GPU Instancer Pro:GettingStarted

From GurBu Wiki
Jump to: navigation, search

About GPU Instance Pro | Getting Started | Terminology | Best Practices | API Documentation | F.A.Q. | Support


GPU Instancer Pro consists of various main Monobehavior classes called Managers. The most commonly used ones are the Prefab Manager, Detail Manager and Tree Manager. The managers are designed with mainly ease of use in mind, and adding them to your scene is as easy as clicking a menu item.

On this page, you will find information about these managers and everything GPUI comes with - including, various tools and components that will quickly get you started using GPUI Pro.


HelpButton.png  All the GPU Instancer Pro Managers also have a question mark icon on their top right corners. Clicking this icon will make the managers show descriptions on their settings. You can always click this button to get information about a manager setting.


Quick Start


The Prefab Manager

The Prefab Manager
  • Add Prefab Manager: Tools -> GPU Instancer Pro -> Add Prefab Manager
  • Click on the Add button.
  • Select the prefabs with or expected to have many instances in the scene. (See Instance Counts)
  • Enable the necessary options under Prefab Prototype Settings

The Tree Manager

The Tree Manager
  • Add Tree Manager: Tools -> GPU Instancer Pro -> Add Tree Manager For Terrains

The Detail Manager

The Detail Manager
  • Add Detail Manager: Tools -> GPU Instancer Pro -> Add Detail Manager For Terrains

No-GameObjects Workflow

  • Create a new renderer with the RegisterRenderer API method and store the rendererKey output.
  • Set the transform matrices using the SetMatrices API method using the given rendererKey.
  • To stop the rendering, call the DisposeRenderer API method.

Manager Setup

Common Manager Settings

The following Manager Settings are common in every manager.

Manager Settings

Dont Destroy On Load: When enabled, the GPUI Manager will not be destroyed when loading a new Scene.

Default Profile: New prototypes that are added to the Manager will use this prototype by default.

Revert When Disabled: Enable default rendering when the manager is disabled.


Profile Settings

The settings related to rendering (culling, LOD, etc.) are stored in a Profile Scriptable Object, which is shared between prototypes. Profile Settings are written to persistent GPU buffers instead of sending the data to GPU every frame. This reduces the number of files, simplifies the addition/removal of prototypes, and optimizes GPU data transfer.

You can use the '+Create' button located on the right side of the Profile object to generate a new Profile Scriptable Object in your project.

Profile Settings

Is Shadow Casting: Is Shadow Casting specifies whether the object will cast shadows or not. Enabling shadow casting requires extra shadow passes, resulting in additional rendering operations. GPU Instancer implements various techniques to optimize these operations, but disabling shadow casting when unnecessary can enhance performance.

Custom Shadow Distance: When Custom Shadow Distance is set to 0, GPU Instancer will render shadows based on the Quality Settings. You can adjust this setting to specify a lower value, effectively culling shadows for distant objects.

Is Cull Shadows: If enabled, culling results will also be applied to the shadows. This will result in more performance, but might also lead to less consistency in shadows.


Is Distance Culling: When Distance Culling is enabled, you can specify minimum and maximum distance values. Objects beyond these distances will be culled.

Is Frustum Culling: Is Frustum Culling determines whether objects outside the camera's view frustum will be rendered. When enabled, GPU Instancer will exclude objects outside the frustum from rendering, enhancing performance. It's advisable to enable frustum culling unless there's a specific reason not to.

Frustum Offset: Frustum Offset expands the camera frustum planes, affecting the area within which objects are rendered when frustum culling is enabled.

Is Occlusion Culling: Is Occlusion Culling determines whether objects occluded by other objects will be rendered. When enabled, GPU Instancer will skip rendering objects that are behind others and would not normally be visible. While occlusion culling adds some additional GPU operations, it's recommended to enable it when beneficial.

