Difference between revisions of "GPU Instancer:API Documentation"

From GurBu Wiki
Jump to: navigation, search
 
Line 101: Line 101:
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Starts listening the specified process and runs the given callback function when it finishes. GPU Instancer does not lock Unity updates when initializing instances and instead, does this in a background process.  Each prototype will show on the terrain upon its own initialization. Use this method to get notified when all prototypes are initialized. The most common usage for this is to show a loading bar. For an example, see: DetailDemoSceneController"/><br><br><br><br>
+
Starts listening the specified process and runs the given callback function when it finishes. GPU Instancer does not lock Unity updates when initializing instances and instead, does this in a background process.  Each prototype will show on the terrain upon its own initialization. Use this method to get notified when all prototypes are initialized. The most common usage for this is to show a loading bar. For an example, see: DetailDemoSceneController<br><br><br><br>
  
 
==== StopListeningGPUIEvent ====
 
==== StopListeningGPUIEvent ====
Line 112: Line 112:
 
!colspan="2" | Parameters
 
!colspan="2" | Parameters
 
|-
 
|-
| <code>'''eventType'''</code> || The event type that was registered with StartListeningGPUIEvent"/>
+
| <code>'''eventType'''</code> || The event type that was registered with StartListeningGPUIEvent
 
|-
 
|-
| <code>'''callback'''</code> || The callback function that was registered with StartListeningGPUIEvent"/>
+
| <code>'''callback'''</code> || The callback function that was registered with StartListeningGPUIEvent
 
|}
 
|}
 
<br>
 
<br>
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Stops listening the specified process and unregisters the given callback function that was registered with StartListeningGPUIEvent"/>. Use this in your callback function to unregister it (e.g. after hiding the loading bar). For an example, see: DetailDemoSceneController"/><br><br><br><br>
+
Stops listening the specified process and unregisters the given callback function that was registered with StartListeningGPUIEvent. Use this in your callback function to unregister it (e.g. after hiding the loading bar). For an example, see: DetailDemoSceneController<br><br><br><br>
  
 
==== SetGlobalPositionOffset ====
 
==== SetGlobalPositionOffset ====
Line 347: Line 347:
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Registers a list of prefab instances with GPU Instancer. You must use InitializeGPUInstancer"/> after registering these prefabs for final initialization. The prefabs of the instances in this list must be previously defined in the given manager (either at runtime or editor time).<br><br><br><br>
+
Registers a list of prefab instances with GPU Instancer. You must use InitializeGPUInstancer after registering these prefabs for final initialization. The prefabs of the instances in this list must be previously defined in the given manager (either at runtime or editor time).<br><br><br><br>
  
 
==== UnregisterPrefabInstanceList ====
 
==== UnregisterPrefabInstanceList ====
Line 365: Line 365:
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Unregisters a list of prefab instances from GPU Instancer. You must use InitializeGPUInstancer"/> after unregistering these prefabs for final initialization. The prefabs of the instances in this list must be previously defined in the given manager (either at runtime or editor time).<br><br><br><br>
+
Unregisters a list of prefab instances from GPU Instancer. You must use InitializeGPUInstancer after unregistering these prefabs for final initialization. The prefabs of the instances in this list must be previously defined in the given manager (either at runtime or editor time).<br><br><br><br>
  
 
==== ClearRegisteredPrefabInstances ====
 
==== ClearRegisteredPrefabInstances ====
Line 417: Line 417:
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Adds a new prefab instance for GPU instancing to an already initialized list of registered instances.  Use this if you want to add another instance of a prefab after you have initialized a list of prefabs with InitializeGPUInstancer"/>. The prefab of this instance must be previously defined in the given manager (either at runtime or editor time). Note that the prefab must be enabled for adding and removal in the manager in order for this to work (for performance reasons). Also note that the number of total instances is limited by the count of already initialized instances plus the extra amount you define in the manager.<br><br><br><br>
+
Adds a new prefab instance for GPU instancing to an already initialized list of registered instances.  Use this if you want to add another instance of a prefab after you have initialized a list of prefabs with InitializeGPUInstancer. The prefab of this instance must be previously defined in the given manager (either at runtime or editor time). Note that the prefab must be enabled for adding and removal in the manager in order for this to work (for performance reasons). Also note that the number of total instances is limited by the count of already initialized instances plus the extra amount you define in the manager.<br><br><br><br>
  
 
==== RemovePrefabInstance ====
 
==== RemovePrefabInstance ====
 
----
 
----
 
<br>
 
<br>
<code>public static void '''RemovePrefabInstance'''(GPUInstancerPrefabManager '''manager''', GPUInstancerPrefab '''prefabInstance''')</code>
+
<code>public static void '''RemovePrefabInstance'''(GPUInstancerPrefabManager '''manager''', GPUInstancerPrefab '''prefabInstance''', bool '''setRenderersEnabled''' = true)</code>
 
<br><br>
 
<br><br>
 
