GPU Instancer Pro:APIDocumentation

From GurBu Wiki
Revision as of 14:22, 3 October 2024 by GurBu Admin (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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





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.