Occlusion Offset: Occlusion Offset defines the depth value (ranged between 0 to 1) that the differences will be discarded while calculating culled objects from the depth texture. Higher offset values will result in less culling.

Occlusion Accuracy: Occlusion Cull Accuracy defines the accuracy of the occlusion culling. Higher values will result in more accurate culling with higher number of texture samples. 1 => 5 samples (middle point and corner points) 2 => 9 samples (adds 1/4 points) 3 => 17 samples (adds 1/8 and 3/8 points)

Min Culling Distance: Min. Culling Distance defines the minimum distance that any kind of culling will occur. If it is a value higher than 0, the instances with a distance less than the specified value to the Camera will not be culled.

Bounds Offset: Bounds Offset can be used to increase the bounding box size of the prototype. This will affect the culling and LOD calculations. It is particularly useful for prototypes with shaders that modify vertex positions.


LOD Cross-fading: LOD Cross-Fade enables cross-fade style blending between the LOD levels of this prototype. This can have a minor impact on performance since during cross-fading, both LOD levels will be rendering.

LOD Bias Adjustment: The LOD Bias Adjustment value effects the LOD level distances per prototype. When it is set to a value less than 1, it favors less detail. A value of more than 1 favors greater detail.

Shadow LOD Map: Shadow LOD Map can be utilized to adjust the level of detail used for rendering shadows for each LOD.


Billboard Settings

GPUInstancer-Scr-BillboardGenerator.png

GPU Instancer Pro has the capability to automatically generate billboard renderers for prefabs. However, it's important to note that the billboard system is primarily designed for terrain trees. Generating billboards for prefabs that do not use default Unity tree shaders (such as SpeedTree, TreeCreator, or SoftOcclusion shaders) might lead to unexpected results.


Manager Settings

Generate Billboard: When Generate Billboard option is enabled, a billboard mesh and material will be created and added as the last LOD to the prototype.

Replace LOD Culled: When enabled, the billboard will replace the Culled section of the LOD Group component, instead of using a custom distance value.

Billboard Distance: The Billboard Distance value is similar to the LOD percentage setting on the LOD Group component. For example a value of 0.9 is similar to 10% on the LOD Group component.

Atlas Resolution: Atlas Resolution defines the resolution of the billboard textures. Higher resolutions result in better looking billboards, but use more memory. Texture atlases are not square for 2D billboards; so for example "x2048" option results in a 2048x256 texture resolution.

Frame Count: Frame Count defines the total amount of snapshots that are taken from different angles for this billboard. Higher frame counts result in more accurate view differences in different view angles, but result in lower resolution frames since they are all packed in the same atlas.

Brightness: You can use Brightness to adjust the brightness of the billboard textures. A zero value is fully black whereas one is lighter.

Cutoff Override: You can use the Cutoff Override option to override the alpha cutoff value of the original materials for the billboard textures. This is normally necessary if you use the alpha value as some other data (e.g. metallic, etc.) in the textures of the material for the prefab of this prototype.

Normal Strength: Normal Strength controls the intensity of the normal texture effect. Values lower than 1 will decrease it, while higher values will amplify the effect of the normal texture.

Add To Billboard Assets: When Add To Billboard Assets option is enabled, the billboard asset will be added to the 'Billboard Assets' List inside Runtime Settings, which will make the billboard asset discoverable when creating prototypes at runtime.


Statistics Tab

The Statistics Tab provides insights into GPU Instancer rendering information, enabling users to identify bottlenecks and optimize performance.

Manager Settings

Show Visibility: When enabled, the GPUI Manager will readback culling results from the GPU and display additional information such as vertex counts and visible LOD counts.



The Prefab Manager


GPUI-PrefabInstancing002.png

By adding your prefabs to the Prefab Manager, the prefab instances you add to your scenes are automatically rendered by GPU Instancer. It also provides additional functionality such as adding/removing/updating instances at runtime. Note that the Prefab Manager only accepts user created prefabs. It will not accept prefabs that are generated when importing your 3D model assets.