{| class="wikitable"
 
{| class="wikitable"
Line 431: Line 431:
 
|-
 
|-
 
| <code>'''prefabInstance'''</code> || The prefab instance to remove.
 
| <code>'''prefabInstance'''</code> || The prefab instance to remove.
 +
|-
 +
| <code>'''setRenderersEnabled'''</code> || If set to false Mesh Renderer components will not be enabled after removing prefab instance which will make the instance invisible.
 
|}
 
|}
 
<br>
 
<br>
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Removes a prefab instance from an already initialized list of registered instances.  Use this if you want to remove a prefab instance after you have initialized a list of prefabs with InitializeGPUInstancer"/> (usually before destroying the GameObject). The prefab of this instance must be previously defined in the given manager (either at runtime or editor time). Note that the prefab must be enabled for adding and removal in the manager in order for this to work (for performance reasons).<br><br><br><br>
+
Removes a prefab instance from an already initialized list of registered instances.  Use this if you want to remove a prefab instance after you have initialized a list of prefabs with InitializeGPUInstancer  (usually before destroying the GameObject). The prefab of this instance must be previously defined in the given manager (either at runtime or editor time). Note that the prefab must be enabled for adding and removal in the manager in order for this to work (for performance reasons).<br><br><br><br>
  
 
==== DisableIntancingForInstance ====
 
==== DisableIntancingForInstance ====
 
----
 
----
 
<br>
 
<br>
<code>public static void '''DisableIntancingForInstance'''(GPUInstancerPrefabManager '''manager''', GPUInstancerPrefab '''prefabInstance''')</code>
+
<code>public static void '''DisableIntancingForInstance'''(GPUInstancerPrefabManager '''manager''', GPUInstancerPrefab '''prefabInstance''', bool '''setRenderersEnabled''' = true)</code>
 
<br><br>
 
<br><br>
 
{| class="wikitable"
 
{| class="wikitable"
Line 449: Line 451:
 
|-
 
|-
 
| <code>'''prefabInstance'''</code> || The prefab instance to disable the GPU Instancing of.
 
| <code>'''prefabInstance'''</code> || The prefab instance to disable the GPU Instancing of.
 +
|-
 +
| <code>'''setRenderersEnabled'''</code> || If set to false Mesh Renderer components will not be enabled after disabling instancing which will make the instance invisible.
 
|}
 
|}
 
<br>
 
<br>
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Disables GPU instancing and enables Unity renderers for the given prefab instance without removing it from the list of registerd prefabs. Use this if you want to pause GPU Instancing for a prefab (e.g. to enable physics). Note that the prefab must be enabled for runtime modifications in the manager in order for this to work (for performance reasons). Also note that you can also add GPUInstancerModificationCollider"/> to a game object to use its collider to automatically  enable/disable instancing when a prefab instance enters/exits its collider.<br><br><br><br>
+
Disables GPU instancing and enables Unity renderers for the given prefab instance without removing it from the list of registerd prefabs. Use this if you want to pause GPU Instancing for a prefab (e.g. to enable physics). Note that the prefab must be enabled for runtime modifications in the manager in order for this to work (for performance reasons). Also note that you can also add GPUInstancerModificationCollider to a game object to use its collider to automatically  enable/disable instancing when a prefab instance enters/exits its collider.<br><br><br><br>
  
 
==== EnableInstancingForInstance ====
 
==== EnableInstancingForInstance ====
 
----
 
----
 
<br>
 
<br>
<code>public static void '''EnableInstancingForInstance'''(GPUInstancerPrefabManager '''manager''', GPUInstancerPrefab '''prefabInstance''')</code>
+
<code>public static void '''EnableInstancingForInstance'''(GPUInstancerPrefabManager '''manager''', GPUInstancerPrefab '''prefabInstance''', bool setRenderersDisabled = true)</code>
 
<br><br>
 
<br><br>
 
{| class="wikitable"
 
{| class="wikitable"
Line 467: Line 471:
 
|-
 
|-
 
| <code>'''prefabInstance'''</code> || The prefab instance to enable the GPU Instancing of.
 
| <code>'''prefabInstance'''</code> || The prefab instance to enable the GPU Instancing of.
 +
|-
 +
| <code>'''disableMeshRenderers'''</code> || If set to false Mesh Renderer components will not be disabled after enabling instancing. Should be used only for instances that have already disabled mesh renderers to speed up the process.
 
|}
 
|}
 
<br>
 
<br>
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Enables GPU instancing and disables Unity renderers for the given prefab instance without re-adding it to the list of registerd prefabs. Use this if you want to unpause GPU Instancing for a prefab. Note that the prefab must be enabled for runtime modifications in the manager in order for this to work (for performance reasons). Also note that you can also add GPUInstancerModificationCollider"/> to a game object to use its collider to automatically  enable/disable instancing when a prefab instance enters/exits its collider.<br><br><br><br>
+
Enables GPU instancing and disables Unity renderers for the given prefab instance without re-adding it to the list of registerd prefabs. Use this if you want to unpause GPU Instancing for a prefab. Note that the prefab must be enabled for runtime modifications in the manager in order for this to work (for performance reasons). Also note that you can also add GPUInstancerModificationCollider to a game object to use its collider to automatically  enable/disable instancing when a prefab instance enters/exits its collider.<br><br><br><br>
  
 
==== UpdateTransformDataForInstance ====
 
