GPU Instancer Logo


API Documentation


All API methods and descriptions can be found in GPUInstancer/Scripts/API/GPUInstancerAPI.cs
Select one of the following API methods to see the details.



InitializeGPUInstancer



InitializeGPUInstancer

public static void InitializeGPUInstancer(GPUInstancerManager manager)

Parameters

managerThe manager that defines the prototypes you want to GPU instance.

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



SetCamera

public static void SetCamera(GPUInstancerManager manager, Camera camera)

Parameters

managerThe manager that defines the prototypes you want to GPU instance.
cameraThe 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



SetCamera

public static void SetCamera(Camera camera)

Parameters

cameraThe 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



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.

SetGlobalPositionOffset



SetGlobalPositionOffset

public static void SetGlobalPositionOffset(GPUInstancerManager manager, Vector3 offsetPosition)

Parameters

managerGPUI Manager to apply the offset
offsetPositionOffset Position

Description

Updates all transform values with the given offset position.

RegisterPrefabInstanceList



RegisterPrefabInstanceList

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

Parameters

managerThe manager that defines the prototypes you want to GPU instance.
prefabInstanceListThe 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



UnregisterPrefabInstanceList

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

Parameters

managerThe manager that defines the prototypes you want to GPU instance.
prefabInstanceListThe 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



ClearRegisteredPrefabInstances

public static void ClearRegisteredPrefabInstances(GPUInstancerPrefabManager manager)

Parameters

managerThe manager that defines the prototypes you want to GPU instance.

Description

Clears the registered prefab instances from the prefab manager.

ClearRegisteredPrefabInstances



ClearRegisteredPrefabInstances

public static void ClearRegisteredPrefabInstances(GPUInstancerPrefabManager manager, GPUInstancerPrototype prototype)

Parameters

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

Description

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

AddPrefabInstance



AddPrefabInstance

public static void AddPrefabInstance(GPUInstancerPrefabManager manager, GPUInstancerPrefab prefabInstance)

Parameters

managerThe manager that defines the prototypes you want to GPU instance.
prefabInstanceThe 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



RemovePrefabInstance

public static void RemovePrefabInstance(GPUInstancerPrefabManager manager, GPUInstancerPrefab prefabInstance)

Parameters

managerThe manager that defines the prototypes you want to GPU instance.
prefabInstanceThe prefab instance to remove.

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



DisableIntancingForInstance

public static void DisableIntancingForInstance(GPUInstancerPrefabManager manager, GPUInstancerPrefab prefabInstance)

Parameters

managerThe manager that defines the prototypes you want to GPU instance.
prefabInstanceThe prefab instance to disable the GPU Instancing of.

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



EnableInstancingForInstance

public static void EnableInstancingForInstance(GPUInstancerPrefabManager manager, GPUInstancerPrefab prefabInstance)

Parameters

managerThe manager that defines the prototypes you want to GPU instance.
prefabInstanceThe prefab instance to enable the GPU Instancing of.

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



UpdateTransformDataForInstance

public static void UpdateTransformDataForInstance(GPUInstancerPrefabManager manager, GPUInstancerPrefab prefabInstance)

Parameters

managerThe manager that defines the prototypes you want to GPU instance.
prefabInstanceThe 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>



DefinePrototypeVariationBuffer<T>

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

Parameters

TThe type of variation buffer. Must be defined in the instance prototype's shader
managerThe manager that defines the prototypes you want to GPU instance.
prototypeThe GPU Instancer prototype to define variations.
bufferNameThe 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

Example

This sample shows how to use the variation buffer in your shader: See "GPUInstancer/ColorVariationShader" for the full example.

...
fixed4 _Color;
#ifdef UNITY_PROCEDURAL_INSTANCING_ENABLED
    StructuredBuffer<float4> colorBuffer;
#endif
...
void surf (Input IN, inout SurfaceOutputStandard o) {
...
    #ifdef UNITY_PROCEDURAL_INSTANCING_ENABLED
        uint index = gpuiTransformationMatrix[unity_InstanceID];
        col = colorBuffer[index];
    #else
        col = _Color;
    #endif
...
}

AddVariation<T>



AddVariation<T>

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

Parameters

TThe type of variation buffer. Must be defined in the instance prototype's shader.
prefabInstanceThe prefab instance to add the variation to.
bufferNameThe name of the variation buffer in the prototype's shader.
valueThe 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.

DefineAndAddVariationFromArray<T>



DefineAndAddVariationFromArray<T>

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

Parameters

TThe type of variation buffer. Must be defined in the instance prototype's shader
managerThe manager that defines the prototypes you want to GPU instance.
prototypeThe GPU Instancer prototype to define variations.
bufferNameThe name of the variation buffer in the prototype's shader.
variationArrayThe 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>



UpdateVariationFromArray<T>

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

Parameters

TThe type of variation buffer. Must be defined in the instance prototype's shader
managerThe manager that defines the prototypes you want to GPU instance.
prototypeThe GPU Instancer prototype to define variations.
bufferNameThe name of the variation buffer in the prototype's shader.
variationArrayThe array that stores the variation information.

Description

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

InitializeWithMatrix4x4Array



InitializeWithMatrix4x4Array

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

Parameters

prefabManagerThe GPUI Prefab Manager that the prefab prototype is defined on
prototypeGPUI Prefab Prototype
matrix4x4ArrayArray 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



UpdateVisibilityBufferWithMatrix4x4Array

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

Parameters

prefabManagerThe GPUI Prefab Manager that the prefab prototype is defined on
prototypeGPUI Prefab Prototype
matrix4x4ArrayArray of Matrix4x4 that store the transform data of prefab instances

Description

Use this method to update transform data of all prefab instances with a Matrix4x4 array

SetupManagerWithTerrain



SetupManagerWithTerrain

public static void SetupManagerWithTerrain(GPUInstancerTerrainManager manager, Terrain terrain)

Parameters

managerThe 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.

UpdateDetailInstances



UpdateDetailInstances

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

Parameters

managerThe manager that defines the prototypes you want to GPU instance.
updateMeshesWhether 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

StartListeningGPUIEvent



StartListeningGPUIEvent

public static void StartListeningGPUIEvent(GPUInstancerEventType eventType, UnityAction callback)

Parameters

eventTypeThe event type that will be listened for callback
callbackThe 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



StopListeningGPUIEvent

public static void StopListeningGPUIEvent(GPUInstancerEventType eventType, UnityAction callback)

Parameters

eventTypeThe event type that was registered with StartListeningGPUIEvent
callbackThe 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