When using the Prefab Manager, the most important thing to have in mind is that you should only add the prefabs that you have many instances of as prototypes. GPU Instancer uses various techniques to increase performance, but ultimately it renders its prototypes using GPU Instancing. Therefore, it is highly recommended to read the Terminology and the Best Practices pages to familiarize with the concept of GPU Instancing and to get the most out of the Prefab Manager and GPUI in general.


Prefab Manager Settings

Prefab Manager Settings

Find Instances At Start: When enabled, the Prefab Manager will search for GPUIPrefab components in the scene during initialization. When disabled, you can manually register the prefab instances in the scene, using the Register Instances In Scene button.


Prefab Manager Prototype Settings

Prefab Manager Prototype Settings

Transform Updates: When enabled, the transform data of the prefab instances will be read and uploaded to a GPU buffer every frame. If the prefab instances are not changing their transform data, it is better to keep it disabled. If there are rarely changes, you can use the GPUIPrefabManager.UpdateTransformData method to notify the Prefab Manager about the changes while keeping this setting disabled.

Auto. Add/Remove: When enabled, GPUIPrefabAutoAddRemove component will be added to the prefab. The instances containing this component will be automatically added to or removed from the Prefab Manager.


The Detail Manager


GPUI-DetailInstancing001.png

The primary objective of the Detail Manager is to enhance performance and improve visual quality compared to Unity's default terrain details. It offers native support for multiple terrains, minimizing draw calls and efficiently managing runtime changes with reduced allocations. Additionally, it introduces optimization features to decrease the number of distant detail instances, thereby boosting performance while preserving visual quality.

The Detail Manager utilizes grayscale density textures to render detail instances, and these textures can be edited at runtime without incurring CPU overhead using the provided Density Modifiers. Users have the capability to dynamically add and remove detail instances at runtime, leading to improved flexibility and usability of the terrain system.

The foliage shader included with the Detail Manager offers various quality enhancements and customization options for texture detail instances.

Furthermore, users can add prefabs with LOD Group components to the Detail Manager's prototypes. GPUI will add the first LOD into the terrain, allowing it to be painted using terrain tools. However, GPUI will continue to utilize the prefab with all its LOD levels during rendering.


Detail Manager Settings

Detail Manager Settings

Render In Edit Mode: When enabled, the GPUI Manager will render the objects in edit mode.

Terrains: List of Terrains this manager is currently rendering the detail and tree instances for.

Auto. Add New Prototypes: When enabled, new prototypes will be created on the Manager when there are prototypes on the terrains that do not match any of the existing prototypes on the Manager.

Auto. Remove Deleted Prototypes: When enabled, prototypes on the Manager that do not match any of the terrain prototypes will be automatically removed.

Detail Distance: Determines the maximum distance that the detail instances will be drawn.

Detail Update Distance: Detail instances are updated based on camera position. Update distance determines after how much camera movement the detail instances will be updated. When set to zero, the detail instances will be updated every frame.

Healthy/Dry Noise Texture: Healthy/Dry Noise Texture is used for determining detail instance scales and colors.


Detail Manager Prototype Settings

Detail Manager Prototype Settings

Mesh: For Texture Detail Prototypes, GPUI uses a quad mesh named 'DefaultDetailMesh'. You have the option to change this default quad mesh by assigning a custom mesh to this property.

Materials: For Texture Detail Prototypes, GPUI uses a material with the 'GPUInstancerPro/Foliage' shader. You have the option to change this by assigning a custom material to this property.

Material Description: To minimize the number of materials used for texture prototypes, GPUI employs Material Property Blocks and shares the same material across different texture prototypes. The 'Material Description' property enables users to utilize custom shaders, leveraging this functionality by creating custom material descriptions for their shaders.

Layer: You can use this dropdown to choose a Layer that the texture type Terrain details will be using. The terrain details that use prefabs will get the Layer value from the prefab object.