==== UpdateTransformDataForInstance ====
Line 511: Line 517:
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Specifies a variation buffer for a GPU Instancer prototype that is defined in the prefab's shader. Required to use AddVariation{T}"/> Use this if you want any type of variation between this prototype's instances. To define the buffer necessary for this variation in your shader, you need to create a StructuredBuffer field of the relevant type in that shader.  You can then access this buffer with "gpuiTransformationMatrix[unity_InstanceID]" see ColorVariations"/> and its demo scene for an example<br><br><br><br>
+
Specifies a variation buffer for a GPU Instancer prototype that is defined in the prefab's shader. Required to use AddVariation{T} Use this if you want any type of variation between this prototype's instances. To define the buffer necessary for this variation in your shader, you need to create a StructuredBuffer field of the relevant type in that shader.  You can then access this buffer with "gpuiTransformationMatrix[unity_InstanceID]" see ColorVariations and its demo scene for an example<br><br><br><br>
  
 
==== AddVariation<T> ====
 
==== AddVariation<T> ====
Line 533: Line 539:
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Sets the variation value for this prefab instance. The variation buffer for the prototype must be defined  with DefinePrototypeVariationBuffer{T}"/> before using this.<br><br><br><br>
+
Sets the variation value for this prefab instance. The variation buffer for the prototype must be defined  with DefinePrototypeVariationBuffer{T} before using this.<br><br><br><br>
  
 
==== UpdateVariation<T> ====
 
==== UpdateVariation<T> ====
Line 557: Line 563:
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Updates the variation value for this prefab instance. The variation buffer for the prototype must be defined  with DefinePrototypeVariationBuffer{T}"/> before using this.<br><br><br><br>
+
Updates the variation value for this prefab instance. The variation buffer for the prototype must be defined  with DefinePrototypeVariationBuffer{T} before using this.<br><br><br><br>
  
 
==== DefineAndAddVariationFromArray<T> ====
 
==== DefineAndAddVariationFromArray<T> ====
Line 586: Line 592:
 
----
 
----
 
<br>
 
<br>
<code>public static void '''UpdateVariationFromArray<'''T'''>'''(GPUInstancerPrefabManager '''manager''', GPUInstancerPrefabPrototype '''prototype''', string '''bufferName''', '''T'''[] '''variationArray''')</code>
+
<code>public static void '''UpdateVariationFromArray<'''T'''>'''(GPUInstancerPrefabManager '''manager''', GPUInstancerPrefabPrototype '''prototype''', string '''bufferName''', '''T'''[] '''variationArray''',int '''arrayStartIndex''' = 0, int '''bufferStartIndex''' = 0, int '''count''' = 0)</code>
 
<br><br>
 
<br><br>
 
{| class="wikitable"
 
{| class="wikitable"
Line 601: Line 607:
 
|-
 
|-
 
| <code>'''variationArray'''</code> || The array that stores the variation information.
 
| <code>'''variationArray'''</code> || The array that stores the variation information.
 +
|-
 +
| <code>'''arrayStartIndex'''</code> || Start index of the given array that the data will be uploaded to the buffer
 +
|-
 +
| <code>'''bufferStartIndex'''</code> || Start index of the buffer to set the data from the array
 +
|-
 +
| <code>'''count'''</code> || Total number of variation data to set to the buffer from the array
 
|}
 
|}
 
<br>
 
<br>
Line 630: Line 642:
 
----
 
----
 
<br>
 
<br>
<code>public static void '''UpdateVisibilityBufferWithMatrix4x4Array'''(GPUInstancerPrefabManager '''prefabManager''', GPUInstancerPrefabPrototype '''prototype''', Matrix4x4[] '''matrix4x4Array''')</code>
+
<code>public static void '''UpdateVisibilityBufferWithMatrix4x4Array'''(GPUInstancerPrefabManager '''prefabManager''', GPUInstancerPrefabPrototype '''prototype''', Matrix4x4[] '''matrix4x4Array''',int '''arrayStartIndex''' = 0, int '''bufferStartIndex''' = 0, int '''count''' = 0)</code>
 
<br><br>
 
<br><br>
 
{| class="wikitable"
 
{| class="wikitable"
Line 641: Line 653:
 
|-
 
|-
 
| <code>'''matrix4x4Array'''</code> || Array of Matrix4x4 that store the transform data of prefab instances
 
| <code>'''matrix4x4Array'''</code> || Array of Matrix4x4 that store the transform data of prefab instances
 +
|-
 +
| <code>'''arrayStartIndex'''</code> || Start index of the given array that the data will be uploaded to the buffer
 +
|-
 +
| <code>'''bufferStartIndex'''</code> || Start index of the buffer to set the data from the array
 +
|-
 +
| <code>'''count'''</code> || Total number of matrices to set to the buffer from the array
 
|}
 
|}
 
