GPU Instancer Pro:APIDocumentation
About GPU Instance Pro | Getting Started | Terminology | Best Practices | API Documentation | F.A.Q. | Support
You can use the GPUI API to manage your instanced objects 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 and terrains, update transform matrices and much more. In this page, you will find detailed information on all the API methods and their parameters.
Please also note that you need to reference the GPUInstancerPro namespaces to use the API methods with: using GPUInstancerPro; or using GPUInstancerPro.PrefabModule; or using GPUInstancerPro.TerrainModule;
API methods are static methods and can be invoked with the class name, such as: GPUICoreAPI.RegisterRenderer or GPUIPrefabAPI.AddPrefabInstance or GPUITerrainAPI.AddTerrain
Contents
- 1 GPUInstancerPro.GPUICoreAPI
- 1.1 InitializeRenderingSystem
- 1.2 RegenerateRenderers
- 1.3 UpdateParameterBufferData
- 1.4 DisposeAll
- 1.5 RegisterRenderer
- 1.6 RegisterRenderer
- 1.7 RegisterRenderer
- 1.8 DisposeRenderer
- 1.9 SetTransformBufferData
- 1.10 SetTransformBufferData
- 1.11 SetTransformBufferData
- 1.12 TryGetTransformBuffer
- 1.13 TryGetTransformBuffer
- 1.14 SetBufferSize
- 1.15 SetInstanceCount
- 1.16 AddMaterialPropertyOverride
- 1.17 AddMaterialPropertyOverride
- 1.18 AddPrototype
- 1.19 AddPrototype
- 1.20 AddCameraEventOnPreCull
- 1.21 RemoveCameraEventOnPreCull
- 1.22 AddCameraEventOnPreRender
- 1.23 RemoveCameraEventOnPreRender
- 1.24 AddCameraEventOnPostRender
- 1.25 RemoveCameraEventOnPostRender
- 2 GPUInstancerPro.PrefabModule.GPUIPrefabAPI
- 3 GPUInstancerPro.TerrainModule.GPUITerrainAPI
GPUInstancerPro.GPUICoreAPI
InitializeRenderingSystem
public static void InitializeRenderingSystem()
| Parameters |
|---|
Description:
GPU Instancer Pro features a centralized rendering system, allowing for efficient rendering of objects with minimal draw calls and compute shader calculations. When GPUI rendering starts, either through GPUI Managers or API calls, the Rendering System is automatically initialized. However, you can also use this API method to initialize it manually.
RegenerateRenderers
public static void RegenerateRenderers()
| Parameters |
|---|
Description:
The Rendering System generates internal renderers and buffers based on the prototype information, such as MeshRenderers on a prefab. When there are changes to the renderers of a prototype, such as meshes or materials, it may be necessary to update the internal renderer setup using the RegenerateRenderers method.
UpdateParameterBufferData
public static void UpdateParameterBufferData()
| Parameters |
|---|
Description:
The Rendering System maintains various parameters such as renderer and profile settings inside a GPU buffer. When there are changes to these settings, the parameter buffer needs to be updated with the new values. For example, when the LODBias setting under the QualitySettings is changed, you need to call the UpdateParameterBufferData method for the changes to take effect for GPUI renders.
DisposeAll
public static void DisposeAll()
| Parameters |
|---|
Description:
When the DisposeAll method is called, all the runtime data related to GPUI rendering will be deleted, the allocated GPU buffers will be disposed of, and the GPUI Rendering System instance will be destroyed.
RegisterRenderer
public static bool RegisterRenderer(UnityEngine.Object source, GameObject prefab, out int rendererKey)
| Parameters | |
|---|---|
source |
The source responsible for registering the renderer. E.g. the MonoBehaviour class |
prefab |
GameObject that the renderers will be based on |
rendererKey |
Integer key output that uniquely identifies the renderer |
Description:
The RegisterRenderer method is used to set up GPUI renderers for the specified GameObject. This method needs to be called to produce a renderKey, which can then be used with the SetTransformBufferData method to start rendering instances with the given transform matrices. To stop the rendering, the DisposeRenderer method should be called with the rendererKey output.
RegisterRenderer
public static bool RegisterRenderer(UnityEngine.Object source, GameObject prefab, GPUIProfile profile, out int rendererKey)
| Parameters | |
|---|---|
source |
The source responsible for registering the renderer. E.g. the MonoBehaviour class |
prefab |
GameObject that the renderers will be based on |
profile |
GPUIProfile that determines various rendering settings |
rendererKey |
Integer key output that uniquely identifies the renderer |
Description:
The RegisterRenderer method is used to set up GPUI renderers for the specified GameObject. This method needs to be called to produce a renderKey, which can then be used with the SetTransformBufferData method to start rendering instances with the given transform matrices. To stop the rendering, the DisposeRenderer method should be called with the rendererKey output.
RegisterRenderer
public static bool RegisterRenderer(UnityEngine.Object source, GPUIPrototype prototype, out int rendererKey)
| Parameters | |
|---|---|
source |
The source responsible for registering the renderer. E.g. the MonoBehaviour class |
prototype |
GPUIPrototype that the renderers will be based on |
rendererKey |
Integer key output that uniquely identifies the renderer |
Description:
The RegisterRenderer method is used to set up GPUI renderers for the specified GameObject. This method needs to be called to produce a renderKey, which can then be used with the SetTransformBufferData method to start rendering instances with the given transform matrices. To stop the rendering, the DisposeRenderer method should be called with the rendererKey output.
DisposeRenderer
public static void DisposeRenderer(int rendererKey)
| Parameters | |
|---|---|
rendererKey |
Integer key that uniquely identifies the renderer |
Description:
Disposes the renderer data previously defined with the RegisterRenderer method.
SetTransformBufferData
public static bool SetTransformBufferData(int rendererKey, NativeArray<Matrix4x4> matrices, int managedBufferStartIndex = 0, int graphicsBufferStartIndex = 0, int count = 0)
| Parameters | |
|---|---|
rendererKey |
Integer key that uniquely identifies the renderer. |
matrices |
Matrix4x4 collection that store the transform data of instances. |
managedBufferStartIndex |
(Optional)The first element index in matrices to copy to the graphics buffer. |
graphicsBufferStartIndex |
(Optional)The first element index in the graphics buffer to receive the data. |
count |
(Optional)The number of elements to copy. |
Description:
Sets the transform matrix data to a renderer previously defined with the RegisterRenderer method.
SetTransformBufferData
public static bool SetTransformBufferData(int rendererKey, Matrix4x4[] matrices, int managedBufferStartIndex = 0, int graphicsBufferStartIndex = 0, int count = 0)
| Parameters | |
|---|---|
rendererKey |
Integer key that uniquely identifies the renderer. |
matrices |
Matrix4x4 collection that store the transform data of instances. |
managedBufferStartIndex |
(Optional)The first element index in matrices to copy to the graphics buffer. |
graphicsBufferStartIndex |
(Optional)The first element index in the graphics buffer to receive the data. |
count |
(Optional)The number of elements to copy. |
Description:
Sets the transform matrix data to a renderer previously defined with the RegisterRenderer method.
SetTransformBufferData
public static bool SetTransformBufferData(int rendererKey, List<Matrix4x4> matrices, int managedBufferStartIndex = 0, int graphicsBufferStartIndex = 0, int count = 0)
| Parameters | |
|---|---|
rendererKey |
Integer key that uniquely identifies the renderer. |
matrices |
Matrix4x4 collection that store the transform data of instances. |
managedBufferStartIndex |
(Optional)The first element index in matrices to copy to the graphics buffer. |
graphicsBufferStartIndex |
(Optional)The first element index in the graphics buffer to receive the data. |
count |
(Optional)The number of elements to copy. |
Description:
Sets the transform matrix data to a renderer previously defined with the RegisterRenderer method.
TryGetTransformBuffer
public static bool TryGetTransformBuffer(int rendererKey, out GraphicsBuffer transformBuffer, out int bufferStartIndex)
| Parameters | |
|---|---|
rendererKey |
Integer key that uniquely identifies the renderer. |
transformBuffer |
Graphics buffer that contains the Matrix4x4 data for instances. |
bufferStartIndex |
Start index for instances for the given render key on the GraphicsBuffer. |
Description:
Outputs the GraphicsBuffer that contains the Matrix4x4 data for instances.
TryGetTransformBuffer
public static bool TryGetTransformBuffer(int rendererKey, out GraphicsBuffer transformBuffer, out int bufferStartIndex, out int bufferSize)
| Parameters | |
|---|---|
rendererKey |
Integer key that uniquely identifies the renderer. |
transformBuffer |
Graphics buffer that contains the Matrix4x4 data for instances. |
bufferStartIndex |
Start index for instances for the given render key on the GraphicsBuffer. |
bufferSize |
Total size for instances for the given render key on the GraphicsBuffer. |
Description:
Outputs the GraphicsBuffer that contains the Matrix4x4 data for instances.
SetBufferSize
public static bool SetBufferSize(int rendererKey, int bufferSize)
| Parameters | |
|---|---|
rendererKey |
Integer key that uniquely identifies the renderer. |
bufferSize |
Size of the buffer to allocate in GPU memory. |
Description:
Sets the transform data buffer size to a renderer previously defined with the RegisterRenderer method.
SetInstanceCount
public static bool SetInstanceCount(int rendererKey, int instanceCount)
| Parameters | |
|---|---|
rendererKey |
Integer key that uniquely identifies the renderer. |
instanceCount |
Number of instances to be processed. |
Description:
Sets the number of instances currently rendered for a renderer previously defined with the RegisterRenderer method.
AddMaterialPropertyOverride
public static void AddMaterialPropertyOverride(int rendererKey, string propertyName, object propertyValue, int lodIndex = -1, int rendererIndex = -1)
| Parameters | |
|---|---|
rendererKey |
Integer key that uniquely identifies the renderer |
propertyName |
The name of the property |
propertyValue |
The value of the property |
lodIndex |
(Optional)LOD |
rendererIndex |
(Optional)The renderer index on the LOD |
Description:
AddMaterialPropertyOverride methods lets you add or change properties on the MaterialPropertyBlock that is used for the draw calls.
AddMaterialPropertyOverride
public static void AddMaterialPropertyOverride(int rendererKey, int nameID, object propertyValue, int lodIndex = -1, int rendererIndex = -1)
| Parameters | |
|---|---|
rendererKey |
Integer key that uniquely identifies the renderer |
nameID |
The name ID of the property retrieved by Shader.PropertyToID |
propertyValue |
The value of the property |
lodIndex |
(Optional)LOD |
rendererIndex |
(Optional)The renderer index on the LOD |
Description:
AddMaterialPropertyOverride methods lets you add or change properties on the MaterialPropertyBlock that is used for the draw calls.
AddPrototype
public static int AddPrototype(GPUIManager gpuiManager, GPUIPrototype prototype)
| Parameters | |
|---|---|
gpuiManager |
|
prototype |
|
Description:
Adds the prototype to the GPUI Manager.
AddPrototype
public static int AddPrototype(GPUIManager gpuiManager, GameObject prefab)
| Parameters | |
|---|---|
gpuiManager |
|
prefab |
|
Description:
Adds the given GameObject as a prototype to the GPUI Manager.
AddCameraEventOnPreCull
public static void AddCameraEventOnPreCull(UnityAction<GPUICameraData> cameraEvent)
| Parameters | |
|---|---|
cameraEvent |
Action that will be executed for each camera |
Description:
Adds a method to execute before each camera's visibility calculations.
RemoveCameraEventOnPreCull
public static void RemoveCameraEventOnPreCull(UnityAction<GPUICameraData> cameraEvent)
| Parameters | |
|---|---|
cameraEvent |
Action that is previously added with the AddCameraEvent method |
Description:
Removes the method previously added with the AddCameraEventOnPreCull method.
AddCameraEventOnPreRender
public static void AddCameraEventOnPreRender(UnityAction<GPUICameraData> cameraEvent)
| Parameters | |
|---|---|
cameraEvent |
Action that will be executed for each camera |
Description:
Adds a method to execute after each camera's visibility calculations and before draw calls.
RemoveCameraEventOnPreRender
public static void RemoveCameraEventOnPreRender(UnityAction<GPUICameraData> cameraEvent)
| Parameters | |
|---|---|
cameraEvent |
Action that is previously added with the AddCameraEvent method |
Description:
Removes the method previously added with the AddCameraEventOnPreRender method.
AddCameraEventOnPostRender
public static void AddCameraEventOnPostRender(UnityAction<GPUICameraData> cameraEvent)
| Parameters | |
|---|---|
cameraEvent |
Action that will be executed for each camera |
Description:
Adds a method to execute after each camera's draw calls.
RemoveCameraEventOnPostRender
public static void RemoveCameraEventOnPostRender(UnityAction<GPUICameraData> cameraEvent)
| Parameters | |
|---|---|
cameraEvent |
Action that is previously added with the AddCameraEvent method |
Description:
Removes the method previously added with the AddCameraEventOnPostRender method.
GPUInstancerPro.PrefabModule.GPUIPrefabAPI
AddPrototype
public static int AddPrototype(GPUIPrefabManager prefabManager, GameObject prefab)
| Parameters | |
|---|---|
prefabManager |
|
prefab |
|
Description:
Adds the given GameObject as a prototype to the Prefab Manager
AddPrefabInstance
public static void AddPrefabInstance(GPUIPrefab gpuiPrefab)
| Parameters | |
|---|---|
gpuiPrefab |
|
Description:
Adds the prefab instance to an existing Prefab Manager. The corresponding prefab should be defined as a prototype on the Prefab Manager. The prefab instance will be registered on the Prefab Manager with the manager's next LateUpdate. If you wish to add the instance immediately, please use the AddPrefabInstanceImmediate(GPUIPrefab) method.
AddPrefabInstances
public static void AddPrefabInstances(IEnumerable<GPUIPrefab> gpuiPrefabs)
| Parameters | |
|---|---|
gpuiPrefabs |
|
Description:
Adds the collection of prefab instances to an existing Prefab Manager. The corresponding prefabs should be defined as a prototype on the Prefab Manager. The instances will be registered on the Prefab Manager with manager's next LateUpdate. If you wish to add the instances immediately, please use the AddPrefabInstanceImmediate(GPUIPrefab) method.
AddPrefabInstances
public static bool AddPrefabInstances(GPUIPrefabManager prefabManager, IEnumerable<GPUIPrefab> instances, int prototypeIndex)
| Parameters | |
|---|---|
prefabManager |
|
instances |
Collection of instances of a specific prefab |
prototypeIndex |
The prototype index of the prefab on the Prefab Manager |
Description:
Adds the collection of instances of a specific prefab to the Prefab Manager. The instances will be registered on the Prefab Manager with manager's next LateUpdate. If you wish to add the instances immediately, please use the AddPrefabInstanceImmediate(GPUIPrefab) method.
AddPrefabInstances
public static void AddPrefabInstances(GPUIPrefabManager prefabManager, IEnumerable<GameObject> gameObjects, int prototypeIndex)
| Parameters | |
|---|---|
prefabManager |
|
gameObjects |
Collection of instances of a specific prefab |
prototypeIndex |
The prototype index of the prefab on the Prefab Manager |
Description:
Adds the collection of instances of a specific prefab to the Prefab Manager. The instances will be registered on the Prefab Manager with manager's next LateUpdate. If you wish to add the instances immediately, please use the AddPrefabInstanceImmediate(GPUIPrefab) method.
AddPrefabInstance
public static bool AddPrefabInstance(GPUIPrefabManager prefabManager, GameObject go, int prototypeIndex)
| Parameters | |
|---|---|
prefabManager |
|
go |
|
prototypeIndex |
The prototype index of the prefab on the Prefab Manager |
Description:
Adds the prefab instance to the Prefab Manager. The instances will be registered on the Prefab Manager with manager's next LateUpdate. If you wish to add the instance immediately, please use the AddPrefabInstanceImmediate method.
AddPrefabInstance
public static bool AddPrefabInstance(GPUIPrefabManager prefabManager, GPUIPrefab gpuiPrefab, int prototypeIndex = -1)
| Parameters | |
|---|---|
prefabManager |
|
gpuiPrefab |
|
prototypeIndex |
The prototype index of the prefab on the Prefab Manager |
Description:
Adds the prefab instance to the Prefab Manager. The instances will be registered on the Prefab Manager with manager's next LateUpdate. If you wish to add the instance immediately, please use the AddPrefabInstanceImmediate(GPUIPrefab) method.
AddPrefabInstanceImmediate
public static int AddPrefabInstanceImmediate(GPUIPrefabManager prefabManager, GPUIPrefab gpuiPrefab, int prototypeIndex = -1)
| Parameters | |
|---|---|
prefabManager |
|
gpuiPrefab |
|
prototypeIndex |
|
Description:
Immediately adds the prefab instance to the Prefab Manager without waiting for LateUpdate.
RemovePrefabInstance
public static void RemovePrefabInstance(GPUIPrefab gpuiPrefab)
| Parameters | |
|---|---|
gpuiPrefab |
|
Description:
Removes the prefab instance from the Prefab Manager.
UpdateTransformData
public static void UpdateTransformData(GPUIPrefabManager prefabManager)
| Parameters | |
|---|---|
prefabManager |
|
Description:
Notifies the Prefab Manager to update the transform data buffers.
UpdateTransformData
public static void UpdateTransformData(GPUIPrefabManager prefabManager, int prototypeIndex)
| Parameters | |
|---|---|
prefabManager |
|
prototypeIndex |
|
Description:
Notifies the Prefab Manager to update the transform data buffers for the specified prototype.
UpdateTransformData
public static void UpdateTransformData(GPUIPrefabManager prefabManager, GPUIPrefab gpuiPrefab)
| Parameters | |
|---|---|
prefabManager |
|
gpuiPrefab |
|
Description:
Updates the Matrix4x4 data for the given prefab instance.
GPUInstancerPro.TerrainModule.GPUITerrainAPI
AddTerrains<T>
public static void AddTerrains<T>(GPUITerrainManager<T> terrainManager, IEnumerable<Terrain> terrains) where T : GPUIPrototypeData, new()
| Parameters | |
|---|---|
terrainManager |
The Tree or Detail Manager to which the terrain will be added |
terrains |
Collection of terrains to add to the manager |
Description:
Adds the given terrain collection to the Detail or Tree Manager.
AddTerrains<T>
public static void AddTerrains<T>(GPUITerrainManager<T> terrainManager, IEnumerable<GPUITerrain> gpuiTerrains) where T : GPUIPrototypeData, new()
| Parameters | |
|---|---|
terrainManager |
The Tree or Detail Manager to which the terrain will be added |
gpuiTerrains |
Collection of GPUI terrains to add to the manager |
Description:
Adds the given terrain collection to the Detail or Tree Manager.
AddTerrain<T>
public static bool AddTerrain<T>(GPUITerrainManager<T> terrainManager, Terrain terrain) where T : GPUIPrototypeData, new()
| Parameters | |
|---|---|
terrainManager |
The Tree or Detail Manager to which the terrain will be added |
terrain |
Terrain to add to the manager |
Description:
Adds the given terrain to the Detail or Tree Manager.
AddTerrain<T>
public static bool AddTerrain<T>(GPUITerrainManager<T> terrainManager, GPUITerrain gpuiTerrain) where T : GPUIPrototypeData, new()
| Parameters | |
|---|---|
terrainManager |
The Tree or Detail Manager to which the terrain will be added |
gpuiTerrain |
GPUI terrain to add to the manager |
Description:
Adds the given terrain to the Detail or Tree Manager.
RemoveTerrain<T>
public static bool RemoveTerrain<T>(GPUITerrainManager<T> terrainManager, Terrain terrain) where T : GPUIPrototypeData, new()
| Parameters | |
|---|---|
terrainManager |
The Tree or Detail Manager from which the terrain will be removed |
terrain |
Terrain to remove from the manager |
Description:
Removes the given terrain from the Detail or Tree Manager.
RemoveTerrain<T>
public static bool RemoveTerrain<T>(GPUITerrainManager<T> terrainManager, GPUITerrain gpuiTerrain) where T : GPUIPrototypeData, new()
| Parameters | |
|---|---|
terrainManager |
The Tree or Detail Manager from which the terrain will be removed |
gpuiTerrain |
GPUI terrain to remove from the manager |
Description:
Removes the given terrain from the Detail or Tree Manager.
RequireUpdate
public static void RequireUpdate(GPUIDetailManager detailManager, bool forceImmediateUpdate = false)
| Parameters | |
|---|---|
detailManager |
The Detail Manager to update. |
forceImmediateUpdate |
(Optional) When true, the Detail Manager will update the detail instances immediately instead of waiting for asynchronous GPU readback. |
Description:
This method can be used to notify the Detail Manager about changes to terrain details at runtime, such as when the terrain height is modified.
RequireUpdate
public static void RequireUpdate(GPUITreeManager treeManager, bool reloadTreeInstances = true)
| Parameters | |
|---|---|
treeManager |
The Tree Manager to update. |
reloadTreeInstances |
(Optional) When true, the Tree Manager will reload the tree instances from the terrain instead of using cached data. |
Description:
This method can be used to notify the Tree Manager about changes to terrain trees at runtime, such as when the terrain height is modified.