Terrain Properties: These settings are read from the terrain for each detail prototype. They are provided for viewing and editing for special use cases, as well as for testing and debugging purposes.

Density Adjustment: By changing the Density Adjustment value, you can increase or decrease the density of detail instances.


Detail Shader Properties

GPUI uses a custom foliage shader that uses the Standard Lighting Model for rendering texture type detail properties. You can use this shader also on your prefabs by creating a material from the GPUInstancerPro/Foliage shader and assigning this material to the Mesh Renderer of your prefabs. These settings on the manager show only when a texture type detail prototype is selected and the default detail material is used, and they can be used to change prototype settings individually.

Detail Shader Properties

Ambient Occlusion: The amount of ambient occlusion to apply to the objects that use the foliage shader.

Gradient Power: GPUI's foliage shader provides an option to darken the lower regions of the mesh that uses it. This results in a more realistic look for foliage. You can set the amount of this darkening effect with the this property, or turn it off completely by setting the slider to zero.

Wind Idle Sway: Specifies the amount of idle wind animation for the detail prototypes that use the foliage shader. This is the wind animation that occurs where wind waves are not present. Turning the slider down to zero disables this idle wind animation.

Wind Waves On: Specifies whether there will be wind waves for the detail prototypes that use the foliage shader. The normal texture that is used to calculate winds can be changed from the material by editing the Wind Wave Normal Texture property.

Wind Wave Size: Specifies the size of the wind waves for the detail prototypes that use foliage shader.

Wind Wave Tint: Specifies how much the Wind Wave Tint Color applies to the wind wave effect for the detail prototypes that use the foliage shader. Turning the slider down to zero disables wind wave coloring.

Wind Wave Sway: Specifies the amount of wind animation that is applied by the wind waves for the detail prototypes that use the foliage shader. This is the wind animation that occurs in addition to the idle wind animation. Turning the slider down to zero disables this extra wave animation.


Detail Density Reduction

Distance Based Density Reduction reduces the amount of detail instances when they are far away. It can also increase the scale of the far away objects to make them cover a similar area.

Detail Shader Properties

DR Start Distance: The starting distance from the camera for the distance reduction.

DR Multiplier: Higher DR Multiplier values will remove more instance, lower values will remove less. For best performance, keep it as high as possible without compromising visual quality.

DR Max Scale: Distant detail instances will be scaled to cover the emptied areas left behind by the removed instances. DR Max Scale determines the maximum scale value.

DR Height Scale: When set to zero, the distance objects are scaled only on the X and Z axises. When set to one, the Y axis will have the same scale increas as the others.


The Tree Manager


GPUI-TreeInstancing001.png

The Tree Manager provides a solution for instancing Unity terrain trees. By adding a Tree Manager to your scene, GPUI can extract tree data from the Unity Terrain and generate the necessary GPUI prototypes. Additionally, the Tree Manager automatically enables billboarding for tree prototypes and generates billboards as needed. This manager supports various tree shaders, including SpeedTree, TreeCreator, and many custom tree shaders. If you prefer to use trees without registering them to the Unity terrain, you can utilize the Prefab Manager instead.


Tree Manager Settings

Tree Manager Settings

Render In Edit Mode: When enabled, the GPUI Manager will render the terrain trees in edit mode.

Terrains: List of Terrains this manager is currently rendering the detail and tree instances for.

Auto. Add New Prototypes: When enabled, new prototypes will be created on the Manager when there are prototypes on the terrains that do not match any of the existing prototypes on the Manager.

Auto. Remove Deleted Prototypes: When enabled, prototypes on the Manager that do not match any of the terrain prototypes will be automatically removed.

Tree Instance Colors: When enabled, the Tree Manager will create color variation buffers based on the color property of TreeInstances. Suitable shaders, such as the Tree Creator shaders, can use this buffer to create color variations.


Tree Manager Prototype Settings

Tree Manager Prototype Settings