<br>
 
<br>
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Use this method to update transform data of all prefab instances with a Matrix4x4 array<br><br><br><br>
+
Use this method to update transform data of all prefab instances with a Matrix4x4 array. By default all the data from the array will be uploaded to the GPU. You can make partial uploads by setting the arrayStartIndex, bufferStartIndex, and count parameters.<br><br><br><br>
  
 
==== DefineGameObjectAsPrefabPrototypeAtRuntime ====
 
==== DefineGameObjectAsPrefabPrototypeAtRuntime ====
Line 741: Line 759:
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Sets the Unity terrain to the GPU Instancer manager and generates the instance prototypes from Unity detail  prototypes that are defined on the given Unity terrain component. Use this to initialize the GPU Instancer detail manager if you want to generate your terrain at runtime.  See TerrainGenerator"/> and its demo scene for an example.<br><br><br><br>
+
Sets the Unity terrain to the GPU Instancer manager and generates the instance prototypes from Unity detail  prototypes that are defined on the given Unity terrain component. Use this to initialize the GPU Instancer detail manager if you want to generate your terrain at runtime.  See TerrainGenerator and its demo scene for an example.<br><br><br><br>
  
  
Line 763: Line 781:
 
'''Description:'''
 
'''Description:'''
 
<br><br>
 
<br><br>
Updates and synchronizes the GPU Instancer detail prototypes with the modifications made in the manager at runtime. Use this if you want to make changes to the detail prototypes at runtime. Prototypes in the manager must be modified before using this. For example usages, see: DetailDemoSceneController"/> and TerrainGenerator"/><br><br><br><br>
+
Updates and synchronizes the GPU Instancer detail prototypes with the modifications made in the manager at runtime. Use this if you want to make changes to the detail prototypes at runtime. Prototypes in the manager must be modified before using this. For example usages, see: DetailDemoSceneController and TerrainGenerator<br><br><br><br>
  
 
==== GetDetailMapData ====
 
==== GetDetailMapData ====

Latest revision as of 11:35, 12 June 2019

About | Crowd Animations | Features | Getting Started | Terminology | Best Practices | API Documentation | F.A.Q.


You can use the GPU Instancer API to manage your instanced Prefabs at runtime smoothly through scripting. All the API methods are designed to be straightforward and to allow you to tap into the GPUI rendering pipeline. Using this API, you can enable/disable instancing per instance basis, add and remove instances, update transform matrices, use material variations, have a no-GameObject workflow and much more. In this page, you will find detailed information on all the GPU Instancer API methods and their parameters.


All API methods and descriptions can be found in GPUInstancer/Scripts/API/GPUInstancerAPI.cs


Please also note that you need to reference the GPUInstancer Namespace to use the API methods with: using GPUInstancer;




Global


InitializeGPUInstancer



public static void InitializeGPUInstancer(GPUInstancerManager manager, bool forceNew = true)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
forceNew If set to false the manager will not run initialization if it was already initialized before


Description:

Main GPU Instancer initialization Method. Generates the necessary GPUInstancer runtime data from predifined GPU Instancer prototypes that are registered in the manager, and generates all necessary GPU buffers for instancing. Use this as the final step after you setup a GPU Instancer manager and all its prototypes. Note that you can also use this to re-initialize the GPU Instancer prototypes that are registered in the manager at runtime.



SetCamera



public static void SetCamera(GPUInstancerManager manager, Camera camera)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
camera The camera that GPU Instancer will use.


Description:

Sets the active camera for a specific manager. This camera is used by GPU Instancer for various calculations (including culling operations). Use this right after you add or change your camera at runtime.



SetCamera



public static void SetCamera(Camera camera)

Parameters
camera The camera that GPU Instancer will use.


Description:

Sets the active camera for all managers. This camera is used by GPU Instancer for various calculations (including culling operations). Use this right after you add or change your camera at runtime.



GetActiveManagers



public static List<GPUInstancerManager> GetActiveManagers()

Parameters


Description:

Returns a list of active managers. Use this if you want to access the managers at runtime.



StartListeningGPUIEvent



public static void StartListeningGPUIEvent(GPUInstancerEventType eventType, UnityAction callback)

Parameters
eventType The event type that will be listened for callback
callback The callback function to run upon initialization completion. Can be any function that doesn't take any parameters.


Description:

Starts listening the specified process and runs the given callback function when it finishes. GPU Instancer does not lock Unity updates when initializing instances and instead, does this in a background process. Each prototype will show on the terrain upon its own initialization. Use this method to get notified when all prototypes are initialized. The most common usage for this is to show a loading bar. For an example, see: DetailDemoSceneController



