GPU Instancer:API Documentation
About | Crowd Animations | Features | Getting Started | Terminology | Best Practices | API Documentation | F.A.Q.
 GPU Instancer Pro is now available (Asset Store page). For documentation of the Pro version, please visit GPU Instancer Pro Documentation.
|
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;
Contents
- 1 Global
- 1.1 InitializeGPUInstancer
- 1.2 SetCamera
- 1.3 SetCamera
- 1.4 GetActiveManagers
- 1.5 StartListeningGPUIEvent
- 1.6 StopListeningGPUIEvent
- 1.7 SetGlobalPositionOffset
- 1.8 SetGlobalMatrixOffset
- 1.9 RemoveInstancesInsideBounds
- 1.10 RemoveInstancesInsideCollider
- 1.11 GetTransformDataBuffer
- 1.12 SetLODBias
- 1.13 ChangeMaterial
- 1.14 ChangeMesh
- 1.15 SetInstanceCount
- 1.16 GetInstanceDataArray
- 1.17 GetInstanceDataNativeArray
- 1.18 GetPrototypeList
- 1.19 ChangeLODShadow
- 1.20 ReleaseInstanceBuffers
- 1.21 ReleaseInstanceBuffers
- 2 Prefab Instancing
- 2.1 RegisterPrefabInstanceList
- 2.2 UnregisterPrefabInstanceList
- 2.3 ClearRegisteredPrefabInstances
- 2.4 ClearRegisteredPrefabInstances
- 2.5 AddPrefabInstance
- 2.6 RemovePrefabInstance
- 2.7 DisableIntancingForInstance
- 2.8 EnableInstancingForInstance
- 2.9 UpdateTransformDataForInstance
- 2.10 DefinePrototypeVariationBuffer<T>
- 2.11 AddVariation<T>
- 2.12 UpdateVariation<T>
- 2.13 DefineAndAddVariationFromArray<T>
- 2.14 DefineAndAddVariationFromArray<T>
- 2.15 UpdateVariationFromArray<T>
- 2.16 UpdateVariationFromArray<T>
- 2.17 InitializeWithMatrix4x4Array
- 2.18 InitializePrototype
- 2.19 UpdateVisibilityBufferWithMatrix4x4Array
- 2.20 UpdateVisibilityBufferWithNativeArray<T>
- 2.21 DefineGameObjectAsPrefabPrototypeAtRuntime
- 2.22 InitializeGPUInstancer
- 2.23 AddInstancesToPrefabPrototypeAtRuntime
- 2.24 RemovePrototypeAtRuntime
- 2.25 ClonePrototypeAtRuntime
- 2.26 AddPrototoypeToManager
- 3 Detail & Tree Instancing
- 4 Detail Instancing
- 5 Tree Instancing
- 6 Editor Only
- 7 Crowd Animator
- 7.1 StartAnimation
- 7.2 StartBlend
- 7.3 SetAnimationWeights
- 7.4 SetAnimationSpeed
- 7.5 SetAnimationSpeeds
- 7.6 GetAnimationTime
- 7.7 SetAnimationTime
- 7.8 SetAnimationSpeedsForPrototype
- 7.9 SetAnimationSpeedsForPrototype
- 7.10 AddAnimationEvent
- 7.11 AddAnimationEvent
- 7.12 ClearAnimationEvents
- 7.13 DefineGameObjectAsCrowdPrototypeAtRuntime
- 7.14 ChangeMaterial
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.
SetGlobalMatrixOffset
public static void SetGlobalMatrixOffset(GPUInstancerManager manager, Matrix4x4 offsetMatrix)
| Parameters | |
|---|---|
manager |
GPUI Manager to apply the offset |
offsetMatrix |
Offset Matrix |
Description:
Updates all transform values in GPU memory with the given offset matrix.
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 |
|---|
Description:
[OBSOLETE]
GetInstanceDataNativeArray
public static NativeArray<Matrix4x4> GetInstanceDataNativeArray(GPUInstancerManager manager, GPUInstancerPrototype prototype)
| Parameters | |
|---|---|
manager |
GPUI Manager |
prototype |
GPUI Prototype |
Description:
Returns the native 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
ChangeLODShadow
public static void ChangeLODShadow(GPUInstancerPrototype prototype, int lodLevel, bool isShadowCasting, int shadowLOD = -1)
| Parameters | |
|---|---|
prototype |
GPUI Prototype |
lodLevel |
LOD level to change the shadow setting |
isShadowCasting |
True if LOD level is shadow casting |
shadowLOD |
(Optional) Provide an LOD level that shadows will be rendered from |
Description:
Changes prototype's shadow LOD setting
ReleaseInstanceBuffers
public static void ReleaseInstanceBuffers(GPUInstancerManager manager)
| Parameters | |
|---|---|
manager |
|
Description:
Releases Compute Buffers for all prototypes defined on the manager
ReleaseInstanceBuffers
public static void ReleaseInstanceBuffers(GPUInstancerManager manager, GPUInstancerPrototype prototype)
| Parameters | |
|---|---|
manager |
|
Description:
Releases Compute Buffers for the given prototype
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, bool autoIncreaseBufferSize = false)
| Parameters | |
|---|---|
manager |
The manager that defines the prototypes you want to GPU instance. |
prefabInstance |
The prefab instance to add. |
autoIncreaseBufferSize |
(Optional) When true, buffer size designated for the prototype will automatically increase when there is not enough space for adding a new instance |
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 "gpui_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 PrefabVariationData<T> 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.
DefineAndAddVariationFromArray<T>
public static PrefabVariationData<T> DefineAndAddVariationFromArray<T>(GPUInstancerPrefabManager manager, GPUInstancerPrefabPrototype prototype, string bufferName, NativeArray<T> variationArray) where T : struct
| 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.
UpdateVariationFromArray<T>
public static void UpdateVariationFromArray<T>(GPUInstancerPrefabManager manager, GPUInstancerPrefabPrototype prototype, string bufferName, NativeArray<T> variationArray, int arrayStartIndex = 0, int bufferStartIndex = 0, int count = 0) where T : struct
| 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.
InitializePrototype
public static void InitializePrototype(GPUInstancerPrefabManager prefabManager, GPUInstancerPrefabPrototype prototype, int bufferSize, int instanceCount = 0)
| Parameters | |
|---|---|
prefabManager |
The GPUI Prefab Manager that the prefab prototype is defined on |
prototype |
GPUI Prefab Prototype |
bufferSize |
Size of the buffer to allocate in GPU memory |
instanceCount |
(Optional) Initial instance count to render. Can also be set later with SetInstanceCount API method |
Description:
Use this method to initialize buffers for the given prototype and set the buffer data later with UpdateVisibilityBuffer API methods. Please note that you will need to provide a positive integer buffer size to initialize the buffers successfully.
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.
UpdateVisibilityBufferWithNativeArray<T>
public static void UpdateVisibilityBufferWithNativeArray<T>(GPUInstancerPrefabManager prefabManager, GPUInstancerPrefabPrototype prototype, NativeArray<T> float4x4Array,int arrayStartIndex = 0, int bufferStartIndex = 0, int count = 0) where T : struct
| Parameters | |
|---|---|
prefabManager |
The GPUI Prefab Manager that the prefab prototype is defined on |
prototype |
GPUI Prefab Prototype |
float4x4Array |
Array of float4x4 that store the transform data of prefab instances. Struct reference is not forced so you can use any float4x4 struct (e.g. Matrix4x4 or float4x4 from Mathematics package) |
arrayStartIndex |
(Optional) Start index of the given array that the data will be uploaded to the buffer |
bufferStartIndex |
(Optional) Start index of the buffer to set the data from the array |
count |
(Optional) 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 float4x4 native 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, bool attachScript = true)
| Parameters | |
|---|---|
prefabManager |
The GPUI Prefab Manager that the prefab prototype will be defined on |
prototypeGameObject |
GameObject to use as reference for the prototype |
attachScript |
(Optional) If false, GPUI will not add the GPUInstancerPrefab component on the prototypeGameObject |
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 to remove from the manager |
Description:
Use this method to remove a prototype definition at runtime
ClonePrototypeAtRuntime
public static GPUInstancerPrefabPrototype ClonePrototypeAtRuntime(GPUInstancerPrefabManager prefabManager, GPUInstancerPrefabPrototype originalPrototype)
| Parameters | |
|---|---|
prefabManager |
The GPUI Prefab Manager that the prefab prototype is defined on |
originalPrototype |
Prototype to copy from |
Description:
Creates a copy of the given prototype. After the changes you want to make to the prototype are completed, you need call InitializePrototype or InitializeWithMatrix4x4Array to create the runtimeData for this prototype
AddPrototoypeToManager
public static void AddPrototoypeToManager(GPUInstancerPrefabManager prefabManager, GPUInstancerPrefabPrototype prototype)
| Parameters | |
|---|---|
prefabManager |
The GPUI Prefab Manager that the prefab prototype will be defined on |
prototype |
Prototype to add |
Description:
Adds a pre-defined prototype to the Prefab Manager. When called at runtime, you need to initialize the runtimedata for this prototype (e.g. by using the InitializePrototype API method).
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.
Tree Instancing
AddTerrainToManager
public static void AddTerrainToManager(GPUInstancerTreeManager manager, Terrain terrain)
| Parameters | |
|---|---|
manager |
The GPUI Tree Manager to add the new terrain |
terrain |
New terrain to render the trees |
Description:
Use this method to add new terrains to Tree Manager at runtime
RemoveTerrainFromManager
public static void RemoveTerrainFromManager(GPUInstancerTreeManager manager, Terrain terrain)
| Parameters | |
|---|---|
manager |
The GPUI Tree Manager to remove the terrain |
terrain |
Terrain to remove |
Description:
Use this method to remove terrains from Tree Manager at runtime
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.
Crowd Animator
StartAnimation
public static void StartAnimation(GPUICrowdPrefab crowdInstance, AnimationClip animationClip, float startTime = -1.0f, float speed = 1.0f, float transitionTime = 0)
| Parameters | |
|---|---|
crowdInstance |
Character that will play the animation clip |
animationClip |
Animation Clip |
startTime |
(Optional) Start time of the animation clip |
speed |
(Optional) Speed of the playing clip |
transitionTime |
(Optional) Time in seconds for smooth transition from the previous animation clips |
Description:
Start the given Animation Clip on the given instance
StartBlend
public static void StartBlend(GPUICrowdPrefab crowdInstance, Vector4 animationWeights, AnimationClip animationClip1, AnimationClip animationClip2, AnimationClip animationClip3 = null, AnimationClip animationClip4 = null, float[] animationTimes = null, float[] animationSpeeds = null, float transitionTime = 0)
| Parameters | |
|---|---|
crowdInstance |
Character that will play the animation clips |
animationWeights |
Weights that will define the blending weights of the given animation clips |
animationClip1 |
Clip 1 |
animationClip2 |
Clip 2 |
animationClip3 |
(Optional) Clip 3 |
animationClip4 |
(Optional) Clip 4 |
animationTimes |
(Optional) Time of the animation clips |
animationSpeeds |
(Optional) Speed of the animation clips |
transitionTime |
(Optional) Time in seconds for smooth transition from the previous animation clips |
Description:
Blend the given Animation Clips and start playing for the given instance
SetAnimationWeights
public static void SetAnimationWeights(GPUICrowdPrefab crowdInstance, Vector4 animationWeights)
| Parameters | |
|---|---|
crowdInstance |
Character to set the speed |
animationWeights |
Animation Weights |
Description:
Set the blend weights of the playing animation blends
SetAnimationSpeed
public static void SetAnimationSpeed(GPUICrowdPrefab crowdInstance, float animationSpeed)
| Parameters | |
|---|---|
crowdInstance |
Character to set the speed |
animationSpeed |
Speed value |
Description:
Set the speed of the playing animation clips
SetAnimationSpeeds
public static void SetAnimationSpeeds(GPUICrowdPrefab crowdInstance, float[] animationSpeeds)
| Parameters | |
|---|---|
crowdInstance |
Character to set the speed |
animationSpeeds |
Speed values |
Description:
Set the speeds for multiple animation clips
GetAnimationTime
public static float GetAnimationTime(GPUICrowdPrefab crowdInstance, AnimationClip animationClip)
| Parameters | |
|---|---|
crowdInstance |
Character to get the time |
animationClip |
The clip to get the time for |
Description:
Returns the current time of the clip
SetAnimationTime
public static void SetAnimationTime(GPUICrowdPrefab crowdInstance, AnimationClip animationClip, float time)
| Parameters | |
|---|---|
crowdInstance |
Character to set the time |
animationClip |
The clip to set the time for |
time |
Time in seconds |
Description:
Sets the current time of the clip
SetAnimationSpeedsForPrototype
public static void SetAnimationSpeedsForPrototype(GPUICrowdManager crowdManager, GPUICrowdPrototype crowdPrototype, float animationSpeed)
| Parameters | |
|---|---|
crowdManager |
Crowd Manager that the prototype is defined on |
crowdPrototype |
Crowd Prototype |
animationSpeed |
Speed value |
Description:
Set the animation speed for all instances of the given prototype
SetAnimationSpeedsForPrototype
public static void SetAnimationSpeedsForPrototype(GPUICrowdManager crowdManager, GPUICrowdPrototype crowdPrototype, float[] animationSpeeds)
| Parameters | |
|---|---|
crowdManager |
Crowd Manager that the prototype is defined on |
crowdPrototype |
Crowd Prototype |
animationSpeeds |
Speed values |
Description:
Set the animation speeds for multiple clips for all instances of the given prototype
AddAnimationEvent
public static void AddAnimationEvent(GPUICrowdManager crowdManager, GPUICrowdPrototype crowdPrototype, AnimationClip animationClip, int eventFrame,UnityAction<GPUICrowdPrefab, float, int, string> eventAction, float floatParam = 0, int intParam = 0, string stringParam = null)
| Parameters | |
|---|---|
crowdManager |
Crowd Manager that the prototype is defined on |
crowdPrototype |
Crowd Prototype |
animationClip |
The clip to attach the event |
eventFrame |
Frame of the animation on which the event will take place |
eventAction |
UnityAction that will be invoked at the given frame for the given clip |
floatParam |
(Optional) Float parameter value |
intParam |
(Optional) Integer parameter value |
stringParam |
(Optional) String parameter value |
Description:
Add an event to an animation clip of a prototype
AddAnimationEvent
public static void AddAnimationEvent(GPUICrowdManager crowdManager, GPUIAnimationEvent animationEvent)
| Parameters | |
|---|---|
crowdManager |
|
animationEvent |
|
Description:
Add an event to the manager using GPUIAnimationEvent class properties
ClearAnimationEvents
public static void ClearAnimationEvents(GPUICrowdManager crowdManager, GPUICrowdPrototype crowdPrototype)
| Parameters | |
|---|---|
crowdManager |
Crowd Manager that the prototype is defined on |
crowdPrototype |
Crowd Prototype |
Description:
Removes all animation events for the given prototype
DefineGameObjectAsCrowdPrototypeAtRuntime
public static GPUICrowdPrototype DefineGameObjectAsCrowdPrototypeAtRuntime(GPUICrowdManager crowdManager, GameObject prototypeGameObject, GPUICrowdAnimationData animationData)
| 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 Crowd Prototypes at runtime for procedurally generated GameObjects
ChangeMaterial
public static void ChangeMaterial(GPUICrowdManager crowdManager, GPUInstancerPrototype prototype, Material material, int lodLevel = 0, int rendererIndex = 0, int subMeshIndex = 0)
| Parameters | |
|---|---|
crowdManager |
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