Apply Rotation: When enabled, trees will be rotated based on the rotation property of the TreeInstance.

Apply Prefab Scale: When enabled, the scale value of the tree prefab will be applied to the instances.

Apply Height: When enabled, tree heights will be modified based on the heightScale property of the TreeInstance.


Utilities

GPUI Debugger Window

GPUIProDebuggerWindow.png

The Debugger Window offers comprehensive insights into draw calls and compute shader calculations, aiding in analysis and debugging. It provides information on the cameras utilized for instanced rendering, statistical data on the currently rendered instances for each camera, and GPU allocations for each prototype. Furthermore, by selecting the GPUI LOD Group Data objects for each prototype, users can access details on the meshes, materials, keywords, and LOD settings utilized for draw calls.


To open this window, navigate to : Tools -> GPU Instancer Pro -> Utilities -> Show Debugger Window


Billboard Generator Window

GPUIProBillboardGeneratorWindow.png

The Billboard Generator Window is a tool provided by GPUI for testing and fine-tuning settings related to billboards generated by the system. It allows users to adjust parameters such as resolution, frame count, and brightness to achieve the desired visual appearance for billboard rendering. For detailed information on these settings, please refer to the Billboard Settings section.


Save as Asset: This button saves the billboard settings to a Scriptable Object, along with the generated textures. It allows users to preserve their billboard configurations for future use within GPUI Managers.

Save Standalone: Clicking this button creates a mesh, a material, and a billboard prefab that can be used independently of the GPUI Managers. It provides a way to add the generated billboards as LOD levels to other objects or scenes.

Close and Return: This button closes the preview scene and returns the user to the previous scene.


To open this window, navigate to : Tools -> GPU Instancer Pro -> Utilities -> Show Billboard Generator


Prefab Replacer Window

GPUIProPrefabReplacerWindow.png

GPUI includes a Prefab Replacer tool designed to simplify the process of replacing GameObjects in your scene hierarchy with prefab instances with just a few clicks. This tool is particularly useful if you didn't follow a prefab workflow when initially creating your scene. Additionally, it allows you to effortlessly replace instances of one or multiple prefabs with another while retaining the transform data, such as positions, rotations, and scales.


To open this window, navigate to : Tools -> GPU Instancer Pro -> Utilities -> Show Prefab Replacer


Grass Mesh Generator Window

GPUIProGrassMeshGeneratorWindow.png

The Grass Mesh Generator tool in GPUI facilitates the creation of custom meshes for texture detail prototypes managed by the Detail Manager. This feature enables users to tailor the appearance of grass and other textured details to suit their specific project requirements.


To open this window, navigate to : Tools -> GPU Instancer Pro -> Utilities -> Show Grass Mesh Generator


Additional Components and Scriptable Objects

GPUI Camera

GPUIProCameraComponent.png

Users can designate the cameras to be utilized for instanced rendering by attaching the GPUI Camera component to each respective camera. The flexibility of employing multiple cameras simultaneously is straightforward; users simply need to add this component to each camera they intend to use. During GPUI rendering initiation, if no cameras with this component are detected, the system will automatically search for a camera based on the behavior selected in the Runtime Settings.

Enable Occlusion Culling: This option determines whether depth textures will be generated for this camera, allowing for the utilization of the Occlusion Culling feature.

HiZ Depth Texture: This property displays the depth texture used for Occlusion Culling at runtime, which can be helpful for debugging purposes.


GPUI LOD Group Data

GPUIProLODGroupData.png

For each prototype, the system generates a GPUI LOD Group Data object, which specifies the meshes, materials, keywords, and LOD transition values utilized for rendering. This information is accessible to users, allowing them to make runtime modifications for debugging and testing purposes.


GPUI Prefab

GPUIProPrefabComponent.png

GPUI Prefab component is automatically attached to prefabs when they are added to the Prefab Manager. It enables the Prefab Manager to track the prefab instances by maintaining their instancing status and GPU buffer information.