StopListeningGPUIEvent



public static void StopListeningGPUIEvent(GPUInstancerEventType eventType, UnityAction callback)

Parameters
eventType The event type that was registered with StartListeningGPUIEvent
callback The callback function that was registered with StartListeningGPUIEvent


Description:

Stops listening the specified process and unregisters the given callback function that was registered with StartListeningGPUIEvent. Use this in your callback function to unregister it (e.g. after hiding the loading bar). For an example, see: DetailDemoSceneController



SetGlobalPositionOffset



public static void SetGlobalPositionOffset(GPUInstancerManager manager, Vector3 offsetPosition)

Parameters
manager GPUI Manager to apply the offset
offsetPosition Offset Position


Description:

Updates all transform values in GPU memory with the given offset position.



RemoveInstancesInsideBounds



public static void RemoveInstancesInsideBounds(GPUInstancerManager manager, Bounds bounds, float offset = 0, List<GPUInstancerPrototype> prototypeFilter = null)

Parameters
manager GPUI Manager to remove the instances from
bounds Bounds that define the area that the instances will be removed
offset Adds an offset around the area that the instances will be removed
prototypeFilter If prototypeFilter parameter is given, only the instances of the given prototypes will be removed.


Description:

Removes the instances in GPU memory that are inside bounds.



RemoveInstancesInsideCollider



public static void RemoveInstancesInsideCollider(GPUInstancerManager manager, Collider collider, float offset = 0, List<GPUInstancerPrototype> prototypeFilter = null)

Parameters
manager GPUI Manager to remove the instances from
collider Collider that define the area that the instances will be removed
offset Adds an offset around the area that the instances will be removed
prototypeFilter If prototypeFilter parameter is given, only the instances of the given prototypes will be removed.


Description:

Removes the instances in GPU memory that are inside collider.



GetTransformDataBuffer



public static ComputeBuffer GetTransformDataBuffer(GPUInstancerManager manager, GPUInstancerPrototype prototype)

Parameters
manager GPUI Manager to get the buffer from
prototype Prototype that the buffer belongs to


Description:

[For Advanced Users Only] Returns the float4x4 ComputeBuffer that store the localToWorldMatrix for each instance in GPU memory. This buffer can be used to make modifications in GPU memory before the rendering process.



SetLODBias



public static void SetLODBias(GPUInstancerManager manager, float newLODBias, List<GPUInstancerPrototype> prototypeFilter = null)

Parameters
manager GPUI Manager to adjust the LOD sizes
newLODBias New LODBias value
prototypeFilter If prototypeFilter parameter is given, only the LODBiases of the given prototypes will be changed.


Description:

Changes the LODBias with the given value. Values lower than the LODBias in your Quality Settings will result in higher quality but less performance (e.g. more instances will use LOD0), values higher than the LODBias in your Quality Settings will reduce the quality but increase performance (e.g. less instances will use LOD0)



ChangeMaterial



public static void ChangeMaterial(GPUInstancerManager manager, GPUInstancerPrototype prototype, Material material, int lodLevel = 0, int rendererIndex = 0, int subMeshIndex = 0)

Parameters
manager GPUI Manager
prototype GPUI Prototype
material New material to set on the renderer
lodLevel LOD level
rendererIndex Renderer index on the LOD level
subMeshIndex Submesh index of the renderer


Description:

Can be used to change the material of a prototype at runtime



ChangeMesh



public static void ChangeMesh(GPUInstancerManager manager, GPUInstancerPrototype prototype, Mesh mesh, int lodLevel = 0, int rendererIndex = 0, int subMeshIndex = 0)

Parameters
manager GPUI Manager
prototype GPUI Prototype
mesh New mesh to set on the renderer
lodLevel LOD level
rendererIndex Renderer index on the LOD level
subMeshIndex Submesh index of the renderer


Description:

Can be used to change the mesh of a prototype at runtime



SetInstanceCount



public static void SetInstanceCount(GPUInstancerManager manager, GPUInstancerPrototype prototype, int instanceCount)

Parameters
manager GPUI Manager
prototype GPUI Prototype
instanceCount New instance count to set on the runtime data


Description:

SetInstanceCount can be used to discard instances that are indexed higher than the given index count



GetInstanceDataArray



public static Matrix4x4[] GetInstanceDataArray(GPUInstancerManager manager, GPUInstancerPrototype prototype)

Parameters
manager GPUI Manager
prototype GPUI Prototype


Description:

Returns the array that stores the transform data of the instances



GetPrototypeList



public static List<GPUInstancerPrototype> GetPrototypeList(GPUInstancerManager manager)

Parameters
manager GPUI Manager


Description:

Returns the prototype list of the given GPUI manager




Prefab Instancing


RegisterPrefabInstanceList



public static void RegisterPrefabInstanceList(GPUInstancerPrefabManager manager, IEnumerable<GPUInstancerPrefab> prefabInstanceList)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
prefabInstanceList The list of prefabs instances to GPU instance.


Description:

Registers a list of prefab instances with GPU Instancer. You must use InitializeGPUInstancer after registering these prefabs for final initialization. The prefabs of the instances in this list must be previously defined in the given manager (either at runtime or editor time).



UnregisterPrefabInstanceList



public static void UnregisterPrefabInstanceList(GPUInstancerPrefabManager manager, IEnumerable<GPUInstancerPrefab> prefabInstanceList)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
prefabInstanceList The list of prefabs instances to be removed from GPU instancer.


Description:

Unregisters a list of prefab instances from GPU Instancer. You must use InitializeGPUInstancer after unregistering these prefabs for final initialization. The prefabs of the instances in this list must be previously defined in the given manager (either at runtime or editor time).



ClearRegisteredPrefabInstances



public static void ClearRegisteredPrefabInstances(GPUInstancerPrefabManager manager)

Parameters
manager The manager that defines the prototypes you want to GPU instance.


Description:

Clears the registered prefab instances from the prefab manager.



ClearRegisteredPrefabInstances



public static void ClearRegisteredPrefabInstances(GPUInstancerPrefabManager manager, GPUInstancerPrototype prototype)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
prototype The prototype to clear registered instances for.


Description:

Clears the registered prefab instances from the prefab manager for a specific prototype.



AddPrefabInstance



public static void AddPrefabInstance(GPUInstancerPrefabManager manager, GPUInstancerPrefab prefabInstance)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
prefabInstance The prefab instance to add.


Description:

Adds a new prefab instance for GPU instancing to an already initialized list of registered instances. Use this if you want to add another instance of a prefab after you have initialized a list of prefabs with InitializeGPUInstancer. The prefab of this instance must be previously defined in the given manager (either at runtime or editor time). Note that the prefab must be enabled for adding and removal in the manager in order for this to work (for performance reasons). Also note that the number of total instances is limited by the count of already initialized instances plus the extra amount you define in the manager.



RemovePrefabInstance



public static void RemovePrefabInstance(GPUInstancerPrefabManager manager, GPUInstancerPrefab prefabInstance, bool setRenderersEnabled = true)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
prefabInstance The prefab instance to remove.
setRenderersEnabled If set to false Mesh Renderer components will not be enabled after removing prefab instance which will make the instance invisible.


Description:

Removes a prefab instance from an already initialized list of registered instances. Use this if you want to remove a prefab instance after you have initialized a list of prefabs with InitializeGPUInstancer (usually before destroying the GameObject). The prefab of this instance must be previously defined in the given manager (either at runtime or editor time). Note that the prefab must be enabled for adding and removal in the manager in order for this to work (for performance reasons).



DisableIntancingForInstance



public static void DisableIntancingForInstance(GPUInstancerPrefabManager manager, GPUInstancerPrefab prefabInstance, bool setRenderersEnabled = true)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
prefabInstance The prefab instance to disable the GPU Instancing of.
setRenderersEnabled If set to false Mesh Renderer components will not be enabled after disabling instancing which will make the instance invisible.


Description:

Disables GPU instancing and enables Unity renderers for the given prefab instance without removing it from the list of registerd prefabs. Use this if you want to pause GPU Instancing for a prefab (e.g. to enable physics). Note that the prefab must be enabled for runtime modifications in the manager in order for this to work (for performance reasons). Also note that you can also add GPUInstancerModificationCollider to a game object to use its collider to automatically enable/disable instancing when a prefab instance enters/exits its collider.



EnableInstancingForInstance



public static void EnableInstancingForInstance(GPUInstancerPrefabManager manager, GPUInstancerPrefab prefabInstance, bool setRenderersDisabled = true)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
prefabInstance The prefab instance to enable the GPU Instancing of.
disableMeshRenderers If set to false Mesh Renderer components will not be disabled after enabling instancing. Should be used only for instances that have already disabled mesh renderers to speed up the process.


Description:

Enables GPU instancing and disables Unity renderers for the given prefab instance without re-adding it to the list of registerd prefabs. Use this if you want to unpause GPU Instancing for a prefab. Note that the prefab must be enabled for runtime modifications in the manager in order for this to work (for performance reasons). Also note that you can also add GPUInstancerModificationCollider to a game object to use its collider to automatically enable/disable instancing when a prefab instance enters/exits its collider.



UpdateTransformDataForInstance



public static void UpdateTransformDataForInstance(GPUInstancerPrefabManager manager, GPUInstancerPrefab prefabInstance)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
prefabInstance The prefab instance to update the transform values of. The instance's Unity transform component must be updated beforehand.


Description:

Updates and synchronizes the GPU Instancer transform data (position, rotation and scale) for the given prefab instance. Use this if you want to update, rotate, and/or scale prefab instances after initialization. The updated values are taken directly from the transformation operations made beforehand on the instance's Unity transform component. (These operations will not reflect on the GPU Instanced prefab automatically unless you use this method).



DefinePrototypeVariationBuffer<T>