GPUI Prefab Auto Add Remove

GPUIProPrefabAutoAddRemoveComponent.png

GPUI Prefab Auto Add Remove component is automatically attached to prefabs when the 'Auto. Add/Remove' option is enabled on the Prefab Manager. It facilitates the automatic registration of prefab instances to the Prefab Manager when they are added to the scene or enabled, and removes them from the Prefab Manager when they are removed from the scene or disabled.


GPUI Terrain

GPUIProTerrainBuiltin.png

GPUI Terrain component is automatically attached to terrains when they are added to the Tree or Detail Managers. It provides essential terrain information, such as heightmap texture, tree instances, and detail density textures, to the GPUI Managers.


Auto. Find Tree Manager: When this option is enabled, the terrain will be automatically assigned to a GPUI Tree Manager present in the scene at runtime.

Auto. Find Detail Manager: When this option is enabled, the terrain will be automatically assigned to a GPUI Detail Manager present in the scene at runtime.

Bake Detail Textures: This button saves the grayscale density texture used for terrain detail rendering as a texture asset. It accelerates Detail Manager initialization and reduces allocations.


Detail Material Description

GPUIProDetailMaterialDescription.png

To reduce the number of materials required for texture prototypes, GPUI utilizes Material Property Blocks, allowing the same material to be shared across different texture prototypes. The 'Detail Material Description' Scriptable Object enables users to leverage this functionality with custom shaders by defining which properties on the shader correspond to specific functions.


To create a new Detail Material Description, right click on the Project window and select: Create -> Rendering -> GPU Instancer Pro -> Detail Material Description


GPUI Event System

GPUIProEventSystem.png

The GPUI Event System enables users to execute custom methods at different stages of the rendering process of cameras. These stages include:

OnPreCull: Executed before the camera visibility calculations.

OnPreRender: Executed after the camera visibility calculations and before the draw calls.

OnPostRender: Executed after the draw calls.


The event system can be added to your scenes by navigating to: Tools -> GPU Instancer Pro -> Helpers -> Add Event System


Floating Origin Event

The "GPUI Event Floating Origin" component can automatically adjust all instances managed by a GPUI Manager according to the movements of a specified transform. Please note that these adjustments are limited to the matrix data stored in GPU memory. GameObjects in your scenes will not be modified.


Face Camera Event

The "GPUI Event Face Camera" component can automatically adjust all instances specific prototype to face the camera. Please note that these adjustments are limited to the matrix data stored in GPU memory. GameObjects in your scenes will not be modified.


System Settings

GPU Instancer Pro Preferences

GPUIProPreferences.png

The GPU Instancer Pro Preferences contain settings that can modify the default behavior of the GPUI rendering system and affect all GPUI managers and prototypes. These settings are divided into two categories: editor settings, which are related to behavior in the Unity editor, and runtime settings, which are related to operations during runtime.


To access the preferences, navigate to : Edit -> Preferences -> GPU Instancer Pro


GPUI Editor Settings


Generate Shader Variant Collection: If enabled, a ShaderVariantCollection with reference to shaders that are used in GPUI Managers will be generated automatically inside Resources folder. This will add the GPUI shader variants automatically to your builds. These shader variants are required for GPUI to work in your builds.

Auto. Shader Conversion: If enabled, shaders of the prefabs that are added to the GPUI Managers will be automatically converted to support GPU Instancer.

Update Buffers In Edit Mode: When enabled, GPUI will run Compute Shaders to make visibility calculations on every editor update.


GPUI Runtime Settings


Is Occlusion Culling Disabled: Enabling this option disables the occlusion culling feature project-wide. This can be beneficial for projects where occlusion culling is unnecessary, avoiding unnecessary depth texture and visibility calculations.

Camera Selection: This setting changes the camera selection behavior based on priority. The possible selections, ordered by priority, are:

'Default' => GPUICamera component, MainCamera tag, Camera.allCameras[0]