public static void DefinePrototypeVariationBuffer<T>(GPUInstancerPrefabManager manager, GPUInstancerPrefabPrototype prototype, string bufferName)

Parameters
T The type of variation buffer. Must be defined in the instance prototype's shader
manager The manager that defines the prototypes you want to GPU instance.
prototype The GPU Instancer prototype to define variations.
bufferName The name of the variation buffer in the prototype's shader.


Description:

Specifies a variation buffer for a GPU Instancer prototype that is defined in the prefab's shader. Required to use AddVariation{T} Use this if you want any type of variation between this prototype's instances. To define the buffer necessary for this variation in your shader, you need to create a StructuredBuffer field of the relevant type in that shader. You can then access this buffer with "gpuiTransformationMatrix[unity_InstanceID]" see ColorVariations and its demo scene for an example



AddVariation<T>



public static void AddVariation<T>(GPUInstancerPrefab prefabInstance, string bufferName, T value)

Parameters
T The type of variation buffer. Must be defined in the instance prototype's shader.
prefabInstance The prefab instance to add the variation to.
bufferName The name of the variation buffer in the prototype's shader.
value The value of the variation.


Description:

Sets the variation value for this prefab instance. The variation buffer for the prototype must be defined with DefinePrototypeVariationBuffer{T} before using this.



UpdateVariation<T>



public static void UpdateVariation<T>(GPUInstancerPrefabManager manager, GPUInstancerPrefab prefabInstance, string bufferName, T value)

Parameters
T The type of variation buffer. Must be defined in the instance prototype's shader.
manager The manager that defines the prototypes you want to GPU instance.
prefabInstance The prefab instance to update the variation at.
bufferName The name of the variation buffer in the prototype's shader.
value The value of the variation.


Description:

Updates the variation value for this prefab instance. The variation buffer for the prototype must be defined with DefinePrototypeVariationBuffer{T} before using this.



DefineAndAddVariationFromArray<T>



public static void DefineAndAddVariationFromArray<T>(GPUInstancerPrefabManager manager, GPUInstancerPrefabPrototype prototype, string bufferName, T[] variationArray)

Parameters
T The type of variation buffer. Must be defined in the instance prototype's shader
manager The manager that defines the prototypes you want to GPU instance.
prototype The GPU Instancer prototype to define variations.
bufferName The name of the variation buffer in the prototype's shader.
variationArray The array that stores the variation information.


Description:

Specifies a variation buffer for a GPU Instancer prototype that is defined in the prefab's shader. And sets the variation values for the given array.



UpdateVariationFromArray<T>



public static void UpdateVariationFromArray<T>(GPUInstancerPrefabManager manager, GPUInstancerPrefabPrototype prototype, string bufferName, T[] variationArray,int arrayStartIndex = 0, int bufferStartIndex = 0, int count = 0)

Parameters
T The type of variation buffer. Must be defined in the instance prototype's shader
manager The manager that defines the prototypes you want to GPU instance.
prototype The GPU Instancer prototype to define variations.
bufferName The name of the variation buffer in the prototype's shader.
variationArray The array that stores the variation information.
arrayStartIndex Start index of the given array that the data will be uploaded to the buffer
bufferStartIndex Start index of the buffer to set the data from the array
count Total number of variation data to set to the buffer from the array


Description:

Updates the variation values for the given array for the specified prototype and buffer.



InitializeWithMatrix4x4Array



public static void InitializeWithMatrix4x4Array(GPUInstancerPrefabManager prefabManager, GPUInstancerPrefabPrototype prototype, Matrix4x4[] matrix4x4Array)

Parameters
prefabManager The GPUI Prefab Manager that the prefab prototype is defined on
prototype GPUI Prefab Prototype
matrix4x4Array Array of Matrix4x4 that store the transform data of prefab instances


Description:

Use this method to create prefab instances with the given transform information without creating GameObjects.



UpdateVisibilityBufferWithMatrix4x4Array



public static void UpdateVisibilityBufferWithMatrix4x4Array(GPUInstancerPrefabManager prefabManager, GPUInstancerPrefabPrototype prototype, Matrix4x4[] matrix4x4Array,int arrayStartIndex = 0, int bufferStartIndex = 0, int count = 0)

Parameters
prefabManager The GPUI Prefab Manager that the prefab prototype is defined on
prototype GPUI Prefab Prototype
matrix4x4Array Array of Matrix4x4 that store the transform data of prefab instances
arrayStartIndex Start index of the given array that the data will be uploaded to the buffer
bufferStartIndex Start index of the buffer to set the data from the array
count Total number of matrices to set to the buffer from the array


Description:

Use this method to update transform data of all prefab instances with a Matrix4x4 array. By default all the data from the array will be uploaded to the GPU. You can make partial uploads by setting the arrayStartIndex, bufferStartIndex, and count parameters.



DefineGameObjectAsPrefabPrototypeAtRuntime



public static GPUInstancerPrefabPrototype DefineGameObjectAsPrefabPrototypeAtRuntime(GPUInstancerPrefabManager prefabManager, GameObject prototypeGameObject)

Parameters
prefabManager The GPUI Prefab Manager that the prefab prototype will be defined on
prototypeGameObject GameObject to use as reference for the prototype


Description:

Use this method to define Prefab Prototypes at runtime for procedurally generated GameObjects



InitializeGPUInstancer



public static GPUInstancerRuntimeData InitializeGPUInstancer(GPUInstancerPrefabManager prefabManager, GPUInstancerPrefabPrototype prototype)

Parameters
prefabManager The GPUI Prefab Manager that the prefab prototype is defined on
prefabPrototype GPUI Prefab Prototype


Description:

Initialize single prefab prototype for preparing runtime data and buffers for instanced rendering



AddInstancesToPrefabPrototypeAtRuntime



public static void AddInstancesToPrefabPrototypeAtRuntime(GPUInstancerPrefabManager prefabManager, GPUInstancerPrefabPrototype prefabPrototype, IEnumerable<GameObject> instances)

Parameters
prefabManager The GPUI Prefab Manager that the prefab prototype is defined on
prefabPrototype GPUI Prefab Prototype
instances List of GameObjects to register on the manager


Description:

Use this method to add new instances to prototype when you do not use prefabs (Ex: when you create a prototype with DefineGameObjectAsPrefabPrototypeAtRuntime API method)



RemovePrototypeAtRuntime



public static void RemovePrototypeAtRuntime(GPUInstancerPrefabManager prefabManager, GPUInstancerPrefabPrototype prefabPrototype)

Parameters
prefabManager The GPUI Prefab Manager that the prefab prototype is defined on
prefabPrototype GPUI Prefab Prototype ro remove from the manager


Description:

Use this method to remove a prototype definition at runtime




Detail & Tree Instancing


SetupManagerWithTerrain



public static void SetupManagerWithTerrain(GPUInstancerTerrainManager manager, Terrain terrain)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
terrain


Description:

Sets the Unity terrain to the GPU Instancer manager and generates the instance prototypes from Unity detail prototypes that are defined on the given Unity terrain component. Use this to initialize the GPU Instancer detail manager if you want to generate your terrain at runtime. See TerrainGenerator and its demo scene for an example.




Detail Instancing


UpdateDetailInstances



public static void UpdateDetailInstances(GPUInstancerDetailManager manager, bool updateMeshes = false)

Parameters
manager The manager that defines the prototypes you want to GPU instance.
updateMeshes Whether GPU Instancer should also update meshes. Send this value as "true" if you change properties related to cross quadding, noise spread and/or detail scales


Description:

Updates and synchronizes the GPU Instancer detail prototypes with the modifications made in the manager at runtime. Use this if you want to make changes to the detail prototypes at runtime. Prototypes in the manager must be modified before using this. For example usages, see: DetailDemoSceneController and TerrainGenerator



GetDetailMapData



public static List<int[,]> GetDetailMapData(GPUInstancerDetailManager manager)

Parameters
manager


Description:

Returns a list of 2D array of detail object density for the all the prototypes of the manager.



GetDetailLayer



public static int[,] GetDetailLayer(GPUInstancerDetailManager manager, int layerIndex)

Parameters
manager
layerIndex


Description:

Returns a 2D array of detail object density for the given layer.



SetDetailMapData



public static void SetDetailMapData(GPUInstancerDetailManager manager, List<int[,]> detailMapData)

Parameters
manager
detailMapData


Description:

Can be used to set the Detail Map Data to the Detail Manager before initialization.




Editor Only


SetupShaderForGPUI



public static bool SetupShaderForGPUI(Shader shader)

Parameters
shader Shader to convert


Description:

[EDITOR-ONLY] Shader auto-conversion can be run with this method without using a GPUI Manager



AddShaderVariantToCollection



public static void AddShaderVariantToCollection(Material material)

Parameters
material


Description:

[EDITOR-ONLY] Adds the shader variant used in the given material to the GPUIShaderVariantCollection. This collection is used to include the shader variants with GPUI support in your builds. Normally GPUI Managers makes this automatically, but if you generate your managers at runtime, this method can be usefull to add these shader variants manually.



StartEditorSimulation



public static void StartEditorSimulation(GPUInstancerManager manager)

Parameters
manager GPUI manager to start simulation for


Description:

[EDITOR-ONLY] Starts rendering GPUI instances for the given manager in editor mode. The simulation can be stopped using the StopEditorSimulation method. It will automatically stop when entering Play mode. It is usefull to render instances in Editor Mode while using no-GameObject workflow.



StopEditorSimulation



public static void StopEditorSimulation(GPUInstancerManager manager)

Parameters
manager GPUI manager to stop simulation for


Description:

[EDITOR-ONLY] Stops rendering GPUI instances for the given manager in editor mode. Can be used after StartEditorSimulation method to disable rendering.