'MainCamera' => GPUICamera component, MainCamera tag

'GPUICameraComponent' => GPUICamera component

Manager Defaults: This list allows users to overwrite the default profile on the GPUI Managers that are used for newly added prototypes.

Billboard Assets: Assets added to the Billboard Assets list are discoverable to GPUI Managers when creating prototypes at runtime.


GPUI Shader Bindings

GPUIProShaderBindings.png

The Shader Bindings asset stores information about shaders used by prototypes for rendering with GPUI. Shaders lacking GPUIPro shader setup will have an automatically created replacement shader, and its information will be stored in this asset. This data is utilized at runtime to determine which shader to use for instanced rendering.


The Shader Bindings asset is located at: Assets/GPUInstancerPro/Resources/GPUIShaderBindings


GPUI Shader Variant Collection

GPUIProShaderVariantCollection.png

The Shader Variant Collection asset stores the shader variants used by prototypes for rendering with GPUI. It ensures that all the necessary shader variants are included in your builds, as GPUI modifies materials for instanced rendering at runtime, and Unity's default build behavior may not include all the necessary variants.


The Shader Variant Collection asset is located at: Assets/GPUInstancerPro/Resources/GPUIShaderVariantCollection


Shader Setup Guide


GPUI has a system that automatically generates a converted version of most shaders to work with itself. This system keeps track of shader changes and handles re-conversions automatically as well. This includes most of the shaders created by shader creation editors like Amplify Shader Editor. But in some special cases, it might be needed to change the shader manually to support GPU Instancer Pro. GPUI detects if a shader is compatible with it and will not generate a separate shader if that is the case. Here is the information you need to manually edit your shaders to support GPUI.


Built-in RP Shader Setup

In Built-in Render Pipeline, for all passes, you need to include the multi_compile_instancing and the instancing_options procedural:setupGPUI pragma directives. Please note that the GPUInstancerSetup.hlsl must be included after the UnityCG.cginc file:

Surface Shaders

...
SubShader {
    ...
    CGPROGRAM
    #include "UnityCG.cginc"
    #include "Packages/com.gurbu.gpui-pro/Runtime/Shaders/Include/GPUInstancerSetup.hlsl"
    #pragma instancing_options procedural:setupGPUI
    ...
    ENDCG
}
...


Since the #pragma multi_compile_instancing directive is automatically added to the generated code from surface shaders, you do not need to include it. However, if you have a additional passes (such as a shadowcaster pass), you need to add support to these passes as well (see Vertex/fragment Shaders below).
Please also note that if your shadows are not showing correctly (e.g. they show on camera position), you can add the addshadow option to your surface pragma directive to have your surface shader generate a shadow pass for you. This will make sure that your shadow pass is also setup for GPUI. If you do not define the addshadow option, and if your surface shader also does not have a shadow pass, Unity will use the shadow pass from the defined fallback shader, and this shader may not be setup for GPUI.


Vertex/fragment Shaders

For all passes:


...
Pass {
    ...
    CGPROGRAM
    ...
    #include "UnityCG.cginc"
 
    #include "Packages/com.gurbu.gpui-pro/Runtime/Shaders/Include/GPUInstancerSetup.hlsl"
    #pragma multi_compile_instancing
    #pragma instancing_options procedural:setupGPUI
    ENDCG
}
...


You also need to add instancing setup to your input structs and vertex functions if you don't already have it:


struct appdata_custom
{
    ...
    UNITY_VERTEX_INPUT_INSTANCE_ID
}


v2f vert( appdata_custom v )
{
    v2f o;
    UNITY_SETUP_INSTANCE_ID(v);
    ...
    return o;
}


URP Shader Setup

For all passes, you need to include the multi_compile_instancing and the instancing_options procedural:setupGPUI pragma directives. Please note that the GPUInstancerSetup.hlsl must be included after the URP include files:


...
Pass {
    ...
    HLSLPROGRAM
    ...
    #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl"
 
    #include "Packages/com.gurbu.gpui-pro/Runtime/Shaders/Include/GPUInstancerSetup.hlsl"
    #pragma multi_compile_instancing
    #pragma instancing_options procedural:setupGPUI
    ENDHLSL
}
...


Same as with other vertex/fragment shaders above, you also need to add instancing setup to your input struct and vertex function if you don't already have it.


For the vertex input struct:

struct VertexInput
{
    ...
    UNITY_VERTEX_INPUT_INSTANCE_ID
}


For the vertex output struct:

struct VertexOutput
{
    ...
    UNITY_VERTEX_INPUT_INSTANCE_ID
}


The vertex function:

VertexOutputvert(VertexInput v)
{
    VertexOutput o;
    UNITY_SETUP_INSTANCE_ID(v);
    ...
    return o;
}


And the fragment function:

half4 frag(VertexOutput IN)
{
    UNITY_SETUP_INSTANCE_ID(IN);
    UNITY_SETUP_STEREO_EYE_INDEX_POST_VERTEX(IN);
    ...
    return o;
}


HDRP Shader Setup

Same as with URP shaders. For all passes, you need to include the multi_compile_instancing and the instancing_options procedural:setupGPUI pragma directives. Please note that the GPUInstancerSetup.hlsl must be included after the HDRP include files:


...
Pass {
    ...
    HLSLPROGRAM
    ...
    #include "Packages/com.unity.render-pipelines.core/ShaderLibrary/Common.hlsl"
    #include "Packages/com.unity.render-pipelines.high-definition/Runtime/ShaderLibrary/ShaderVariables.hlsl"
 
    #include "Packages/com.gurbu.gpui-pro/Runtime/Shaders/Include/GPUInstancerSetup.hlsl"
    #pragma multi_compile_instancing
    #pragma instancing_options procedural:setupGPUI
    ENDHLSL
}
...


Same as with other vertex/fragment shaders above, you also need to add instancing setup to your input struct and vertex function if you don't already have it.


For the vertex input struct:

struct AttributesMesh
{
    ...
    UNITY_VERTEX_INPUT_INSTANCE_ID
}


For the vertex output struct:

struct PackedVaryingsMeshToPS
{
    ...
    UNITY_VERTEX_INPUT_INSTANCE_ID
}


The vertex function:

PackedVaryingsMeshToPSVert(AttributesMesh inputMesh)
{
    PackedVaryingsMeshToPS outputPackedVaryingsMeshToPS;
    UNITY_SETUP_INSTANCE_ID(inputMesh);
    UNITY_TRANSFER_INSTANCE_ID(inputMesh, outputPackedVaryingsMeshToPS);
    ...
    return outputPackedVaryingsMeshToPS;
}


And the fragment function:

void Frag(PackedVaryingsMeshToPS packedInput, OUTPUT_GBUFFER(outGBuffer) #ifdef _DEPTHOFFSET_ON, out float outputDepth : SV_Depth #endif)
{
    UNITY_SETUP_STEREO_EYE_INDEX_POST_VERTEX(packedInput);
    UNITY_SETUP_INSTANCE_ID(packedInput);
    ...
}


Shader Graph Setup

GPUI Pro ShaderGraph Setup

To set up a Shader Graph shader, simply add the GPU Instancer Pro Setup node to the shader and connect it to the Vertex Position output.


The primary function of the 'GPU Instancer Pro Setup' node is to incorporate instancing pragma directives and include necessary files in the shader. Essentially, it copies the provided input to the output without any alterations. If another node is already connected to the Vertex Position output, you can link it to the input of the 'GPU Instancer Pro Setup' node and then connect the output to the Vertex Position. Alternatively, if there are no nodes currently utilizing the Position output, you can add a Position node in Object space, connect it to the input of the 'GPU Instancer Pro Setup' node, and then link the output to the Vertex Position, as illustrated in the accompanying image.