Difference between revisions of "GPU Instancer:GettingStarted"

From GurBu Wiki
Jump to: navigation, search
(The Detail Manager)
(Includes and Pragmas)
(118 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[GPU_Instancer|About]] | [[GPU_Instancer:Features|Features]] | [[GPU_Instancer:GettingStarted|Getting Started]] | [[GPU_Instancer:Terminology|Terminology]] | [[GPU_Instancer:BestPractices|Best Practices]] | [[GPU_Instancer:FAQ|F.A.Q.]]
+
[[GPU_Instancer|About]] | [[GPU_Instancer:CrowdAnimations|Crowd Animations]] | [[GPU_Instancer:Features|Features]] | [[GPU_Instancer:GettingStarted|Getting Started]] | [[GPU_Instancer:Terminology|Terminology]] | [[GPU_Instancer:BestPractices|Best Practices]] |  [[GPU_Instancer:API_Documentation|API Documentation]] | [[GPU_Instancer:FAQ|F.A.Q.]]
  
  
[https://www.gurbu.com/gettingstarted Getting Started]
+
GPU Instancer consists of three main Monobehavior classes. These 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.
 
 
 
 
GPU Instancer consists of three main Monobehavior classes. These 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 that will quickly get you started using GPUI.
 
  
  
Line 18: Line 15:
  
  
== The Prefab Manager ==
+
== Quick Start ==
 
<br>
 
<br>
By adding your prefabs to the GPU Instancer 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, changing material properties per instance, choosing an LOD level to render the shadows from, and much more. Note that the Prefab Manager only accepts user created prefabs. It will not accept prefabs that are generated when importing your 3D model assets.
+
Getting Started with GPUI is extremely easy:
 +
 
 +
{| class="wikitable"
 +
|-
 +
|
 +
 
  
 +
'''1. Add the desired Managers to your scene'''
  
<div style="clear: both"></div>
+
{| class="wikitable" style="width:800px;"
[[File:AddPrefabManager v098-lowres.png|frame|left|Adding a Prefab Manager]]
+
|-
[[File:PrefabManager v098.png|frame|left|The Prefab Manager]]
+
| [[File:PrefabManager v1 11 high.png|50px|thumb|center]]||
 +
* Add Prefab Manager: '''<code>Tools -> GPU Instancer -> Add Prefab Manager</code>'''
 +
* Drag and drop the prefabs you want on the '''Add''' button.
 +
|-
 +
| [[File:DetailManager v111.png|50px|thumb|center]]||
 +
* Add Detail Managers to your scene: '''<code>Tools -> GPU Instancer -> Add Detail Manager For Terrains</code>'''
 +
* (Requires at least one Unity terrain in the scene)
 +
|-
 +
| [[File:TreeManager v111.png|50px|thumb|center]]||
 +
* Add Tree Managers to your scene '''<code>Tools -> GPU Instancer -> Add Tree Manager For Terrains</code>'''
 +
*(Requires at least one Unity terrain in the scene)
 +
|}
  
  
'''You can add a Prefab Manager from:'''
 
  
<code>Tools -> GPU Instancer -> Add Prefab Manager</code>
+
'''2. That's all. Your prefabs/details/trees will now be rendered with GPUI.
  
{| class="wikitable"
+
{| class="wikitable" style="width:800px;"
 
|-
 
|-
| [[File:HelpButton.png|frameless|border|middle]] &nbsp; You can click the question mark icon at the top-right corner of the Prefab Manager at any time to get detailed information about these settings.  
+
| [[File:HelpButton.png|frameless|border|middle]]||
 +
* In the Inspector window, you can click the question mark icon at the top-right corner to get detailed information about the settings of the manager you just added.'''
 +
|}
 +
 
 
|}
 
|}
  
  
Below are the sections you will find in the Prefab Manager.
+
Below you can find further information on the managers and their settings.
 +
 
 +
<br>
 +
 
 +
== Common Manager Settings ==
 +
<br>
 +
 
 +
The following setting sections exist in all managers with the same purposes. For the rare cases where there are manager specific options in them, the wiki sections on the specific managers below will explain those options.
  
  
 +
<div style="clear: both"></div>
 
=== Scene Settings ===
 
=== Scene Settings ===
 
----
 
----
  
  
The Scene Settings section contains scene specific settings like camera selection and global culling settings that effect all the prototypes in this manager.
+
The Scene Settings section contains scene specific settings like camera selection and global culling settings that effect all the prototypes in a manager.
 +
 
 +
 
 +
[[File:GPUI Manager SceneSettings Terrain.png|frame|left|Manager Scene Settings]]
 +
 
 +
'''Paint on Terrain:''' This button is only visible in Detail and Tree Managers, and it can be used to navigate to the Unity terrain component that a manager is referencing. Details and Trees should be painted on the terrain using Unity's native tools as usual. Detail and Tree data on the terrain will be automatically detected by GPU Instancer. GPUI also adds a script on your terrain which will show you a button to go back to the manager that is responsible for that terrain. When you are done painting, you can use the '''Go to GPUI Detail/Tree Manager''' buttons to come back to the respective managers.
 +
 
 +
 
 +
'''Unset Terrain:''' This button is only visible in Detail and Tree Managers, and it will severe the connection between the Unity terrain and this manager. You can use this to effectively disable GPUI's rendering of the terrain. It can later be enabled again by using the '''Set Terrain''' button.
  
  
Line 57: Line 89:
  
  
'''Use Occlusion Culling:''' toggles [[GPU Instancer:Terminology#Occlusion_Culling|occlusion culling]] globally for all the prototypes in this manager. By using occlusion culling, the prototypes that are not actually visible at runtime will not be rendered. This will increase rendering performance depending on the amount of occluded geometry. Please note that occlusion culling may lag if the FPS falls to extremely low levels. If this is a possibility, it could be better to turn it off. Please also check the [[GPU_Instancer:BestPractices#Using_Occlusion_Culling|Best Practices section on occlusion culling]].
+
'''Use Occlusion Culling:''' Toggles [[GPU Instancer:Terminology#Occlusion_Culling|occlusion culling]] globally for all the prototypes in this manager. By using occlusion culling, the prototypes that are not actually visible at runtime will not be rendered. This will increase rendering performance depending on the amount of occluded geometry. Please note that occlusion culling may lag if the FPS falls to extremely low levels. If this is a possibility, it could be better to turn it off. Please also check the [[GPU_Instancer:BestPractices#Using_Occlusion_Culling|Best Practices section on occlusion culling]].
  
  
 
'''Min. Culling Distance:''' You can use this slider to define 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 never be culled.
 
'''Min. Culling Distance:''' You can use this slider to define 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 never be culled.
 +
 +
 +
'''Use Floating Origin:''' If enabled, positions of the instances will automatically change when the position of the assigned transform is modified. If this manager is a Detail or Tree Manager, the transform option will not show and GPUI will change the position of the instances based on the Unity terrain.
  
 
<br>
 
<br>
 +
<div style="clear: both"></div>
  
=== Registered Prefabs ===
+
=== Prototypes ===
 
----
 
----
  
  
Registered Prefabs shows the list of registered prefab instances that are currently in the scene. These instances will be rendered with GPU Instancer.
+
The Prototypes Section shows the list of objects that will be rendered by GPU Instancer. When you add a prefab to a Prefab Manager, it is added as a GPUI Prototype - and GPUI will track the instances of this prefab in the scene and render these instances with the settings you define for this prototype. For Detail and Tree Managers, the GPUI prototypes on these managers correspond to the detail or tree prototypes on the Unity terrain. For these managers you can click the '''Generate Prototypes''' button to (re)create the GPUI prototypes from the terrain. Also, for the Detail and Tree Managers, when you add a GPUI prototype to the manager, it will be added to the terrain as well.  
 +
 
 +
 
  
 +
[[File:GPUI Manager Prototypes.png|frame|left|Manager Prototypes]]
 +
To modify the settings of a prototype, you can click on its image to select it. You can also use ctrl+click and shift+click to multi-select prototypes. GPUI will show you the available settings for the selected prototypes below the Prototypes section of the manager.
  
'''Register Prefabs in Scene:''' This button can be used to register the prefab instances that are currently in the scene, so that they can be used by GPU Instancer. When you add new instances to the scene using the Unity editor, you need to register them to GPUI again using this button to update the current instance counts. For adding new instances at runtime, you can check the [https://www.gurbu.com/apidocumentation API documentation].
 
  
=== Prototypes ===
+
'''Text/Icon Mode:''' When you toggle this button, GPUI will show the prototypes as either a list of icons (default behavior) or a list of prefab names. If you have visually similar prototypes, seeing them by prefab names can help you identify them.
----
+
 
 +
 
 +
'''Generate Prototypes:''' This button is only available in the Detail and Tree Managers. It can be used to synchronize the detail prototypes on the Unity terrain with GPU Instancer. When used, it will reset the settings of each GPUI prototype on the manager with those from the Unity terrain, and use default values for properties that don't exist on the Unity terrain.
 +
 
 +
 
 +
'''Regenerate Billboards:''' This button is only available in the Tree Manager, and regenerates the billboard atlases for all of the prototypes, also updating textures with the chosen settings in the '''Billboard Settings''' section.
 +
 
 +
 
 +
'''Add:''' Click on this button to select a prefab from your project and add it as a prototype to the manager. You can also drag and drop a prefab, a prefab instance or a GPUI prototype scriptable object on this button; in all these cases the referenced prefab is added to the manager as a prototype. For the Detail Manager, you can also add textures as prototypes; these will be added to the terrain as texture type detail prototypes.
 +
 
 +
 
 +
Note that GPUI accepts user made prefabs, and not imported model prefabs. If you wish to add a model prefab, you can first create a prefab out of it by dragging an instance of the model prefab from your scene and dropping it in your project window. Please also note that you can also use the [[GPU_Instancer:BestPractices#Scene_Prefab_Importer|Scene Prefab Importer tool]] to create a Prefab Manager with the selected prefab instances in your scene.
 +
 
 +
 
 +
'''Multi. Add:''' You can use this button to add multiple prefabs to a manager. When clicked, the manager will be locked and GPUI will show you a drop area in the form of a separate window. You can simply drag and drop your prefabs (or prefab instances) to this area and they will each be added as a separate prototype to the manager.
 +
 
 +
<br>
 +
<div style="clear: both"></div>
 +
== Common Prototype Settings ==
 +
<br>
  
 +
The following settings are prototype specific, and they are mostly the same for the prototypes of all managers.
  
Prototypes show the list of objects that will be rendered by GPU Instancer. To modify the settings of a prototype, you can click on its image.
 
  
 +
[[File:GPUI Prototype Reference.png|frame|left|Prototype References]]
  
'''Add:''' Click on this button to select a prefab from your project and add it as a prototype to the manager. You can also drag and drop a prefab, a prefab instance or a GPUI prototype scriptable object on this button; in all these cases the referenced prefab is added to the manager. You can take a look at [[GPU_Instancer:BestPractices#Adding_Multiple_Prototypes_to_an_Existing_Prefab_Manager|this section of the Best Practices Page]] to see how you can add multiple prefabs like this. Please note that you can also use the [[GPU_Instancer:BestPractices#Scene_Prefab_Importer|Scene Prefab Importer tool]] to create a Prefab Manager with the selected prefab instances in your scene.
+
All prototypes show a reference to the prefab (or texture) that they reference, and a reference to their Scriptable Object (the data object that stores all the information related to the prototype). These reference fields are not editable; they are only there to easily access the reference objects.
  
  
The following settings can be edited for each individual prototype.
+
'''Edit:''' This option is visible in the Detail and Tree Managers only, and you can click this button (or drop a prefab/texure on it) to replace the prototype's reference prefab (or texture). When you do this, the corresponding prefab/texture on the terrain will also change in the same index.
  
  
==== Shadows ====
+
<div style="clear: both"></div>
 +
=== Shadows ===
 
----
 
----
  
Line 93: Line 153:
  
  
 +
[[File:GPUI Prototype Shadows.png|frame|left|Prototype Based Shadow Settings]]
 
'''Is Shadow Casting:''' This option specifies whether the object will cast shadows or not. Turning shadows off hides the rest of the shadow options in the menu as well.
 
'''Is Shadow Casting:''' This option specifies whether the object will cast shadows or not. Turning shadows off hides the rest of the shadow options in the menu as well.
 +
 +
 +
The options below are available only for the '''Prefab Manager''':
  
  
 
'''Shadow with Original Shader:''' By default, GPUI uses a custom, lightweight "shadows only" shader to render the shadows of the prototypes that are defined on a Prefab Manager. Using this shader helps increase the shadow performance slightly more; especially if the original shader is using a shadow pass generated by a surface shader (using the addshadow directive). In most cases this shader is enough to render the prototype flawlessly; however, if the original shader uses vertex animation and/or alpha cutoff, then the shadows might not look right. Typical cases of this are when adding tree prefabs. In these cases you can enable this option to use the shadow pass of the original shaders of the prefab and the shadows should then look right.
 
'''Shadow with Original Shader:''' By default, GPUI uses a custom, lightweight "shadows only" shader to render the shadows of the prototypes that are defined on a Prefab Manager. Using this shader helps increase the shadow performance slightly more; especially if the original shader is using a shadow pass generated by a surface shader (using the addshadow directive). In most cases this shader is enough to render the prototype flawlessly; however, if the original shader uses vertex animation and/or alpha cutoff, then the shadows might not look right. Typical cases of this are when adding tree prefabs. In these cases you can enable this option to use the shadow pass of the original shaders of the prefab and the shadows should then look right.
 +
 +
  
  
Line 108: Line 174:
  
 
<br>
 
<br>
==== Culling ====
+
<div style="clear: both"></div>
 +
=== Culling ===
 
----
 
----
  
Line 115: Line 182:
  
  
 +
[[File:GPUI Prototype Culling.png|frame|left|Prototype Based Culling Settings]]
 
'''Max Distance:''' Defines the maximum distance from the selected camera within which this prototype will be rendered.
 
'''Max Distance:''' Defines the maximum distance from the selected camera within which this prototype will be rendered.
  
Line 122: Line 190:
  
 
'''Frustum Offset:''' Defines the size of the area around the camera frustum planes within which objects will be rendered while frustum culling is enabled. GPU Instancer does frustum culling on the GPU which provides a performance boost. However, if there is a performance hit (usually while rendering an extreme amount of objects in the frustum; or because of some game script), and if the camera is moving very fast at the same time, rendering can lag behind the camera movement. This could result in some objects not being rendered around the frustum edges. This offset expands the calculated frustum area so that the renderer can keep up with the camera movement in those cases.
 
'''Frustum Offset:''' Defines the size of the area around the camera frustum planes within which objects will be rendered while frustum culling is enabled. GPU Instancer does frustum culling on the GPU which provides a performance boost. However, if there is a performance hit (usually while rendering an extreme amount of objects in the frustum; or because of some game script), and if the camera is moving very fast at the same time, rendering can lag behind the camera movement. This could result in some objects not being rendered around the frustum edges. This offset expands the calculated frustum area so that the renderer can keep up with the camera movement in those cases.
 +
 +
 +
'''Is Occlusion Culling:''' Toggles [[GPU Instancer:Terminology#Occlusion_Culling|occlusion culling]] for this prototype. By using occlusion culling, the prototype instances that are not actually visible at runtime will not be rendered. This will increase rendering performance depending on the amount of occluded geometry, and since terrain details are usually quite high in instance counts it is usually very good to have it on for detail instances. Please note that occlusion culling may lag if the FPS falls to extremely low levels. If this is a possibility, it could be better to turn it off. Please also check the [[GPU_Instancer:BestPractices#Using_Occlusion_Culling|Best Practices section on occlusion culling]].
 +
 +
 +
'''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.
  
 
<br>
 
<br>
 
+
<div style="clear: both"></div>
==== LOD ====
+
=== LOD ===
 
----
 
----
  
Line 132: Line 206:
  
  
 +
[[File:GPUI Prototype LOD.png|frame|left|Prototype Based LOD Settings]]
 
'''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 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.
  
Line 139: Line 214:
  
 
'''LOD Fade Transition Width:''' You can use this value to define the cross-fading zone between LOD Levels. This zone is the distance in which the prototype LODs are cross-faded. Higher numbers result in wider transition zones. In the transition zone, both LOD levels will be rendered. This option only becomes visible if cross-fade animation is disabled.
 
'''LOD Fade Transition Width:''' You can use this value to define the cross-fading zone between LOD Levels. This zone is the distance in which the prototype LODs are cross-faded. Higher numbers result in wider transition zones. In the transition zone, both LOD levels will be rendered. This option only becomes visible if cross-fade animation is disabled.
 +
  
  
Line 144: Line 220:
  
 
<br>
 
<br>
 +
<div style="clear: both"></div>
 +
=== Billboard Settings ===
 +
----
 +
 +
 +
GPU Instancer comes with a billboard generator system. A [[GPU Instancer:Terminology#Billboards|billboard]] is a simple quad that shows snapshots of the object from different angles depending on the camera viewing angle. GPUI's billboard generator is mainly designed for use with trees so it generates snapshots of view angles around the world y axis. This means that the billboards do not have view perspectives from up or down. For detailed information on GPUI's billboard generator, you can take a look at its [[GPU_Instancer:Features#Automatic_2D_Billboard_Generation_System|section in the Features Page]]. Bilboards are a great way to increase performance while having vast viewing distances. GPUI adds the generated billboard automatically as the final LOD level (even if the prefab does not have an LOD Group on it). You can also use a custom mesh and material for the billboard if you do not wish to use the billboard that GPUI generates. All the billboard settings here can be edited for each individual prototype.
 +
 +
 +
[[File:GPUI Prototype Billboard.png|frame|left|Prototype Based Billboard Settings]]
 +
'''Generate Billboard:''' If enabled, GPU Instancer will automatically generate a camera facing billboard of this prototype to use as its final LOD level. This billboard is made of a single quad mesh, and as such it can increase the performance for distant instances greatly. The remaining billboard options will not be visible if this option is disabled.
 +
 +
 +
'''Use Custom Billboard:''' You can use a custom mesh and material with GPUIs billboard system instead of the generated billboard. When you enable this option, you will see two fields where you can assign your mesh and material. Billboard generation settings will disappear since GPUI will not be generating the billboard anymore.
  
==== Runtime Settings ====
+
 
 +
'''Billboard Quality:''' 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 "2048" option results in a 2048x256 texture resolution.
 +
 
 +
 
 +
'''Billboard 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.
 +
 
 +
 
 +
'''Billboard Brightness:''' You can use this slider to adjust the brightness of the generated billboard textures. A zero value is fully black whereas one is fully white.
 +
 
 +
 
 +
 
 +
 
 +
'''Override Original Cutoff:''' You can use this 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.
 +
 
 +
 
 +
'''Override Cutoff Amount:''' Becomes visible when you choose to override the original cutoff value. You can use the slider to adjust the cutoff amount.
 +
 
 +
 
 +
'''Replace LOD Culled With Billboard:''' If this option is enabled, GPU Instancer will use the generated billboard instead of the "Culled" distance defined in this prototype's LOD Group. Deselect this option if you want to use a custom billboard distance.
 +
 
 +
 
 +
'''Billboard Distance:''' Defines the distance to the camera in which the prototype will render as the billboard. Increase this if you want the prototypes to switch to billboards further away from the camera.
 +
 
 +
 
 +
'''Billboard Albedo Texture:''' This is the texture atlas that is generated for use with this billboard. You cannot change the texture here, but you can click on it to highlight it in the project window; so that you can view it.
 +
 
 +
 
 +
'''Billboard Normal Texture:''' This is the normal texture atlas that is generated for use with this billboard. You cannot change the normal texture here, but you can click on it to highlight it in the project window; so that you can view it.
 +
 
 +
 
 +
'''Generate Billboard:''' If you see this option then the billboard has not been generated yet. This button generates the billboard atlases for this prototype and creates the current textures with the current billboard settings.
 +
 
 +
 
 +
'''Regenerate Billboard:''' This button regenerates the billboard atlases for this prototype and updates the current textures with the changed settings.
 +
 
 +
 
 +
'''Show Billboard:''' This button instantiates a quad mesh at (0,0,0) position and shows the generated billboard on it. You can use this to inspect how the billboards will look like at runtime. You can also safely delete the generated game object from your scene once you are done inspecting.
 +
 
 +
<br>
 +
 
 +
== The Prefab Manager ==
 +
<br>
 +
[[File:GPUI-PrefabInstancing002.png|450px|thumb|left]]
 +
<br>
 +
By adding your prefabs to the GPU Instancer 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, changing material properties per instance, choosing an LOD level to render the shadows from, and much more. 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 [[GPU Instancer:Terminology|Terminology]] and the [[GPU Instancer:BestPractices|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.
 +
 
 +
<div style="clear: both"></div>
 +
[[File:AddPrefabManager v098-lowres.png|frame|left|Adding a Prefab Manager]]
 +
 
 +
'''You can add a Prefab Manager from:'''
 +
 
 +
<code>Tools -> GPU Instancer -> Add Prefab Manager</code>
 +
 
 +
{| class="wikitable"
 +
|-
 +
| [[File:HelpButton.png|frameless|border|middle]] &nbsp; You can click the question mark icon at the top-right corner of the Prefab Manager at any time to get detailed information about these settings.
 +
|}
 +
 
 +
 
 +
Below are the settings that are specific to the Prefab Manager.
 +
 
 +
 
 +
<div style="clear: both"></div>
 +
=== Registered Prefabs ===
 
----
 
----
  
  
The runtime settings that you can find here can be used to change the runtime behavior of the prototype instances. If you enable runtime modifications, the instances can be added, removed and/or updated during runtime. These modifications can either be done through the GPU Instancer API, or automatically from the manager.
+
The Registered Prefabs section shows the list of registered prefab instances that are currently in the scene. These instances will be rendered with GPU Instancer.
 +
 
 +
 
 +
[[File:GPUI Manager Registered Prototypes.png|frame|left|Prefab Manager Registered Prototypes]]
 +
The first time you add a prefab, the manager automatically registers the instances in your scene and shows the registered instance counts. However, when you add or remove instances while designing your scene, it is required to register the instances in the scene again. In this section, GPUI also shows which prototypes are currently selected. You can also shift+click or ctrl+click on the list items to select multiple prototypes.
 +
 
  
 +
Please note that the Prefab Manager will show you a warning in this section if the instance counts for some prototypes are too low, and it will also highlight the problem prototypes. The reason for this is that GPU instancing is useful only in cases where there are lots of instances with the same mesh/material combination. For more in formation on this, you can check the [[GPU_Instancer:BestPractices#Instance_Counts|Best Practices wiki article on instance counts]]. You can disable this warning form the [[GPU_Instancer:GettingStarted#GPU_Instancer_Preferences|GPU Instancer Pereferences]]. If the instance counts for a prototype are zero, GPUI simply ignores the prototype as if it didn't exist.
  
 +
 +
'''Register Instances in Scene:''' This button can be used to register the prefab instances that are currently in the scene and update the instance counts; so that they can be used by GPU Instancer. When you add new instances to the scene using the Unity editor, you need to register them to GPUI again using this button to update the current instance counts. Please note that this button does '''not''' create new prototypes from prefab instances from your scene - for that you need to drag and drop prefabs or prefab instances on the '''Add''' button. For information on adding new instances at runtime, you can check the [[GPU Instancer:API Documentation|API Documentation]].
 +
 +
<br>
 +
<div style="clear: both"></div>
 +
 +
=== Runtime Settings ===
 +
----
 +
 +
 +
The runtime settings that you can find per Prefab Manager prototype can be used to change the runtime behavior of the prototype instances. If you enable runtime modifications, the instances can be added, removed and/or updated during runtime. These modifications can either be done through the [[GPU Instancer:API Documentation|GPU Instancer API]], or automatically from the manager.
 +
 +
 +
[[File:GPUI Manager Runtime Settings.png|frame|left|Prefab Manager Prototype Runtime Settings]]
 
'''Enable Runtime Modifications:''' If this option is enabled, transform data (position, rotation, scale) for the prefab instances can be modified at runtime. This can be done either automatically (see below) or through scripting with API calls. The options below become visible only when this option is enabled.
 
'''Enable Runtime Modifications:''' If this option is enabled, transform data (position, rotation, scale) for the prefab instances can be modified at runtime. This can be done either automatically (see below) or through scripting with API calls. The options below become visible only when this option is enabled.
  
Line 159: Line 334:
  
 
'''Add/Remove Instances At Runtime:''' Enabling this option allows you to add new prefab instances or remove existing ones at runtime. This can be done either automatically (see below) or through scripting with API calls.
 
'''Add/Remove Instances At Runtime:''' Enabling this option allows you to add new prefab instances or remove existing ones at runtime. This can be done either automatically (see below) or through scripting with API calls.
 +
  
  
Line 168: Line 344:
  
 
'''Auto. Update Transform Data:''' If this option is enabled, transform updates (position, rotation and scale changes) on prefab instances will be reflected automatically on the prototype instances at runtime without the need for API calls. GPUI will track transform changes and physics movements through rigidbodies and apply them to its rendered instances automatically. Please have in mind, however, that even though GPUI efficiently keeps track of the transform changes (i.e. transform data is cached as opposed to being queried each frame), this still adds a further operation to each update. The impact of this on performance should usually not be noticeable, but if you know that your instances transforms will not be updated (that they won't move, rotate or resize) then you should not enable this option.
 
'''Auto. Update Transform Data:''' If this option is enabled, transform updates (position, rotation and scale changes) on prefab instances will be reflected automatically on the prototype instances at runtime without the need for API calls. GPUI will track transform changes and physics movements through rigidbodies and apply them to its rendered instances automatically. Please have in mind, however, that even though GPUI efficiently keeps track of the transform changes (i.e. transform data is cached as opposed to being queried each frame), this still adds a further operation to each update. The impact of this on performance should usually not be noticeable, but if you know that your instances transforms will not be updated (that they won't move, rotate or resize) then you should not enable this option.
 +
 +
<br>
 +
<div style="clear: both"></div>
 +
 +
=== Actions ===
 +
----
 +
 +
 +
'''Delete:''' You can use this button if you wish to remove the selected prototype from the Prefab Manager. GPUI will ask you whether you want to delete the prototype reference object as well. You can keep the reference object if you are using this prototype in another Prefab Manager; or simply to keep its settings in order to add the same prototype later.
  
 
<br>
 
<br>
  
==== Billboard Settings ====
+
<div style="clear: both"></div>
 +
=== Advanced Actions ===
 
----
 
----
  
  
GPU Instancer comes with a billboard generator system. A [[GPU Instancer:Terminology#Billboards|billboard]] is a simple quad that shows snapshots of the object from different angles depending on the camera viewing angle. GPUI's billboard generator is mainly designed for use with trees so it generates snapshots of view angles around the world y axis. This means that the billboards do not have view perspectives from up or down. For detailed information on GPUI's billboard generator, you can take a look at its [[GPU_Instancer:Features#Automatic_2D_Billboard_Generation_System|section in the Features Page]]. Bilboards are a great way to increase performance while having vast viewing distances. GPUI adds the generated billboard automatically as the final LOD level (even if the prefab does not have an LOD Group on it). You can also use a custom mesh and material for the billboard if you do not wish to use the billboard that GPUI generates. All the billboard settings here can be edited for each individual prototype.
+
[[File:AdvancedActions v099.png|frame|left|Prefab Manager Advanced Actions]]
 +
 
 +
The options you can see here are the advanced features that are available to access from the Prefab Manager GUI. Using these usually require a thorough understanding of how GPUI and [[GPU_Instancer:Terminology#GPU_Instancing|GPU Instancing]] in general works. If you are not experienced with the concepts at work here, it is recommended not to use the options in this menu. By default, you will find this menu collapsed; you can click on the arrow icon to the left in order to see its contents.
 +
 
 +
 
 +
'''Disable Mesh Renderers:''' By default, during initialization, GPU Instancer loops through all the GameObjects that are instances of a prototype and disables their Mesh Renderers and LOD Groups before starting its own rendering system. This is a costly operation and the impact could be seen more with increasing numbers of prototype instances in the scene. GPUI offers a workaround to this problem by disabling the Mesh Renderers on the original prefab using this button. When clicked, GPUI marks that it has disabled the Mesh Renderers (and LOD Groups) as such on the selected prototype and does not search the scene for its instances when entering play mode - increasing initialization performance. Please note that when using this option, since the Mesh Renderers are disabled on the original prefab, the scene instances will not be visible in the editor before entering the play mode. Therefore, it is recommended to use this option after you design your scenes and before building your game. Please also note that this button turns into '''Enable Mesh Renderers''' when clicked, and you can use it again to enable the Mesh Renderers back on.
 +
 
 +
 
 +
'''Serialize Registered Instances:''' This action will remove the registered prefab instances from the scene and save their transform data into a TextAsset. This is helpfull to save memory and speed up initialization by getting rid of unnecessary GameObjects. However, these objects will be visible only during play mode or editor simulation and while the Prefab Manager is active and running. You will be able to use this button again to recreate the GameObjects with the same transform data, but it is recommended to do this after you finished your scene design.
 +
 
 +
 
 +
'''Simulate at Scene Camera [Experimental]:''' This button will render the prefab instances that are disabled or serialized by these advanced actions in the scene view using GPUI. Please note that this feature is experimental; changing prototype settings and/or editing the scene may break the simulation.
 +
 
 +
<br>
 +
 
 +
<div style="clear: both"></div>
 +
 
 +
== The Detail Manager ==
 +
<br>
 +
[[File:GPUI-DetailInstancing002.png|thumb|450px|left]]
 +
The main purpose of the Detail Manager is increasing visual quality over that of the default Unity terrain details while backing this up with the indirect instancing core of GPUI for performance. You also don't have to do any extra work for this visual upgrade - GPUI simply takes your Unity terrain and makes it better looking just by adding the Detail Manager. The default settings on the manager introduce shadows for your details and turn the texture prototypes into cross-quads. The foliage shader also introduces further quality upgrades by adding ambient occlusion, color gradienting, wind wave tints, and much more to the detail instances. The Detail Manager also allows you to use custom shaders for your Unity terrain details while still using cross quads for texture details, shadows, etc.
 +
 
 +
 
 +
GPUI uses instancing techniques for backing this up performance-wise, and the result is always a stable FPS with no spikes. The [[GPU Instancer:Terminology#Occlusion_Culling|occlusion]] and [[GPU Instancer:Terminology#Frustum_Culling|frustum culling]] solutions apply to the detail prototypes as well; further increasing performance. However, please note that in some cases, the FPS would result in a number that is lower than the default Unity terrain especially if you are using features that don't exist in the Unity terrain details. The expected result when increasing visual quality in the Detail Manager, therefore, is not that it would always be faster than the Unity terrain, but that it is fast while still using these features. For more information and best practices on using the Detail Manager, you can check [[GPU_Instancer:BestPractices#Using_GPUI_for_Unity_Terrain_Details|the relevant section of the Best Practices Page]].
 +
 
 +
 
 +
When you add a Detail Manager for your terrain, the manager automatically creates GPUI prototypes from the detail prototypes that are defined in your terrain. The settings that match the Unity terrain are also transferred to the Manager (e.g. max detail distance, density, colors, etc.)
 +
 
 +
 
 +
The prototype types on the terrain result in different kinds of GPUI prototypes depending on whether they are detail textures or detail meshes. Detail textures will be handled by the manager with the GPUI foliage shader, while the prefab references of the detail meshes will be directly referenced as prefab instances. What this latter point means is that even though the Unity terrain applies its own shader and does not always correctly handle prefabs for detail prototypes, you can add them to the terrain anyway and GPUI will render them with their own materials and shaders. Furthermore, you can also add prefabs with LOD Groups on them if you add the prototypes form the Detail Manager. GPUI will add the first LOD to the terrain so that it is visible in the editor; but will use the prefab with all its LOD levels when rendering. We recommend to use LODed prefabs on your terrains as details for performance.
 +
 
 +
 
 +
Please also note that you can use the GPUI foliage shader on your prefab materials and make use of this shaders features when using prefab prototypes. You can check the '''DetailInstancingDemo''' scene to investigate how we used the detail manager settings and LODs on the detail prefabs (that also use the foliage shader).
 +
 
 +
 
 +
<div style="clear: both"></div>
 +
[[File:AddDetailManager v098-lowres.png|frame|left|Adding Detail Managers]]
 +
 
 +
'''You can add a Detail Manager from: '''
 +
 
 +
<code>Tools -> GPU Instancer -> Add Detail Manager For Terrains</code>
 +
 
 +
{| class="wikitable"
 +
|-
 +
| [[File:HelpButton.png|frameless|border|middle]] &nbsp; You can click the question mark icon at the top-right corner of the Detail Manager at any time to get detailed information about these settings.  
 +
|}
 +
 
 +
 
 +
When you click this menu item, GPU Instancer will create a Detail Manager for each Unity terrain that you have in the scene. Please note that this menu option becomes available only if you have at least one terrain in the scene.
 +
 
 +
 
 +
<div style="clear: both"></div>
 +
Please note that after you add the Detail Manager, it is recommended to add/remove/update detail prototypes on the terrain from the manager rather than directly on the terrain object. From the '''Scene Settings''' section for the Detail Manager, you can easily switch to the Unity terrain that this manager is responsible to paint details on the terrain. You can also set and unset the terrain connection with this manager from there.
 +
 
 +
 
 +
Below are the sections that are specific to the Detail Manager:
 +
 
 +
 
 +
<div style="clear: both"></div>
 +
=== Debug ===
 +
----
 +
 
 +
 
 +
The debug section is intended to show edit-time specific features. It is mainly used to simulate GPUI's rendering of terrain details without entering play mode. Since GPUI uses the data from the instances on the Unity terrain, it does not take over scene rendering and you can enable and disable GPUI in your project without loosing the terrain detail data.
 +
 
 +
 
 +
'''Simulate at Scene Camera:''' This button can be used to render the terrain details on the scene camera using the current GPU Instancer setup. This simulation is designed to provide a fast sneak peak of the GPU Instanced terrain details without having to enter play mode.
 +
 
 +
<br>
 +
 
 +
=== Global Detail Values ===
 +
----
 +
 
 +
 
 +
These settings are applied to all the detail prototypes defined in a Detail Manager. The '''Terrain Settings SO''' is a reference to the data object that contains these values and also serves as a container for the individual detail prototype data objects. This reference is not editable.
 +
 
 +
 
 +
[[File:GPUI Manager Global Detail Values.png|frame|left|Detail Manager Global Detail Values]]
 +
'''Max Detail Distance:''' Defines the maximum distance from the camera within which the terrain details will be rendered. Details that are farther than the specified distance will be culled. This setting also provides the upper limit for the maximum view distance of each detail prototype.
 +
 
 +
 
 +
'''Detail Density:''' This slider goes from 0.0 to 1.0, with 1.0 being the original density on the terrain, and lower numbers resulting in less detail objects being rendered. Thus lowering density will increase performance.
 +
 
 +
 
 +
'''Detail Texture 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.
 +
 
 +
 
 +
'''Wind Vector:''' Specifies the [X, Z] vector (world axis) of the wind for all the prototypes (in this terrain) that use the GPUI foliage shader (which is also the default shader for the texture type grass details). This vector supplies both direction and magnitude information for wind as far as detail prototypes are concerned.
 +
 
 +
 
 +
'''Healthy / Dry Noise Texture:''' This can be used to specify the Healthy Color / Dry Color variation for all the prototypes that use the GPUI foliage shader in the terrain. Texture type detail prototypes are also scaled by this noise. This image must be a greyscale noise texture.
 +
 
 +
 
 +
'''Wind Wave Normal Texture:''' This can be used to specify the vectors of all wind animations and coloring for all the prototypes that use the GPUI foliage shader in the terrain. This image must be a normal map noise texture.
 +
 
 +
<div style="clear: both"></div>
 +
'''Auto SP Cell Size:''' Detail Manager uses spatial partitioning for loading and unloading detail instances from GPU memory according to the camera position. Detail instances are grouped in cells with a calculated size. By selecting "Auto SP Cell Size", you can let the manager decide which cell size to use. If you deselect "Auto SP Cell Size", you can determine a '''Preferred SP Cell Size'''.
 +
 
 +
 
 +
'''Initialize in Threads:''' If this option is enabled, the Detail Manager makes the initialization calculations for spatial partitioning in Threads. This significantly reduces FPS drops caused by initialization, however it might take longer for the initialization to finish.
 +
 
 +
<br>
 +
 
 +
=== Detail Properties ===
 +
----
 +
 
 +
 
 +
Prototype based Detail Properties can be edited individually in this section for each prototype. The settings here will override their global counterparts.
 +
 
 +
 
 +
[[File:GPUI Prototype Detail Properties.png|frame|left|Prototype Based Detail Properties]]
 +
'''Detail Density:''' This value goes from 0.0 to 1.0, with 1.0 being the original density on the terrain, and lower numbers resulting in less detail instances being rendered. Rendering a lesser amount of detail instances can increase the performance.
 +
 
 +
 
 +
'''Detail Scale:''' These values can be used to set a range for the instance sizes of the detail prototypes. For the texture type detail prototypes, this range applies to the "Healthy / Dry Noise Texture" above. The values here correspond to the width and height values for the detail prototypes in the Unity terrain. '''X:''' Minimum Width - '''Y:''' Maximum Width - '''Z:''' - Minimum Height - '''W:''' Maximum Height
 +
 
 +
 
 +
'''Noise Spread:''' This property specifies the size of the "Healthy" and "Dry" patches for the Detail Prototype instances that use the foliage shader. This corresponds to the "Noise Spread" property of the detail prototypes in the Unity terrain. A higher number results in smaller patches. The Healthy / Dry noise texture can be changed globally for all detail prototypes that use the foliage shader from the "Healthy/Dry Noise Texture" property above; or individually by using a custom noise texture (see below).
 +
<div style="clear: both"></div>
 +
 
 +
 
 +
'''Custom Noise Texture:''' This option can be used to specify that a custom Healthy/Dry Noise Texture for this prototype. The foliage shader uses this for healthy/dry color variation and the manager will scale the prototypes based on this texture as well.
 +
 
 +
 
 +
'''Use Custom Material:''' If you wish to use a custom material (with a custom shader) for the texture type detail prototypes instead of the foliage shader, you can specify it by enabling this option. Note that cross-quading and shadows are available for custom materials as well, the ability of cross-quads to billboard at a distance will not be available since GPU Instancer handles their billboarding in the foliage shader.
 +
 
 +
 
 +
'''Custom Material:''' This field becomes visible if you choose to use a custom material for a texture type detail prototype. It can be used to specify the material that will be used instead of GPUI's foliage shader. The shader that this material uses will be automatically set up for use with GPU Instancer. This process creates a copy of the original shader (in the same folder) that has the necessary lines of code. Note that this process will NOT modify the material and is completely non-invasive.
 +
 
 +
<br>
 +
 
 +
=== Cross Quads ===
 +
----
 +
 
 +
 
 +
GPUI optionally renders the instances of texture type detail prototypes by generating cross-quads instead of the single quads used by the Unity terrain. This option can make grass and foliage on the terrain look lusher and denser; but comes at the cost of increased scene geometry. However, GPUI further optimizes this solution by billboarding the instances that are farther away for increased performance. In any case, using this option will result in less performance and better visuals in contrast to not using it. Cross-quadding can be enabled individually for each prototype, and they become visible only when the prototype is a texture type detail prototype.
 +
 
 +
 
 +
[[File:GPUI Prototype Cross Quads.png|frame|left|Detail Prototype Cross Quads]]
 +
 
 +
 
 +
'''Cross Quads:''' If enabled, a mesh with multiple quads will be generated for this detail texture (instead of a single quad or billboard). The generated quads will be equiangular to each other. Cross quadding means more polygons for a given prototype, so turning this off will increase performance if there will be a huge number of instances of this detail prototype.
 +
 
 +
 
 +
'''Quad Count:''' Defines the number of generated quads for this detail texture. Using more quads will usually improve visual quality whereas using less quads will increase performance (especially where there will be a huge number of instances of this prototype). The options are 2, 3 or 4 quads.
 +
<div style="clear: both"></div>
 +
 
 +
The following Options are available only for the prototypes that use the default '''GPUI Foliage Shader''' (not a custom material):
 +
 
 +
 
 +
'''CQ Billboard Distance:''' When cross-quadding is enabled, this option specifies the distance from the selected camera where the instances will be drawn as single quad billboards instead of cross-quads. Since instances that far away will look almost the same whether they are billboards or cross-quads, you can use this option to increase performance further without compromising too much of the visual quality. The value used here is similar to the screenRelativeTransitionHeight property of Unity LOD Groups.
 +
 
 +
 
 +
'''CQ Distance Debug:''' When cross-quadding is enabled, you can enable this option to visually test the cross-quad billboarding distance. The billboards will be rendered with a specified color for this purpose. Please note that you have to either simulate at scene camera or enter the play mode to see this effect.
 +
 
 +
 
 +
'''Debug Color:''' Visible when CQ Distance Debug is enabled, you can choose the color of the instances that will be billboarded at the specified distance.
 +
 
 +
 
 +
'''CQ Billboard Face Cam. Pos.:''' If enabled, the billboard LODs of this cross quad will ignore the camera view matrix rotations and will always face the camera position. This is ideal for VR platforms."
 +
 
 +
<br>
 +
 
 +
=== Foliage 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 <code>GPUInstancer/Foliage</code> 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 they can be used to change prototype settings individually.
 +
 
 +
 
 +
[[File:GPUI Prototype Foliage Shader Properties.png|frame|left|Detail Prototype Foliage Shader Properties]]
 +
'''Billboard:''' If enabled, the generated mesh for this prototype will be billboarded to always face the camera. Note that billboarding will turn off automatically if cross quads are enabled.
 +
 
 +
 
 +
'''Billboard Face Cam. Pos.:''' If enabled, the billboards for this prototype will ignore the camera view matrix rotations and will always face the camera position. This is ideal for VR platforms.
 +
 
 +
 
 +
'''Detail Healthy Color:''' The '''Healthy''' color of the the Healthy / Dry noise variation for the prototypes that use the foliage shader. This corresponds to the '''Healhy Color''' property of the detail prototypes in the Unity terrain. The Healthy / Dry noise texture can be changed globally (terrain specific) for all detail prototypes that use the foliage shader from the "Healthy/Dry Noise Texture" globally or on a per-prototype basis (see above).
 +
 
 +
 
 +
'''Detail Dry Color:''' The '''Dry''' color of the the Healthy / Dry noise variation for the prototypes that use the foliage shader. This corresponds to the '''Dry Color''' property of the detail prototypes in the Unity terrain. The Healthy / Dry noise texture can be changed globally (terrain specific) for all detail prototypes that use the foliage shader from the "Healthy/Dry Noise Texture" globally or on a per-prototype basis (see above).
 +
 
 +
 
 +
'''Ambient Occlusion:''' The amount of ambient occlusion to apply to the objects that use the foliage shader.
  
  
'''Generate Billboard:''' If enabled, GPU Instancer will automatically generate a camera facing billboard of this prototype to use as its final LOD level. This billboard is made of a single quad mesh, and as such it can increase the performance for distant instances greatly. The remaining billboard options will not be visible if this option is disabled.
+
'''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.
 +
<div style="clear: both"></div>
 +
 
  
 +
'''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.
  
'''Use Custom Billboard:''' You can use a custom mesh and material with GPUIs billboard system instead of the generated billboard. When you enable this option, you will see two fields where you can assign your mesh and material. Billboard generation settings will disappear since GPUI will not be generating the billboard anymore.
 
  
 +
'''Wind Waves:''' 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 globally (terrain specific) for all detail prototypes that use the foliage shader from the '''Wind Wave Normal Texture''' global property.
  
'''Billboard Quality:''' 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 "2048" option results in a 2048x256 texture resolution.
 
  
 +
'''Wind Wave Tint Color:''' This is a shader property that acts similar to the '''Grass Tint''' property of the Unity terrain, except GPUI applies this on a per-prototype basis. This color applies to the '''Wind Wave Tint''' properties of all the instances of this prototype (see below).
  
'''Billboard 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.
 
  
 +
'''Wind Wave Size:''' Specifies the size of the wind waves for the detail prototypes that use foliage shader.
  
'''Replace LOD Culled With Billboard:''' If this option is enabled, GPU Instancer will use the generated billboard instead of the "Culled" distance defined in this prototype's LOD Group. Deselect this option if you want to use a custom billboard distance.
 
  
 +
'''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.
  
'''Billboard Distance:''' Defines the distance to the camera in which the prototype will render as the billboard. Increase this if you want the prototypes to switch to billboards further away from the camera.
 
  
 +
'''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.
  
'''Generate Billboard:''' If you see this option then the billboard has not been generated yet. This button generates the billboard atlases for this prototype and creates the current textures with the current billboard settings.
 
  
 +
=== Actions ===
 +
----
  
'''Regenerate Billboard:''' This button regenerates the billboard atlases for this prototype and updates the current textures with the changed settings.
 
  
 +
'''Apply Changes To Terrain:''' This button can be used to modify the Unity terrain with the changes that are made in Detail Manager.
  
'''Show Billboard:''' This button instantiates a quad mesh at (0,0,0) position and shows the generated billboard on it. You can use this to inspect how the billboards will look like at runtime. You can also safely delete the generated game object from your scene once you are done inspecting.
+
'''Delete:''' You can use this button if you wish to remove the selected prototype from both the manager and the Unity terrain.
  
 
<br>
 
<br>
 +
 +
== The Tree Manager ==
  
 
<br>
 
<br>
By adding your prefabs to the GPU Instancer 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, changing material properties per instance, choosing an LOD level to render the shadows from, and much more. Note that the Prefab Manager only accepts user created prefabs. It will not accept prefabs that are generated when importing your 3D model assets.  
+
[[File:GPUI-TreeInstancing001.png|450px|thumb|left]]
 +
 
 +
 
 +
You can use the Tree Manager to instance Unity terrain trees. If you want to use trees without registering them to the Unity terrain, you can use the Prefab Manager instead. Adding a Tree Manager to your scene will let GPUI take the tree data from the Unity Terrain and generate the required GPUI prototypes. The tree manager also enables billboarding for the tree prototypes automatically, and generates the billboards.
 +
 
 +
 
 +
The Tree Manager supports SpeedTree, TreeCreator and most of the custom tree shaders. For SpeedTrees, GPUI will use the generated billboard instead of the SpeedTree Billboard LOD - for all other trees, the generated billboard is used as a final LOD level.
 +
 
 +
 
 +
<div style="clear: both"></div>
 +
[[File:AddTreeManager v098-lowres.png|frame|left|Adding Tree Managers]]
 +
 
 +
'''You can add a Tree Manager from:'''
 +
 
 +
<code>Tools -> GPU Instancer -> Add Tree Manager For Terrains</code>
 +
 
 +
{| class="wikitable"
 +
|-
 +
| [[File:HelpButton.png|frameless|border|middle]] &nbsp; You can click the question mark icon at the top-right corner of the Tree Manager at any time to get detailed information about these settings.
 +
|}
 +
 
 +
 
 +
When you click this menu item, GPU Instancer will create a Tree Manager for each Unity terrain that you have in the scene. Please note that this menu option becomes available only if you have at least one terrain in the scene. Below are the sections you will find in the Tree Manager.
 +
 
 +
 
 +
<div style="clear: both"></div>
 +
Please note that after you add the Tree Manager, it is recommended to add/remove/update tree prototypes on the terrain from the manager rather than directly on the terrain object. From the '''Scene Settings''' section for the Tree Manager, you can easily switch to the Unity terrain that this manager is responsible to paint details on the terrain. You can also set and unset the terrain connection with this manager from there.
 +
 
 +
 
 +
Below are the sections that are specific to the Tree Manager:
 +
 
 +
 
 +
<div style="clear: both"></div>
 +
=== Global Tree Values ===
 +
----
 +
 
 +
 
 +
These settings are applied to all the tree prototypes defined in a Tree Manager. The '''Terrain Settings SO''' is a reference to the data object that contains these values and also serves as a container for the individual detail prototype data objects. This reference is not editable.
 +
 
 +
 
 +
[[File:GPUI Manager Global Tree Values.png|frame|left|Tree Manager Global Tree Values]]
 +
 
 +
 
 +
'''Max Tree Distance:''' Defines the maximum distance from the camera within which the terrain trees will be rendered. Trees that are farther than the specified distance will not be visible. This setting also provides the upper limit for the maximum view distance of each tree prototype.
 +
 
  
 +
'''Initialize With Coroutine:''' if enabled, makes the initialization calculations for tree instances in a Coroutine. This significantly reduces FPS drops caused by initialization, however it might take longer for the initialization to finish.
  
 
<div style="clear: both"></div>
 
<div style="clear: both"></div>
 +
=== Actions ===
 +
----
 +
 +
 +
'''Delete:''' You can use this button if you wish to remove the selected prototype from both the manager and the Unity terrain.
  
== The Detail Manager ==
 
 
<br>
 
<br>
[[File:GPUI-DetailInstancing002.png|thumb|left]]
 
The main purpose of the Detail Manager is increasing visual quality over that of the default Unity terrain details while backing this up with the indirect instancing core of GPUI for performance. You also don't have to do any extra work for this visual upgrade - GPUI simply takes your Unity terrain and makes it better looking just by adding the Detail Manager. The default settings on the manager introduce shadows for your details and turns the texture prototypes into cross-quads. The foliage shader also introduces further quality upgrades by adding ambient occlusion, color gradienting, wind wave tints, and much more to the detail instances. The Detail Manager also allows you to use custom shaders for your Unity terrain details while still using cross quads for texture details, shadows, etc.
 
  
 +
== GPU Instancer Preferences ==
 +
<br>
 +
 +
[[File:GPUI Preferences.png|frame|left|GPU Instancer Preferences]]
 +
 +
 +
GPU Instancer includes a Preferences Window where you can change setting that effect all the GPUI managers and prototypes. This window also can be used to execute various version update specific jobs and extract desired extra packages.
 +
 +
 +
'''You can access the GPU Instancer Preferences Window from:'''
 +
 +
<code>Edit -> Preferences -> GPU Instancer</code>
  
GPUI uses instancing techniques for backing this up performance-wise, and the result is always a stable FPS with no spikes. The [[GPU Instancer:Terminology#Occlusion_Culling|occlusion]] and [[GPU Instancer:Terminology#Frustum_Culling|frustum culling]] solutions apply to the detail prototypes as well; further increasing performance. However, please note that in some cases, the FPS would result in a number that is lower than the default Unity terrain especially if you are using features that don't exist in the Unity terrain details. The expected result when increasing visual quality in the Detail Manager, therefore, is not that it would always be faster than the Unity terrain, but that it is fast while still using these features. For more information and best practices on using the Detail Manager, you can check [[GPU_Instancer:BestPractices#Using_GPUI_for_Unity_Terrain_Details|the relevant section of the Best Practices Page]].
+
 
 +
{| class="wikitable"
 +
|-
 +
| [[File:HelpButton.png|frameless|border|middle]] &nbsp; You can hover your mouse over the labels for each setting to get detailed information about them.&nbsp;
 +
|}
 +
 
 +
 
 +
<div style="clear: both"></div>
 +
 
 +
 
 +
The following are the options that you can access from this window:
 +
 
 +
 
 +
=== Constants ===
 +
----
 +
 
 +
 
 +
'''Max Detail Distance:''' Defines the maximum distance from the camera within which the terrain details will be rendered. Details that are farther than the specified distance will not be visible. This setting also provides the upper limit for the maximum view distance of each detail prototype.
 +
 
 +
 
 +
'''Max Tree Distance:''' Defines the maximum distance from the camera within which the terrain trees will be rendered. Trees that are farther than the specified distance will not be visible. This setting also provides the upper limit for the maximum view distance of each tree prototype.
 +
 
 +
 
 +
'''Max Prefab Distance:''' Defines the maximum distance from the camera within which Prefab Manager prototypes will be rendered.
 +
 
 +
 
 +
'''Max Prefab Extra Buffer Size:''' Specifies the maximum amount of prefab instances that can be added without re-initializing compute buffers at runtime. Instances can be added at runtime with API calls or by enabling ''Automatically Add/Remove Instances'' option from the Prefab Manager.
 +
 
 +
 
 +
'''Instancing Bounds Size:''' Defines the bounds parameter's size for the instanced rendering draw call.
 +
 
 +
 
 +
=== Behavior ===
 +
----
 +
 
 +
 
 +
'''Auto Generate Billboards:''' If enabled, billboard textures will be automatically generated for known tree types when they are added to the GPUI Managers.
 +
 
 +
 
 +
'''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.
 +
 
 +
 
 +
'''Disable Instance Count Warnings:''' If enabled, Prefab Manager will not show warnings for prototypes with low instance counts.
 +
 
 +
 
 +
=== VR ===
 +
----
 +
 
 +
 
 +
'''VR Rendering Mode:''' You can set which VR rendering mode you are using in your project here. Setting this will allow GPUI to use the correct rendering mode for VR operations such as occlusion culling. Please note that in Unity versions 2018.3 and above, this is automatically detected by GPUI and this option will not be visible.
 +
 
 +
 
 +
'''Test Both Eyes for VR Occ. Culling:''' If disabled, GPUI will run occlusion test calculations for the left VR eye only. When enabled, both eyes will be tested. Testing both eyes can put more load on the GPU in some cases, but culling results will always be more accurate.
 +
 
 +
 
 +
=== Theme ===
 +
----
 +
 
 +
 
 +
'''Custom Preview BG Color:''' If enabled, a custom background color can be used for preview icons of the prototypes.
 +
 
 +
 
 +
'''Preview BG Color:''' The custom background color to be used for preview icons of the prototypes.
 +
 
 +
 
 +
=== Update Jobs ===
 +
----
 +
 
 +
 
 +
If any actions are required after updating GPUI to a new version, you will be able to execute these actions from this section.
 +
 
 +
 
 +
=== Package Definitions ===
 +
----
 +
 
 +
 
 +
You can see which optional GPUI packages are loaded for this section. You can also remove individual packages or reload them.
 +
 
 +
== Tools ==
 +
 
 +
=== Scene Prefab Importer ===
 +
 
 +
[[File:GPUI-v097-ScenePrefabImporter.jpg|thumb|left]]
 +
 
 +
GPUI comes with a '''Scene Prefab Importer''' tool that can help you to easily create a Prefab Manager in your scene with the prefab instances in your scene as prototypes. This can reduce the amount of work greatly if you have a lot of prefabs in your scene, since you will be able to setup your Prefab Manager in only a few clicks. The Scene Prefab Importer also helps you to see the amounts prefab of instances that you have in the scene, and allows you to easily add prototypes that are above a certain instance count.
  
  
When you add a Detail Manager for your terrain, the manager automatically creates GPUI prototypes from the detail prototypes that are defined in your terrain. The settings that match the Unity terrain are also transferred to the Manager (e.g. max detail distance, density, colors, etc.)
+
Instance counts are among the most important things to consider when adding a prefab to GPUI as a prototype to render with it. You can check [[GPU_Instancer:BestPractices#Instance_Counts|the section on the Best Practices Page]] about this for more information.
  
  
The prototype types on the terrain result in different kinds of GPUI prototypes depending on whether they are detail textures or detail meshes. Detail textures will be handled by the manager with the GPUI foliage shader, while the prefab references of the detail meshes will be directly referenced as prefab instances. What this latter point means is that even though the Unity terrain applies its own shader and does not always correctly handle detail prototypes, you can add them to the terrain anyway and GPUI will render them with their own materials and shaders. Furthermore, you can also add prefabs with LOD Groups on them if you add the prototypes form the Detail Manager. GPUI will add the first LOD to the terrain so that it is visible in the editor; but will use the prefab with all its LOD levels when rendering. We recommend to use LODed prefabs on your terrains as details for performance.
+
'''Using the Scene Prefab Importer Tool is very easy. You can access it from:'''
  
 +
<code>Tools --> GPU Instancer --> Show Scene Prefab Importer</code>
 +
 +
{| class="wikitable"
 +
|-
 +
| [[File:HelpButton.png|frameless|border|middle]] &nbsp; You can click the question mark icon at the top-right corner of the Scene Prefab Importer at any time to get detailed information about these settings.
 +
|}
  
Please also note that you can use the GPUI foliage shader on your prefab materials and make use of this shaders features when using prefab prototypes. You can check the '''DetailInstancingDemo''' scene to investigate how we used the detail manager settings and LODs on the detail prefabs (that also use the foliage shader).
 
  
 +
The Scene Prefab Importer tool will show you all the GameObjects in the open scene that are instances of a Prefab - and their instance counts in the scene. You can use the '''Select Min. Instance Count''' slider and button to select prefabs with a given minimum amount. You can then '''Import Selected Prefabs''' and GPUI will create a Prefab Manager in your scene with selected prefabs as prototypes.
  
 
<div style="clear: both"></div>
 
<div style="clear: both"></div>
[[File:AddDetailManager v098-lowres.png|frame|left|Adding Detail Managers]]
 
[[File:DetailManager v098.png|frame|left|The Detail Manager]]
 
  
'''You can add a Detail Manager from:'''
+
=== The Prefab Replacer ===
 +
 
 +
[[File:GPUI-v098-PrefabReplacer.png|thumb|left|The Prefab Replacer Tool]]
 +
 
 +
GPUI comes with a '''Prefab Replacer''' tool that can help you to easily replace GameObjects in your scene hierarchy with prefab instances in a few clicks. This is very helpful especially if you did not follow a prefab workflow when creating your scene. You can also use this to easily replace instances of one or multiple prefabs with another while still keeping the transform data (positions, rotations and scales).
 +
 
 +
 
 +
'''Using the Scene Prefab Importer Tool is very easy. You can access it from:'''
  
<code>Tools -> GPU Instancer -> Add Detail Manager For Terrains</code>
+
<code>Tools --> GPU Instancer --> Show Prefab Replacer</code>
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
| [[File:HelpButton.png|frameless|border|middle]] &nbsp; You can click the question mark icon at the top-right corner of the Detail Manager at any time to get detailed information about these settings.  
+
| [[File:HelpButton.png|frameless|border|middle]] &nbsp; You can click the question mark icon at the top-right corner of the Prefab Replacer at any time to get detailed information about these settings.  
 
|}
 
|}
  
  
When you click this menu item, GPU Instancer will create a Detail Manager for each Unity terrain that you have in the scene. Below are the sections you will find in the Detail Manager.
+
To use this tool, you can select multiple GameObjects by either shift clicking or ctrl/cmd clicking on them. The Prefab Replacer will show you the selected GameObjects' names. You can then assign a prefab in the tool; the selected GameObjects will be replaced with instances of this selected prefab. You can also choose to replace the names as well, which will properly name the new GameObjects with respect to the selected prefab. Clicking '''Replace Selection with Prefab''' button will execute the operation.
 +
 
 +
 
 +
Don't forget to save your scene, and if the selected Prefab is already registered as prototype on a Prefab Manager, do not forget to '''Register Instances in Scene''' to update the instance counts.
 +
 
 +
<div style="clear: both"></div>
 +
 
 +
=== Clear Shader Bindings ===
 +
 
 +
 
 +
GPU Instancer automatically generates new versions of the shaders that are on the materials of your prototypes. The generated shaders are exactly the same with the original shader; the only difference being they are setup to work with GPUI. These shaders always in the same directory where the original shader is, and their filenames end with a '''[_GPUI]''' suffix. Also, these shaders always show as starting with '''[GPUInstancer/]''' followed by the original shader name.
 +
 
 +
 
 +
GPUI internally keeps track of these shaders and re-generates them if the original shader is modified. '''Shader Bindings''' is an internal object that keeps track of these shaders. If for any reason you wish to clear this object, you can use the '''Clear Shader Bindings''' menu item for this. You can access it from:
 +
 
 +
 
 +
<code>Tools --> GPU Instancer --> Clear Shader Bindings</code>
 +
 
 +
 
 +
You can also use this tool to delete the shaders that GPUI generated. The tool will first ask you whether you really want to clear the shader bindings object, the ask also if it should delete the generated shaders. Please note that both operations are completely safe and this tool will never touch your original shaders. Also, the managers will instantly generate the necessary shaders again, so you don't have to worry about breaking GPUI while using this.
 +
 
 +
<br>
 +
 
 +
== Components ==
 +
<br>
 +
=== GPUI Modification Collider ===
 +
----
 +
 
 +
 
 +
[[File:GPUIModificationCollider600.gif|frame|450px|left|GPUI Modification Collider]]
 +
 
 +
GPU Instancer comes with a component that you can use to disable instancing inside a zone. This is called the '''GPU Instancer Modification Collider''', and it can help you manage physics with GPUI in a more efficient way and with better performance.
 +
 
 +
 
 +
The Modication Collider component can be used in various scenarios; for example in the '''PrefabInstancingDemo''' it is used to activate Rigidbodies on the asteroids that are close to the Spaceship. The Rigidbodies in this example move the asteroids around upon collision with the spaceship. When they stop moving (i.e enter Sleep state), The Modification Collider turns back instancing on them and deactivates their Rigidbodies again if they are outside the de-instancing zone.
 +
 
 +
 
 +
The zone in which the Modification Collider works is determined by a [https://docs.unity3d.com/Manual/CollidersOverview.html trigger type Collider] that must also exist on the same GameObject that the Modification Collider component exists - hence the name of the component.
 +
 
 +
 
 +
Notice that you have to '''Enable Runtime Modifications''' for the prefabs that you wish to effect this way in the Prefab Manager; however you do not need to enable any other options in the '''Runtime Settings''' section. This is because transform/physics updates are not applied automatically for the instances that reside outside the Modification Collider at runtime, and this will result in better performance. You can see in [https://www.gurbu.com/demobuilds the downloadable demos] that GPUI can render 200k asteroids with physics in around 150-200 FPS by using this technique. The asteroid counts could even go much higher, but you need to follow a no-game object workflow for that since Unity restricts Collider usage to around 260k.
 +
 
 +
<div style="clear: both"></div>
 +
 
 +
<br>
 +
[[File:GPUIModificationCollider.png|frame|left|GPUI Modification Collider (Inspector)]]
  
  
=== Scene Settings ===
+
'''Using the Modification Collider is very simple:'''
 +
 
 +
 
 +
'''1)''' Add the included '''GPUInstancerModificationCollider.cs''' script to any GameObject with a Collider (must be trigger). This GameObject's collider will be used for the de-instancing zone. You can use the <code>Add Component</code> button in the inspector window to add the script as a component to this GameObject.
 +
 
 +
 
 +
'''2)''' Enable the option <code>Enable Runtime Modifications</code> in the '''Prefab Manager''' for the prefabs you want to be effected by the de-instancing zone.
 +
 
 +
 
 +
'''3) Optional:''' Assign the desired Prefab Manager to the Modification Collider's respective field. If you don't assign any, the first found Prefab Manager in the scene will be used to determine the prototypes.
 +
 
 +
That's all. The GameObject you added this can move at the runtime which will also move the de-instancing zone, and if your prototype prefabs have Rigidbody components on them, these components will be activated in the zone and deactivated when they're out and still.
 +
 
 +
 
 +
Please note that the Modification Collider will use only the first Collider if your GameObject has multiple.
 +
 
 +
<div style="clear: both"></div>
 +
 
 +
<br>
 +
 
 +
=== GPUI Instance Remover ===
 
----
 
----
  
  
The Scene Settings section contains scene specific settings like camera selection and global culling settings that effect all the prototypes in this manager. You can also easily switch to the Unity terrain that this manager is responsible for to paint details on the terrain. You can also set and unset the terrain connection with this manager from here.  
+
[[File:GPUIInstanceRemover600.gif|frame|450px|left|GPUI Instance Remover]]
  
  
Please note that after you add the Detail Manager, it is recommended to add/remove/update detail prototypes on the terrain from the manager rather than directly on the terrain object.
+
GPU Instancer comes with a component that you can use to easily remove instances from your scenes at runtime without any code. This component becomes particularly useful if you're using the Detail Manager; you can use it, for example, to remove the grass under a placed building at runtime. However, it can also be used for all the instances that are rendered by GPUI (including the Tree Manager and the Prefab Manager). This component is the '''GPU Instancer Instance Remover'''.
  
  
'''Paint on Terrain:''' This button can be used to navigate to the Unity terrain component that this manager is referencing. Details should be painted on the terrain using Unity's native tools as usual. Detail data on the terrain will be automatically detected by GPU Instancer. GPUI also adds a script on your terrain which will show you a button to go back to the manager that is responsible for that terrain. When you are done painting, you can use the '''Go to GPUI Detail Manager''' button to come back to the manager.
+
The Instance Remover will use either the bounds of the GameObject that it is on, or its Colliders to remove the instances that fall inside these zones. The removal of the instances is extremely fast (as you can see in the '''DetailInstancingDemo''' scene's grass mower) so you can even use it to remove instances in every Update loop.  
  
  
'''Unset Terrain:''' This button will severe the connection between the Unity terrain and this manager. You can use this to effectively disable GPUI's rendering of the terrain. It can later be enabled again by using the '''Set Terrain''' button.
+
Please note that the instances will be removed from GPUI's runtime session, and not the terrain itself. When you instantiate GameObjects with an Instance Remover component on them (or enter the playmode with them), the instances that fall inside the Bounds/Colliders of these GameObjects will instantly be removed. Notice that you can have as many of these as you like.
  
  
'''Auto Select Camera:''' When this checkbox is active, GPU Instancer will use the first camera with the '''MainCamera''' tag at startup. If the checkbox is inactive, the desired camera can be set manually. GPU Instancer uses this camera for various calculations including culling operations.
+
<div style="clear: both"></div>
 +
 
 +
[[File:GPUIInstanceRemover.png|frame|left|GPUI Instance Remover (Inspector)]]
 +
 
 +
'''Using the Instance Remover is very simple:'''
 +
 
 +
 
 +
1) Add the included '''GPUInstancerInstanceRemover.cs''' script to any GameObject with a Collider. This GameObject's Collider or Collider Bounds (faster) will be used for instantly removing GPUI instances at runtime. You can use the Add Component button in the inspector window to add the script as a component to this GameObject.
 +
 
 +
 
 +
2) That's actually all, you don't need to do anything else. The Instance Remover is an imposing GPUI component, so you don't need to have any additional settings on the managers or prototypes to use it; it will also target all active GPUI managers so you don't have to specify a manager.
 +
 
 +
 
 +
There are a few options on the Instance Remover:
 +
 
 +
 
 +
'''Use Bounds:''' If this is selected, GPUI will use object Bounds instead of the Colliders for removing instances.
 +
 
 +
 
 +
'''Sellected Colliders:'''' You can see a list of Volliders that the Instance Remover will be using in this list. This list is automatically constructed upon [https://docs.unity3d.com/ScriptReference/MonoBehaviour.Reset.html Component Reset]. The list contains all the components also in the child GameObjects of this GameObject. All of these Colliders are encapsulated to calculate the removal zone. If you're adding the Instance Remover component from script, you can modify this list after adding the script to define the Colliders that you wish to use with it.
 +
 
 +
 
 +
'''Remove from Detail Manager:''' If this is enabled, the Instance Remover will remove prototype instances that are defined in Detail Managers as well. If not enabled, it will ignore them.
 +
 
 +
 
 +
'''Remove from Tree Manager:''' If this is enabled, the Instance Remover will remove prototype instances that are defined in Tree Managers as well. If not enabled, it will ignore them.
 +
 
 +
 
 +
'''Remove from Prefab Manager:''' If this is enabled, the Instance Remover will remove prototype instances that are defined in Prefab Managers as well. If not enabled, it will ignore them.
 +
 
 +
 
 +
'''Remove at Update:''' Specifies whether GPUI will use this Instance Remover during the Update loop. Disabling this option will cause removal upon instantiating this object only, and the Instance Remover will not do anything during the Update Loops.
  
  
'''Use Selected Camera Only:''' If enabled, instances will only be rendered with the selected camera. They will not be rendered in other active cameras (including the Scene View camera). This may improve performance if there are other cameras in the scene that are mainly used for camera effects, weather/water effects, reflections, etc. Using this option will make them ignore GPUI, increasing performance. Please note that the scene view during play mode will no longer show GPUI instances if this is selected.
+
'''Offset:''' With this option you can specify an offset that will be used to expand or shrink the area that is calculated from the Bounds/Colliders.
  
  
'''Use Frustum Culling:''' Toggles [[GPU Instancer:Terminology#Frustum_Culling|frustum culling]] globally for all the prototypes in this manager. By turning frustum culling off, you can have view GPUI prototypes in all active cameras since they will not be culled. However, please note that turning frustum culling off may result in a lower FPS than having it on. If turned on, you can still turn frustum culling off for individual prototypes.
+
Please also note that what the Instance Remover is doing is actually using two API methods that you can directly use instead. These are the <code>[[GPU_Instancer:API_Documentation#RemoveInstancesInsideBounds|RemoveInstancesInsideBounds]]</code> and <code>[[GPU_Instancer:API_Documentation#RemoveInstancesInsideCollider|RemoveInstancesInsideCollider]]</code> methods.
  
 +
<div style="clear: both"></div>
 +
<br>
  
'''Use Occlusion Culling:''' toggles [[GPU Instancer:Terminology#Occlusion_Culling|occlusion culling]] globally for all the prototypes in this manager. By using occlusion culling, the prototypes that are not actually visible at runtime will not be rendered. This will increase rendering performance depending on the amount of occluded geometry. Please note that occlusion culling may lag if the FPS falls to extremely low levels. If this is a possibility, it could be better to turn it off. Please also check the [[GPU_Instancer:BestPractices#Using_Occlusion_Culling|Best Practices section on occlusion culling]].
+
=== GPUI GUI Info ===
 +
----
  
  
'''Min. Culling Distance:''' You can use this slider to define 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 never be culled.
+
GPU Instancer also has an Info script that you can use for Debugging purposes. You can add the '''GPUInstancerGUIInfo.cs''' script at any GameObject in your scene and it will overlay a small red text on your camera that shows information on the GPUI prototypes. The inspector options on this script are self explanatory, but please notice that if you use the '''Show Rendered Amount''' option it will cause a readback from the GPU each frame and this will cause a great performance hit. You can, however have that information for debugging purposes.
  
 +
<div style="clear: both"></div>
 
<br>
 
<br>
  
=== Debug ===
+
=== GPUI LOD Color Debugger ===
 
----
 
----
  
  
The debug section is intended to show edit-time specific features. It is mainly used to simulate GPUI's rendering of terrain details without entering play mode. Since GPUI uses the data from the instances on the Unity terrain, it does not take over scene rendering and you can enable and disable GPUI in your project without loosing the terrain detail data.
+
[[File:GPUI-LODColorDebugger.png|450px|thumb|left|GPUI LOD Color Debugger]]
 +
You can use the included script '''GPUInstancerLODColorDebugger.cs''' to visualize the LOD levels of your GPUI prototypes during runtime. This script can be added on the manager GameObject for automatic setup. Please note that the shader that is used by the prototype must have a '''_Color''' property for this to work.
 +
 
 +
<div style="clear: both"></div>
 +
<br>
 +
 
 +
== Extension: Crowd Animations ==
 +
<br>
 +
 
 +
[[File:CrowdAnim-StoreBanner-Small-450.png|450px|left|thumb]]
 +
 
 +
 
 +
'''[https://assetstore.unity.com/packages/tools/animation/gpu-instancer-crowd-animations-145114 GPU Instancer - Crowd Animations] is available as a separate asset in the Unity Asset Store.'''
 +
 
 +
 
 +
Crowd Animations is an an extension for GPUI that is designed for using massive amounts of animated characters in your scenes with high performance. CA uses the GPU Instancer core and adds GPU skinning techniques on top of GPUI's indirect instancing solution and GPU culling techniques. This results in a combination which will allow you to get the most out of GPU Instancing in Unity for your animated characters.  
 +
 
  
 +
Crowd Animations works by baking the bone data of animation clips into a texture and reading that texture in [[GPU Instancer:Terminology#Compute_Shaders|Compute Shaders]] to feed skinning data to the rendering pipeline for indirect skinned-mesh instancing. Using the GPU Instancer backend for visibility tests in the GPU as well, the Crowd Animations extension is designed to be the ultimate solution for a GPU based animation workflow.
  
'''Simulate at Scene Camera:''' This button can be used to render the terrain details on the scene camera using the current GPU Instancer setup. This simulation is designed to provide a fast sneak peak of the GPU Instanced terrain details without having to enter play mode.
 
  
 +
<div style="clear: both"></div>
 
<br>
 
<br>
  
=== Global Detail Values ===
+
=== The Crowd Manager ===
 
----
 
----
  
  
These settings are applied to all the detail prototypes defined in the manager.
+
[[File:GPUI-CrowdAnimations-Chompers450.gif|450px|frame|left]]
 +
 
 +
 
 +
The Crowd Manager allows you to use GPUI's indirect instancing with skinned mesh renderers, allowing you to define animated characters as prototypes to GPUI. Using the Crowd Manager, you can have massive amounts of characters that are animated individually with high performance. The Crowd Manager is also fully integrated into the GPUI core, meaning that it allows for LODs, multiple skinned meshes and multiple submeshes on your prototypes. Furthermore, GPUI's culling techniques such as GPU occlusion and frustum culling also apply to the prototypes of this manager.
 +
 
 +
 
 +
You can use the Crowd Manager a lot like how you use the [[GPU_Instancer:GettingStarted#The_Prefab_Manager|Prefab Manager]]: by adding your character prefabs to the Manager, the instances of these prefabs in your scenes will be rendered by GPU Instancer. Also, just like the Prefab Manager, the Crowd Manager provides additional functionality such as adding/removing/updating instances at runtime, choosing an LOD level to render the shadows from, and much more.
 +
 
 +
 
 +
Note that the Crowd Manager only accepts user created prefabs. It will not accept prefabs that are generated when importing your 3D model assets. Please also note that, to use a prefab with the Crowd Manager, the prefab must have an Animator Component on it, and must also have Skinned Mesh Renderer(s). The animation clips that are in the Animator component will be baked and the Skinned Mesh Renderers will be used to gather the bone data.
 +
 
 +
 
 +
<div style="clear: both"></div>
 +
[[File:AddCrowdManager.png|frame|left|Adding a Crowd Manager]]
 +
 
 +
 
 +
'''You can add a Crowd Manager from:'''
 +
 
 +
<code>Tools -> GPU Instancer -> Add Crowd Manager</code>
 +
 
 +
{| class="wikitable"
 +
|-
 +
| [[File:HelpButton.png|frameless|border|middle]] &nbsp; You can click the question mark icon at the top-right corner of the Crowd Manager at any time to get detailed information about these settings.
 +
|}
 +
 
 +
 
 +
Crowd Animations supports two different animator workflows: The '''Mecanim Animator workflow''' and the '''Crowd Animator workflow'''. Below, you can find information on how you can setup the Crowd Manager for both of these workflows.
 +
 
 +
 
 +
<div style="clear: both"></div>
 +
<br>
  
 +
=== Adding the Character Prototypes ===
 +
----
  
'''Max Detail Distance:''' defines the maximum distance from the camera within which the terrain details will be rendered. Details that are farther than the specified distance will not be visible. This setting also provides the upper limit for the maximum view distance of each detail prototype.
 
  
 +
[[File:CA-RegisteredPrefabs.png|450px|thumb|left|The Crowd Manager: Registered Prototypes]]
  
'''Detail Density:''' goes from 0.0 to 1.0, with 1.0 being the original density, and lower numbers resulting in less detail objects being rendered.
 
  
 +
You can add an animated character to the Crowd Manager as a [[GPU_Instancer:GettingStarted#Prototypes|GPUI Prototype]] as usual by either dragging and dropping its prefab on the '''Add''' Button (or the '''Multi. Add''' area), or by clicking the '''Add''' button to choose its prefab. This prefab must have at least one Skinned Mesh Renderer, and must also be a '''User Created Prefab''' and not a '''Model Prefab''' that is generated when importing your 3D character models.
  
'''Wind Vector:''' specifies the [X, Z] vector (world axis) of the wind for all the prototypes (in this terrain) that use the "GPUInstancer/Foliage" shader (which is also the default shader for the texture type grass details). This vector supplies both direction and magnitude information for wind.
 
  
 +
For both the '''Mecanim Animator workflow''' and the '''Crowd Animator workflow''', the next step is to bake the '''animation texture''', and GPUI will use the same texture for both workflows. In order to bake this animation texture, there must be an '''Animator''' component on the added prefab. When the animation texture is baked, GPUI will gather the animation clips from this Animator component. Therefore, for both workflows, the prefab must also have an Animator Component on it that will define the available animation clips for this prototype.
  
'''Healthy / Dry Noise Texture:''' can be used to specify the Healthy Color / Dry Color variation for all the prototypes that use the "GPUInstancer/Foliage" shader in this terrain (which is also the default shader for the texture type grass details). Texture type detail prototypes are also scaled by this noise. This image must be a greyscale noise texture.
 
  
 +
The '''Registered Prototypes''' section works exactly like it does in the [[GPU_Instancer:GettingStarted#Registered_Prefabs|Prefab Manager]]. It shows the list of registered prefab instances and their current instance counts in the scene. The first time you add a prefab, the manager automatically registers the instances in your scene and shows the registered instance counts. When you add or remove instances while designing your scene, it is required to register the instances in the scene again by using the '''Register Instances in Scene''' button.
  
'''Wind Wave Normal Texture:''' can be used to specify the vectors of all wind animations and coloring for all the prototypes that use the "GPUInstancer/Foliage" shader in this terrain (which is also the default shader for the texture type grass details). This image must be a normal map noise texture.
 
  
 +
The '''Prototypes''' Section shows the list of animated characters that are added to the Crowd Manager as prototypes and will be rendered by GPU Instancer. By clicking on the icons of these prototypes (or their prefab names in the Text Mode) you can select each prototype and edit their settings individually. You can also shift or ctrl click on them to edit some settings for multiple prototypes at once. GPUI will track the instances of the prefabs in the scene and render these instances with the settings you define for these prototypes.
  
'''Auto SP Cell Size:''' Detail Manager uses spatial partitioning for loading and unloading detail instances from GPU memory according to camera position. Detail instances are grouped in cells with a calculated size. By selecting "Auto SP Cell Size", you can let the manager decide which cell size to use. If you deselect "Auto SP Cell Size", you can determine a "Prefered SP Cell Size".
 
  
 +
Once you add a prototype, you can than go ahead and bake the animation texture for this prototype from the '''Animation Bake Data''' section.
 +
 +
 +
<div style="clear: both"></div>
 
<br>
 
<br>
  
=== Prototypes ===
+
=== Baking the Animation Texture ===
 
----
 
----
  
  
Prototypes show the list of objects that will be used in GPU Instancer. To modify a prototype, click on its image.
+
[[File:CA-AnimationBakeData.png|450px|thumb|left|Baking the Animation Data]]
 +
[[File:CA-CrowdPrefabDebugger.png|450px|thumb|left|Testing the Animation Data]]
  
 +
Crowd Animations works by baking the bone data of animation clips into a texture and reading that texture at runtime in [[GPU Instancer:Terminology#Compute_Shaders|Compute Shaders]] to animate a Skinned Mesh.
 +
 +
 +
Because of this, both Crowd Animations workflows require you to bake the animation texture first. When you add a prefab that has an Animator component to the Crowd Manager, you can use the '''Animation Bake Data''' section in the Crowd Manager to bake this animation texture and test the baked animations.
 +
 +
 +
'''Frame Rate:''' The number of frames per second that the animation will be played in. A higher frame rate will result in a smoother animation playback, but also a larger animation texture size.
 +
 +
 +
'''Animation Texture:''' This is the Animation texture that is created when you bake the animations for this prototype. This field is reference only.
 +
 +
 +
'''Bake Animations:''' You can use this button to bake the animations for this prototype. When this button is used, GPUI will gather all the animation clips from the Animator component of the prefab and bone data from the Skinned Mesh Renderers found in this prefab and create the animation texture with respect to these.
 +
 +
<div style="clear: both"></div>
 +
'''Test Animations:''' You can use this button to test the animations that are baked for this prototype. When this button is used, GPUI will instantiate an instance of this prefab in the scene and add the '''The Crowd Prefab Debugger''' component on it. The instantiated prefab instance will have a test material on it which will allow you to test the animations that were found on the original prefab's Animator component. This test material mimics how GPUI will run the animations on runtime, so you can choose the animation that you want to test and use the '''Frame Index''' slider on this component to test the generated animation texture. Please note that this test material uses a generic test shader instead of the one that will be used for this prototype at runtime and some shader properties (e.g. specularity, metalic, etc.) may not be shown in this test.
 +
 +
<div style="clear: both"></div>
 
<br>
 
<br>
==== Render Settings ====
+
 
 +
=== Choosing the Animator Workflow ===
 +
----
 +
 
 +
 
 +
Once you add the prototype to the manager and bake its animation texture, you can choose which workflow you wish o use this prototype with from the '''Animator Settings''' section. The '''Mecanim Animator''' and '''Crowd Animator''' buttons in this section work as a toggle, allowing you to select the workflow for the selected individual prototype. These workflows are designed with ease of use in mind, and all you need to do is to select the your workflow and the options you need for its animator.
 +
 
 +
 
 +
[[File:CA-AnimatorSettings-Mechanim.png|450px|thumb|left|Animator Settings: Mechanim Animator]]
 +
==== The Mecanim Animator Workflow ====
 +
----
 +
 
 +
You can use the Unity Mecanim Animator to handle the state machine for animations as usual, and GPUI will read the animator states from the Mecanim Animator. This will let you use your existing Animators and scripts with Crowd Animations, and make it possible to use indirect GPU Instancing out of the box with all the GPUI features such as GPU frustum and occlusion culling. This workflow increases GPU performance while rendering skinned meshes, but it won't be an ideal solution for projects that are CPU bound since the Mecanim Animator will still create an overhang for each instance.
 +
 
 +
 
 +
In this workflow, you can also attach GameObjects on the bone transforms of your prefab instances.
 +
 
 +
 
 +
'''Apply Root Motion:''' When enabled, GPUI will apply root the motion of the animation clips to your transforms to the prefab instances.
 +
 
 +
'''Remove Bone GOs:''' This option will remove the bone GameObjects from the prefab instances at runtime, resulting in improved performance. It is recommended to enable this option if you will not use to the bone transforms in your prefab instances.
 +
 
 +
 
 +
'''Extra Bone GameObjects to Expose:''' Even when you remove the bone GameObjects for this prototype, you can choose to enable the GameObjects of some specific bones; for example to attach a weapon to your character's hand. When the bones in this list are selected, GPUI will keep their corresponding GameObjects in your prefab instances and apply the transforms of the bone hierarchy to them. This will be better in terms of performance as opposed to keeping all bone GameObjects.
 +
 
 +
 
 +
Please keep in mind, that although in this workflow GPUI uses your existing Mecanim Animators, there are some limitations: Animation Layers, masks, and IK are not supported. Also, the maximum number of animation blends are for four animations. If your animators have more blends than 4, the first four animation clips with highest blend weights at a given time will be used.
 +
 
 +
 
 +
<div style="clear: both"></div>
 +
[[File:CA-AnimatorSettings-Crowd.png|450px|thumb|left|Animator Settings: Crowd Animator]]
 +
 
 +
==== The Crowd Animator Workflow ====
 
----
 
----
  
 +
The Crowd Animator is designed to get the best performance out of GPUI when rendering animated characters. You can use the Crowd Animator to handle your animation clips in the GPU through the GPUInstancer API and decide which animation to play at a given time. This workflow will require you to write your own scripts (or use visual scripting tools) to handle animation states manually - but it will also let you get the most out of GPUI since there won't be any overhang created by the Mecanim Animator.
 +
 +
 +
'''Default Clip:''' This is the animation clip that will start playing for the instances of this prototype without any scripting. The list of animations displayed here are gathered from the Animator component of the original prefab.
  
Render Settings can be edited individualy for each prototype.
+
'''Apply Root Motion:''' When enabled, GPUI will apply root motion of the animation clips to transforms of the prefab instances.
  
 +
 +
In order to see how you can script your animation states and run blended animations (up to 4 animations) when using the Crowd Animator, you can take a look at the GPUI Crowd Animations API.
 +
 +
 +
<div style="clear: both"></div>
 
<br>
 
<br>
==== Detail Properties ====
+
 
 +
=== Using a Custom Shader on the Character Models ===
 
----
 
----
  
  
Detail Properties can be edited individualy for each prototype.
+
The Crowd Animations Extension works out of the box with materials using the Standard, Standard (Specular) and Autodesk Interactive shaders. However, if you wish to use a custom shader with CA, you need to manually setup the shader for work with it. Please note that this requires a working knowledge of shaders.  
  
 +
 +
Below, you can find the necessary information on how you can manually setup a shader to work with Crowd Animations:
 +
 +
 +
==== Includes and Pragmas ====
 +
 +
For all passes, you need to include the <CODE>UnityCG.cginc</CODE> and the <CODE>GPUICrowdInclude.cginc</CODE>. You also need the <CODE>multi_compile_instancing</CODE>, <CODE>multi_compile _ GPUI_CA_BINDPOSEOFFSET</CODE> and <CODE>instancing_options procedural:setupGPUI</CODE> pragma directives:
 +
 +
 +
...
 +
<span style="color: #008080;">Pass</span>
 +
{
 +
    ...
 +
    <span style="color: #008080;">CGPROGRAM</span>
 +
 +
    <span style="color: #0000FF;">#include</span> "UnityCG.cginc"
 +
    <span style="color: #0000FF;">#include</span> "GPUInstancer-CrowdAnimations/Shaders/Include/GPUICrowdInclude.cginc"
 +
 +
    <span style="color: #0000FF;">#pragma</span> multi_compile _ GPUI_CA_BINDPOSEOFFSET
 +
    <span style="color: #0000FF;">#pragma</span> multi_compile_instancing
 +
    <span style="color: #0000FF;">#pragma</span> instancing_options procedural:setupGPUI
 +
    ...
 +
    <span style="color: #008080;">ENDCG</span>
 +
}
 +
...
 +
 +
 +
Please note that these directives must be declared in this order and in the beginning of your shader pass (or SubShader, if you are using a surface shader).
 +
 +
==== Vertex Function Modifications ====
 +
 +
 +
The vertex function must first include the <CODE>UNITY_SETUP_INSTANCE_ID(v)</CODE> and the <CODE>GPUI_CROWD_VERTEX(v)</CODE> macros:
 +
 +
 +
v2f <span style="color: #0000FF;">vert</span>(appdata_full v)
 +
{
 +
    v2f o;
 +
    <span style="color: #0000FF;">UNITY_SETUP_INSTANCE_ID</span>(v);
 +
    <span style="color: #0000FF;">GPUI_CROWD_VERTEX</span>(v);
 +
    ...
 +
    return o;
 +
}
 +
 +
 +
 +
==== The Vertex Input Struct ====
 +
 +
 +
For Vertex/Fragment shaders, you can simply use <CODE>appdata_full</CODE>. Surface Shaders will also be using this input struct. In both these cases, you can skip this step.
 +
 +
 +
However, if you are using a custom input struct, the vertex function input struct must have <CODE>TEXCOORD2</CODE>, <CODE>TEXCOORD3</CODE>, <CODE>POSITION</CODE>, <CODE>TANGENT</CODE>, <CODE>NORMAL</CODE> defined. The following is an example with minimum members:
 +
 +
 +
<span style="color: #0000FF;">struct</span> appdata_custom
 +
{
 +
    <span style="color: #0000FF;">float4</span> vertex : POSITION;
 +
    <span style="color: #0000FF;">float4</span> tangent : TANGENT;
 +
    <span style="color: #0000FF;">float3</span> normal : NORMAL;
 +
    <span style="color: #0000FF;">float4</span> texcoord2 : TEXCOORD2;
 +
    <span style="color: #0000FF;">float4</span> texcoord3 : TEXCOORD3;
 +
    UNITY_VERTEX_INPUT_INSTANCE_ID
 +
};
 +
 +
 +
For custom vertex input structs, you also need to add defines in your shader that declare the names you use for your input struct members. Here is an example:
 +
 +
 +
<span style="color: #0000FF;">#define</span> GPUI_CUSTOM_INPUT 1 <span style="color: #008080; font-style: italic;">// needs to be declared so GPUI does not override your defines</span>
 +
<span style="color: #0000FF;">#define</span> GPUI_STRUCT_NAME appdata_custom <span style="color: #008080; font-style: italic;">// the name of your input struct</span>
 +
<span style="color: #0000FF;">#define</span> GPUI_BONE_INDEX texcoord2 <span style="color: #008080; font-style: italic;">// TEXCOORD2</span>
 +
<span style="color: #0000FF;">#define</span> GPUI_BONE_WEIGHT texcoord3 <span style="color: #008080; font-style: italic;">// TEXCOORD3</span>
 +
<span style="color: #0000FF;">#define</span> GPUI_VERTEX vertex <span style="color: #008080; font-style: italic;">// VERTEX</span>
 +
<span style="color: #0000FF;">#define</span> GPUI_NORMAL normal <span style="color: #008080; font-style: italic;">// NORMAL</span>
 +
<span style="color: #0000FF;">#define</span> GPUI_TANGENT tangent <span style="color: #008080; font-style: italic;">// TANGENT</span>
 +
 +
 +
==== UVs ====
 +
 +
The <CODE>uv2</CODE> and <CODE>uv3</CODE> channels on the mesh must not be used by the custom shader. Crowd Animations uses these channels to transmit bake data to the shader.
 +
 +
 +
<div style="clear: both"></div>
 
<br>
 
<br>
==== Cross Quads ====
+
 
 +
=== Crowd Animations Tools ===
 +
----
 +
 
 +
 
 +
==== Crowd Animator Randomizer ====
 
----
 
----
 +
<br>
  
 +
When using the Crowd Animator workflow, you can use this component to have the instances of your Crowd Prototypes run with randomized animations and animation frames without having to write any additional script.
  
Cross Quads can be edited individualy for each prototype.
 
  
 +
[[File:CA-CrowdAnimatorRandomizer.png|450px|thumb|left|The Crowd Animator Randomizer]]
 +
 +
 +
'''GPUI Manager:''' The Crowd Manager that this randomizer component will work on.
 +
 +
'''Randomize Clips:''' When selected, the instances of all the prototypes of the selected Crowd Manager will start with playing a random animation clip.
 +
 +
'''Randomize Frames:''' When selected, the instances of all the prototypes of the selected Crowd Manager will start from a different frame index of their default animation clips.
 +
 +
'''Reset Animations:''' This option is designed to be activated from script at runtime, and when activated, it will reset all the prototypes to their default animations.
 +
 +
 +
<div style="clear: both"></div>
 
<br>
 
<br>
==== Foliage Shader Properties ====
+
 
 +
== Integrations ==
 +
<br>
 +
 
 +
=== MapMagic World Generator  ===
 
----
 
----
 +
<br>
  
 +
<div style="clear: both"></div>
 +
[[File:GPUI-MapMagic integration.png|thumb|left|GPUI - MapMagic Integration]]
  
Foliage Shader Properties can be edited individualy for each prototype.
 
  
 +
GPU Instancer has a built-in integration with MapMagic World Generator. To use GPUI in your MapMagic Terrains, , you can use the following menu item:
 +
 +
 +
<code>Tools -> GPU Instancer -> Integration -> Add MapMagic Integration</code>
 +
 +
 +
Please note that GPUI checks the scripting define symbols in the player settings to determine whether you have MapMagic installed. If you don't have MapMagic, you will not see this menu item. If you have MapMagic, however, and if you don't see the integration menu item, the scripting define symbol might not be added to your player settings for some reason. In that case, you can manually add it by opening your Unity '''Player Settings''' (<code>Edit -> Project Settings -> Player</code>) and entering <code>;MAPMAGIC</code> at the end of your scripting define symbols line.
 +
 +
 +
When you add the integration from the menu, GPUI will add a GameObject to your scene with the options showing you what you want to import to GPUI from the MapMagic generation ruleset in the scene. You can then check the options you wish and click '''Import'''. This will turn the integration object into what looks like a combined version of all the GPUI Managers, and you can use the settings as you normally would in those managers.
 +
 +
 +
This is all you need to do to render your MapMagic terrains with GPUI. If at any time you change or edit the MapMagic ruleset, you can click '''Import''' again and the changes will reflect on the integration as well.
 +
 +
 +
<div style="clear: both"></div>
 +
 +
=== Gaia ===
 +
----
 
<br>
 
<br>
  
== The Tree Manager ==
+
<div style="clear: both"></div>
 +
[[File:GPUI-Gaia integration.png|thumb|left|GPUI - Gaia Integration]]
 +
 
 +
GPU Instancer has a built-in integration with Gaia. If you wish to use Gaia generated terrains with GPUI, you can use the '''GX''' tab under the '''Gaia Manager''' to add all desired GPUI managers to your scene.
 +
 
 +
 
 +
When you add the The Detail and the Tree Managers this way, it is exactly like adding them from the GPU Instancer Menu. They are there only for convenience.
  
  
=== Scene Settings ===
+
When you use Add the Prefab Manager from the GX menu, however, GPUI shows you a window that is similar to GPUI's Scene Prefab Importer tool. Using this window, however, instead of the prefab instances in your scene, you are presented with prefab instances that come from the Gaia ruleset that that is defined in the scene.
Scene Settings contains scene specific settings like camera selection.
 
  
=== Global Tree Values ===
 
Global Tree Values settings that are applied to all tree prototypes.
 
  
=== Prototypes ===
+
We recommended you to check the [[GPU Instancer:BestPractices|Best Practices Page]] before using Gaia with GPUI - especially [[GPU_Instancer:BestPractices#Using_GPUI_for_Unity_Terrain_Details|the section on Detail instancing]] - to get the most out of GPUI.
Prototypes show the list of objects that will be used in GPU Instancer. To modify a prototype, click on its image.
 
  
=== Render Settings ===
 
Render Settings can be edited individualy for each prototype.
 
  
=== Billboard Settings ===
+
<div style="clear: both"></div>
Billboard Settings can be edited individualy for each prototype.
 

Revision as of 10:01, 1 July 2019

About | Crowd Animations | Features | Getting Started | Terminology | Best Practices | API Documentation | F.A.Q.


GPU Instancer consists of three main Monobehavior classes. These 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.


HelpButton.png  All the GPU Instancer 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


Getting Started with GPUI is extremely easy:


1. Add the desired Managers to your scene

PrefabManager v1 11 high.png
  • Add Prefab Manager: Tools -> GPU Instancer -> Add Prefab Manager
  • Drag and drop the prefabs you want on the Add button.
DetailManager v111.png
  • Add Detail Managers to your scene: Tools -> GPU Instancer -> Add Detail Manager For Terrains
  • (Requires at least one Unity terrain in the scene)
TreeManager v111.png
  • Add Tree Managers to your scene Tools -> GPU Instancer -> Add Tree Manager For Terrains
  • (Requires at least one Unity terrain in the scene)


2. That's all. Your prefabs/details/trees will now be rendered with GPUI.

HelpButton.png
  • In the Inspector window, you can click the question mark icon at the top-right corner to get detailed information about the settings of the manager you just added.


Below you can find further information on the managers and their settings.


Common Manager Settings


The following setting sections exist in all managers with the same purposes. For the rare cases where there are manager specific options in them, the wiki sections on the specific managers below will explain those options.


Scene Settings



The Scene Settings section contains scene specific settings like camera selection and global culling settings that effect all the prototypes in a manager.


Manager Scene Settings

Paint on Terrain: This button is only visible in Detail and Tree Managers, and it can be used to navigate to the Unity terrain component that a manager is referencing. Details and Trees should be painted on the terrain using Unity's native tools as usual. Detail and Tree data on the terrain will be automatically detected by GPU Instancer. GPUI also adds a script on your terrain which will show you a button to go back to the manager that is responsible for that terrain. When you are done painting, you can use the Go to GPUI Detail/Tree Manager buttons to come back to the respective managers.


Unset Terrain: This button is only visible in Detail and Tree Managers, and it will severe the connection between the Unity terrain and this manager. You can use this to effectively disable GPUI's rendering of the terrain. It can later be enabled again by using the Set Terrain button.


Auto Select Camera: When this checkbox is active, GPU Instancer will use the first camera with the MainCamera tag at startup. If the checkbox is inactive, the desired camera can be set manually. GPU Instancer uses this camera for various calculations including culling operations.


Use Selected Camera Only: If enabled, instances will only be rendered with the selected camera. They will not be rendered in other active cameras (including the Scene View camera). This may improve performance if there are other cameras in the scene that are mainly used for camera effects, weather/water effects, reflections, etc. Using this option will make them ignore GPUI, increasing performance. Please note that the scene view during play mode will no longer show GPUI instances if this is selected.


Use Frustum Culling: Toggles frustum culling globally for all the prototypes in this manager. By turning frustum culling off, you can have view GPUI prototypes in all active cameras since they will not be culled. However, please note that turning frustum culling off may result in a lower FPS than having it on. If turned on, you can still turn frustum culling off for individual prototypes.


Use Occlusion Culling: Toggles occlusion culling globally for all the prototypes in this manager. By using occlusion culling, the prototypes that are not actually visible at runtime will not be rendered. This will increase rendering performance depending on the amount of occluded geometry. Please note that occlusion culling may lag if the FPS falls to extremely low levels. If this is a possibility, it could be better to turn it off. Please also check the Best Practices section on occlusion culling.


Min. Culling Distance: You can use this slider to define 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 never be culled.


Use Floating Origin: If enabled, positions of the instances will automatically change when the position of the assigned transform is modified. If this manager is a Detail or Tree Manager, the transform option will not show and GPUI will change the position of the instances based on the Unity terrain.


Prototypes



The Prototypes Section shows the list of objects that will be rendered by GPU Instancer. When you add a prefab to a Prefab Manager, it is added as a GPUI Prototype - and GPUI will track the instances of this prefab in the scene and render these instances with the settings you define for this prototype. For Detail and Tree Managers, the GPUI prototypes on these managers correspond to the detail or tree prototypes on the Unity terrain. For these managers you can click the Generate Prototypes button to (re)create the GPUI prototypes from the terrain. Also, for the Detail and Tree Managers, when you add a GPUI prototype to the manager, it will be added to the terrain as well.


Manager Prototypes

To modify the settings of a prototype, you can click on its image to select it. You can also use ctrl+click and shift+click to multi-select prototypes. GPUI will show you the available settings for the selected prototypes below the Prototypes section of the manager.


Text/Icon Mode: When you toggle this button, GPUI will show the prototypes as either a list of icons (default behavior) or a list of prefab names. If you have visually similar prototypes, seeing them by prefab names can help you identify them.


Generate Prototypes: This button is only available in the Detail and Tree Managers. It can be used to synchronize the detail prototypes on the Unity terrain with GPU Instancer. When used, it will reset the settings of each GPUI prototype on the manager with those from the Unity terrain, and use default values for properties that don't exist on the Unity terrain.


Regenerate Billboards: This button is only available in the Tree Manager, and regenerates the billboard atlases for all of the prototypes, also updating textures with the chosen settings in the Billboard Settings section.


Add: Click on this button to select a prefab from your project and add it as a prototype to the manager. You can also drag and drop a prefab, a prefab instance or a GPUI prototype scriptable object on this button; in all these cases the referenced prefab is added to the manager as a prototype. For the Detail Manager, you can also add textures as prototypes; these will be added to the terrain as texture type detail prototypes.


Note that GPUI accepts user made prefabs, and not imported model prefabs. If you wish to add a model prefab, you can first create a prefab out of it by dragging an instance of the model prefab from your scene and dropping it in your project window. Please also note that you can also use the Scene Prefab Importer tool to create a Prefab Manager with the selected prefab instances in your scene.


Multi. Add: You can use this button to add multiple prefabs to a manager. When clicked, the manager will be locked and GPUI will show you a drop area in the form of a separate window. You can simply drag and drop your prefabs (or prefab instances) to this area and they will each be added as a separate prototype to the manager.


Common Prototype Settings


The following settings are prototype specific, and they are mostly the same for the prototypes of all managers.


Prototype References

All prototypes show a reference to the prefab (or texture) that they reference, and a reference to their Scriptable Object (the data object that stores all the information related to the prototype). These reference fields are not editable; they are only there to easily access the reference objects.


Edit: This option is visible in the Detail and Tree Managers only, and you can click this button (or drop a prefab/texure on it) to replace the prototype's reference prefab (or texture). When you do this, the corresponding prefab/texture on the terrain will also change in the same index.


Shadows



Settings related to shadows can be accessed from this section. GPU Instancer allows you to use shadows selectively on your prototypes. Shadow casting requires extra shadow passes in shaders - resulting in additional rendering operations. GPUI uses various techniques that boost the performance of these operations, but turning shadow casting off completely will increase performance a lot more. If your prefab for the selected prototype is an LOD Group, you can also choose which LOD level to render the shadows from. Rendering shadows from LOD levels with lower triangle counts will help a lot with performance.


Prototype Based Shadow Settings

Is Shadow Casting: This option specifies whether the object will cast shadows or not. Turning shadows off hides the rest of the shadow options in the menu as well.


The options below are available only for the Prefab Manager:


Shadow with Original Shader: By default, GPUI uses a custom, lightweight "shadows only" shader to render the shadows of the prototypes that are defined on a Prefab Manager. Using this shader helps increase the shadow performance slightly more; especially if the original shader is using a shadow pass generated by a surface shader (using the addshadow directive). In most cases this shader is enough to render the prototype flawlessly; however, if the original shader uses vertex animation and/or alpha cutoff, then the shadows might not look right. Typical cases of this are when adding tree prefabs. In these cases you can enable this option to use the shadow pass of the original shaders of the prefab and the shadows should then look right.



Use Custom Shadow Distance: If this option is enabled, you can set a custom shadow distance for this prototype. This is particularly helpful since shadows can have the hugest impact on performance. If, for example, your scene fog is blurring objects further away from the camera, then using using a smaller shadow distance can increase the performance while not changing much of visual quality. If this option is not enabled, then GPUI will use the shadow distance defined in Unity's quality settings.


LOD N Shadow: These options appear if the registered prefab has an LOD Group on it. There will be as many options showing here as there are LOD levels on the LOD Group. Using the dropdowns, you can select which LOD level to render the shadows from for each LOD individual level; or choose "None" if you don't wish to render shadows for a specific LOD Group. Managing these options correctly can increase the scene performance greatly.


Use Culling for Shadows: By default GPUI does not use frustum and occlusion culling for prototype shadows that are in the shadow distance. This prevents issues with shadows (e.g. shadow popping) especially if the camera is dynamic and scene lighting changes a lot. If this option is selected, culling results will also be applied to the prototype shadows. This will result in more performance but might also lead to less consistency in shadows.


Culling



These are the culling settings you can define on a prototype basis. Changing settings here will override the general settings in the manager for the selected prototype. You can check the Terminology Page for more information on culling.


Prototype Based Culling Settings

Max Distance: Defines the maximum distance from the selected camera within which this prototype will be rendered.


Is Frustum Culling: Specifies whether the objects that are not in the selected camera's view frustum will be rendered or not. If enabled, GPU Instancer will not render the objects that are outside the selected camera's view frustum. This will increase performance. It is recommended to turn frustum culling on unless there are multiple cameras rendering the scene at the same time.


Frustum Offset: Defines the size of the area around the camera frustum planes within which objects will be rendered while frustum culling is enabled. GPU Instancer does frustum culling on the GPU which provides a performance boost. However, if there is a performance hit (usually while rendering an extreme amount of objects in the frustum; or because of some game script), and if the camera is moving very fast at the same time, rendering can lag behind the camera movement. This could result in some objects not being rendered around the frustum edges. This offset expands the calculated frustum area so that the renderer can keep up with the camera movement in those cases.


Is Occlusion Culling: Toggles occlusion culling for this prototype. By using occlusion culling, the prototype instances that are not actually visible at runtime will not be rendered. This will increase rendering performance depending on the amount of occluded geometry, and since terrain details are usually quite high in instance counts it is usually very good to have it on for detail instances. Please note that occlusion culling may lag if the FPS falls to extremely low levels. If this is a possibility, it could be better to turn it off. Please also check the Best Practices section on occlusion culling.


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.


LOD



Using LODs (Level of Detail) are a great way to improve performance. GPUI supports LOD groups on your prefabs and automatically renders them with indirect instancing while managing the necessary GPU buffer automatically. The LOD settings of the prototype will only be visible if there is an LOD Group on the prefab.


Prototype Based LOD Settings

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.


Animate Cross-Fading: If this option is selected, GPUI animates cross-fading instead of it being distance based. The animation starts with the first occurrence of the changed LOD. During the animation, both LOD levels will be rendered.


LOD Fade Transition Width: You can use this value to define the cross-fading zone between LOD Levels. This zone is the distance in which the prototype LODs are cross-faded. Higher numbers result in wider transition zones. In the transition zone, both LOD levels will be rendered. This option only becomes visible if cross-fade animation is disabled.


LOD Bias Adjustment: This 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. You can use this to manipulate the instance LOD distances without changing LOD Group on the original prefab.


Billboard Settings



GPU Instancer comes with a billboard generator system. A billboard is a simple quad that shows snapshots of the object from different angles depending on the camera viewing angle. GPUI's billboard generator is mainly designed for use with trees so it generates snapshots of view angles around the world y axis. This means that the billboards do not have view perspectives from up or down. For detailed information on GPUI's billboard generator, you can take a look at its section in the Features Page. Bilboards are a great way to increase performance while having vast viewing distances. GPUI adds the generated billboard automatically as the final LOD level (even if the prefab does not have an LOD Group on it). You can also use a custom mesh and material for the billboard if you do not wish to use the billboard that GPUI generates. All the billboard settings here can be edited for each individual prototype.


Prototype Based Billboard Settings

Generate Billboard: If enabled, GPU Instancer will automatically generate a camera facing billboard of this prototype to use as its final LOD level. This billboard is made of a single quad mesh, and as such it can increase the performance for distant instances greatly. The remaining billboard options will not be visible if this option is disabled.


Use Custom Billboard: You can use a custom mesh and material with GPUIs billboard system instead of the generated billboard. When you enable this option, you will see two fields where you can assign your mesh and material. Billboard generation settings will disappear since GPUI will not be generating the billboard anymore.


Billboard Quality: 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 "2048" option results in a 2048x256 texture resolution.


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


Billboard Brightness: You can use this slider to adjust the brightness of the generated billboard textures. A zero value is fully black whereas one is fully white.



Override Original Cutoff: You can use this 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.


Override Cutoff Amount: Becomes visible when you choose to override the original cutoff value. You can use the slider to adjust the cutoff amount.


Replace LOD Culled With Billboard: If this option is enabled, GPU Instancer will use the generated billboard instead of the "Culled" distance defined in this prototype's LOD Group. Deselect this option if you want to use a custom billboard distance.


Billboard Distance: Defines the distance to the camera in which the prototype will render as the billboard. Increase this if you want the prototypes to switch to billboards further away from the camera.


Billboard Albedo Texture: This is the texture atlas that is generated for use with this billboard. You cannot change the texture here, but you can click on it to highlight it in the project window; so that you can view it.


Billboard Normal Texture: This is the normal texture atlas that is generated for use with this billboard. You cannot change the normal texture here, but you can click on it to highlight it in the project window; so that you can view it.


Generate Billboard: If you see this option then the billboard has not been generated yet. This button generates the billboard atlases for this prototype and creates the current textures with the current billboard settings.


Regenerate Billboard: This button regenerates the billboard atlases for this prototype and updates the current textures with the changed settings.


Show Billboard: This button instantiates a quad mesh at (0,0,0) position and shows the generated billboard on it. You can use this to inspect how the billboards will look like at runtime. You can also safely delete the generated game object from your scene once you are done inspecting.


The Prefab Manager


GPUI-PrefabInstancing002.png


By adding your prefabs to the GPU Instancer 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, changing material properties per instance, choosing an LOD level to render the shadows from, and much more. 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.

Adding a Prefab Manager

You can add a Prefab Manager from:

Tools -> GPU Instancer -> Add Prefab Manager

HelpButton.png   You can click the question mark icon at the top-right corner of the Prefab Manager at any time to get detailed information about these settings.


Below are the settings that are specific to the Prefab Manager.


Registered Prefabs



The Registered Prefabs section shows the list of registered prefab instances that are currently in the scene. These instances will be rendered with GPU Instancer.


Prefab Manager Registered Prototypes

The first time you add a prefab, the manager automatically registers the instances in your scene and shows the registered instance counts. However, when you add or remove instances while designing your scene, it is required to register the instances in the scene again. In this section, GPUI also shows which prototypes are currently selected. You can also shift+click or ctrl+click on the list items to select multiple prototypes.


Please note that the Prefab Manager will show you a warning in this section if the instance counts for some prototypes are too low, and it will also highlight the problem prototypes. The reason for this is that GPU instancing is useful only in cases where there are lots of instances with the same mesh/material combination. For more in formation on this, you can check the Best Practices wiki article on instance counts. You can disable this warning form the GPU Instancer Pereferences. If the instance counts for a prototype are zero, GPUI simply ignores the prototype as if it didn't exist.


Register Instances in Scene: This button can be used to register the prefab instances that are currently in the scene and update the instance counts; so that they can be used by GPU Instancer. When you add new instances to the scene using the Unity editor, you need to register them to GPUI again using this button to update the current instance counts. Please note that this button does not create new prototypes from prefab instances from your scene - for that you need to drag and drop prefabs or prefab instances on the Add button. For information on adding new instances at runtime, you can check the API Documentation.


Runtime Settings



The runtime settings that you can find per Prefab Manager prototype can be used to change the runtime behavior of the prototype instances. If you enable runtime modifications, the instances can be added, removed and/or updated during runtime. These modifications can either be done through the GPU Instancer API, or automatically from the manager.


Prefab Manager Prototype Runtime Settings

Enable Runtime Modifications: If this option is enabled, transform data (position, rotation, scale) for the prefab instances can be modified at runtime. This can be done either automatically (see below) or through scripting with API calls. The options below become visible only when this option is enabled.


Start With RigidBody: When using this option, the prefab instances that have a RigidBody component on them will start with an active RigidBody.


Add/Remove Instances At Runtime: Enabling this option allows you to add new prefab instances or remove existing ones at runtime. This can be done either automatically (see below) or through scripting with API calls.


Extra Buffer Size: This option specifies the amount of prefab instances that can be added without re-initializing compute buffers at runtime. This is relevant when scripting the add/remove operations and not while GPUI is automatically managing the buffers (see below).


Auto. Add/Remove Instances: If this option is enabled, new prefab instances will be added or existing ones will be removed automatically at runtime without using any API calls. This is the easiest way to use this feature; however, if you have an extreme number of objects (e.g. tens or hundreds of thousands) it is recommended to use the API and manage these operations through code. The reason for this is, each time an instance is added/removed, GPU buffers will be re-initialized. Even though these operations are optimized for efficiency and are quite fast, in extreme numbers there will be a slight difference in performance.


Auto. Update Transform Data: If this option is enabled, transform updates (position, rotation and scale changes) on prefab instances will be reflected automatically on the prototype instances at runtime without the need for API calls. GPUI will track transform changes and physics movements through rigidbodies and apply them to its rendered instances automatically. Please have in mind, however, that even though GPUI efficiently keeps track of the transform changes (i.e. transform data is cached as opposed to being queried each frame), this still adds a further operation to each update. The impact of this on performance should usually not be noticeable, but if you know that your instances transforms will not be updated (that they won't move, rotate or resize) then you should not enable this option.


Actions



Delete: You can use this button if you wish to remove the selected prototype from the Prefab Manager. GPUI will ask you whether you want to delete the prototype reference object as well. You can keep the reference object if you are using this prototype in another Prefab Manager; or simply to keep its settings in order to add the same prototype later.


Advanced Actions



Prefab Manager Advanced Actions

The options you can see here are the advanced features that are available to access from the Prefab Manager GUI. Using these usually require a thorough understanding of how GPUI and GPU Instancing in general works. If you are not experienced with the concepts at work here, it is recommended not to use the options in this menu. By default, you will find this menu collapsed; you can click on the arrow icon to the left in order to see its contents.


Disable Mesh Renderers: By default, during initialization, GPU Instancer loops through all the GameObjects that are instances of a prototype and disables their Mesh Renderers and LOD Groups before starting its own rendering system. This is a costly operation and the impact could be seen more with increasing numbers of prototype instances in the scene. GPUI offers a workaround to this problem by disabling the Mesh Renderers on the original prefab using this button. When clicked, GPUI marks that it has disabled the Mesh Renderers (and LOD Groups) as such on the selected prototype and does not search the scene for its instances when entering play mode - increasing initialization performance. Please note that when using this option, since the Mesh Renderers are disabled on the original prefab, the scene instances will not be visible in the editor before entering the play mode. Therefore, it is recommended to use this option after you design your scenes and before building your game. Please also note that this button turns into Enable Mesh Renderers when clicked, and you can use it again to enable the Mesh Renderers back on.


Serialize Registered Instances: This action will remove the registered prefab instances from the scene and save their transform data into a TextAsset. This is helpfull to save memory and speed up initialization by getting rid of unnecessary GameObjects. However, these objects will be visible only during play mode or editor simulation and while the Prefab Manager is active and running. You will be able to use this button again to recreate the GameObjects with the same transform data, but it is recommended to do this after you finished your scene design.


Simulate at Scene Camera [Experimental]: This button will render the prefab instances that are disabled or serialized by these advanced actions in the scene view using GPUI. Please note that this feature is experimental; changing prototype settings and/or editing the scene may break the simulation.


The Detail Manager


GPUI-DetailInstancing002.png

The main purpose of the Detail Manager is increasing visual quality over that of the default Unity terrain details while backing this up with the indirect instancing core of GPUI for performance. You also don't have to do any extra work for this visual upgrade - GPUI simply takes your Unity terrain and makes it better looking just by adding the Detail Manager. The default settings on the manager introduce shadows for your details and turn the texture prototypes into cross-quads. The foliage shader also introduces further quality upgrades by adding ambient occlusion, color gradienting, wind wave tints, and much more to the detail instances. The Detail Manager also allows you to use custom shaders for your Unity terrain details while still using cross quads for texture details, shadows, etc.


GPUI uses instancing techniques for backing this up performance-wise, and the result is always a stable FPS with no spikes. The occlusion and frustum culling solutions apply to the detail prototypes as well; further increasing performance. However, please note that in some cases, the FPS would result in a number that is lower than the default Unity terrain especially if you are using features that don't exist in the Unity terrain details. The expected result when increasing visual quality in the Detail Manager, therefore, is not that it would always be faster than the Unity terrain, but that it is fast while still using these features. For more information and best practices on using the Detail Manager, you can check the relevant section of the Best Practices Page.


When you add a Detail Manager for your terrain, the manager automatically creates GPUI prototypes from the detail prototypes that are defined in your terrain. The settings that match the Unity terrain are also transferred to the Manager (e.g. max detail distance, density, colors, etc.)


The prototype types on the terrain result in different kinds of GPUI prototypes depending on whether they are detail textures or detail meshes. Detail textures will be handled by the manager with the GPUI foliage shader, while the prefab references of the detail meshes will be directly referenced as prefab instances. What this latter point means is that even though the Unity terrain applies its own shader and does not always correctly handle prefabs for detail prototypes, you can add them to the terrain anyway and GPUI will render them with their own materials and shaders. Furthermore, you can also add prefabs with LOD Groups on them if you add the prototypes form the Detail Manager. GPUI will add the first LOD to the terrain so that it is visible in the editor; but will use the prefab with all its LOD levels when rendering. We recommend to use LODed prefabs on your terrains as details for performance.


Please also note that you can use the GPUI foliage shader on your prefab materials and make use of this shaders features when using prefab prototypes. You can check the DetailInstancingDemo scene to investigate how we used the detail manager settings and LODs on the detail prefabs (that also use the foliage shader).


Adding Detail Managers

You can add a Detail Manager from:

Tools -> GPU Instancer -> Add Detail Manager For Terrains

HelpButton.png   You can click the question mark icon at the top-right corner of the Detail Manager at any time to get detailed information about these settings.


When you click this menu item, GPU Instancer will create a Detail Manager for each Unity terrain that you have in the scene. Please note that this menu option becomes available only if you have at least one terrain in the scene.


Please note that after you add the Detail Manager, it is recommended to add/remove/update detail prototypes on the terrain from the manager rather than directly on the terrain object. From the Scene Settings section for the Detail Manager, you can easily switch to the Unity terrain that this manager is responsible to paint details on the terrain. You can also set and unset the terrain connection with this manager from there.


Below are the sections that are specific to the Detail Manager:


Debug



The debug section is intended to show edit-time specific features. It is mainly used to simulate GPUI's rendering of terrain details without entering play mode. Since GPUI uses the data from the instances on the Unity terrain, it does not take over scene rendering and you can enable and disable GPUI in your project without loosing the terrain detail data.


Simulate at Scene Camera: This button can be used to render the terrain details on the scene camera using the current GPU Instancer setup. This simulation is designed to provide a fast sneak peak of the GPU Instanced terrain details without having to enter play mode.


Global Detail Values



These settings are applied to all the detail prototypes defined in a Detail Manager. The Terrain Settings SO is a reference to the data object that contains these values and also serves as a container for the individual detail prototype data objects. This reference is not editable.


Detail Manager Global Detail Values

Max Detail Distance: Defines the maximum distance from the camera within which the terrain details will be rendered. Details that are farther than the specified distance will be culled. This setting also provides the upper limit for the maximum view distance of each detail prototype.


Detail Density: This slider goes from 0.0 to 1.0, with 1.0 being the original density on the terrain, and lower numbers resulting in less detail objects being rendered. Thus lowering density will increase performance.


Detail Texture 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.


Wind Vector: Specifies the [X, Z] vector (world axis) of the wind for all the prototypes (in this terrain) that use the GPUI foliage shader (which is also the default shader for the texture type grass details). This vector supplies both direction and magnitude information for wind as far as detail prototypes are concerned.


Healthy / Dry Noise Texture: This can be used to specify the Healthy Color / Dry Color variation for all the prototypes that use the GPUI foliage shader in the terrain. Texture type detail prototypes are also scaled by this noise. This image must be a greyscale noise texture.


Wind Wave Normal Texture: This can be used to specify the vectors of all wind animations and coloring for all the prototypes that use the GPUI foliage shader in the terrain. This image must be a normal map noise texture.

Auto SP Cell Size: Detail Manager uses spatial partitioning for loading and unloading detail instances from GPU memory according to the camera position. Detail instances are grouped in cells with a calculated size. By selecting "Auto SP Cell Size", you can let the manager decide which cell size to use. If you deselect "Auto SP Cell Size", you can determine a Preferred SP Cell Size.


Initialize in Threads: If this option is enabled, the Detail Manager makes the initialization calculations for spatial partitioning in Threads. This significantly reduces FPS drops caused by initialization, however it might take longer for the initialization to finish.


Detail Properties



Prototype based Detail Properties can be edited individually in this section for each prototype. The settings here will override their global counterparts.


Prototype Based Detail Properties

Detail Density: This value goes from 0.0 to 1.0, with 1.0 being the original density on the terrain, and lower numbers resulting in less detail instances being rendered. Rendering a lesser amount of detail instances can increase the performance.


Detail Scale: These values can be used to set a range for the instance sizes of the detail prototypes. For the texture type detail prototypes, this range applies to the "Healthy / Dry Noise Texture" above. The values here correspond to the width and height values for the detail prototypes in the Unity terrain. X: Minimum Width - Y: Maximum Width - Z: - Minimum Height - W: Maximum Height


Noise Spread: This property specifies the size of the "Healthy" and "Dry" patches for the Detail Prototype instances that use the foliage shader. This corresponds to the "Noise Spread" property of the detail prototypes in the Unity terrain. A higher number results in smaller patches. The Healthy / Dry noise texture can be changed globally for all detail prototypes that use the foliage shader from the "Healthy/Dry Noise Texture" property above; or individually by using a custom noise texture (see below).


Custom Noise Texture: This option can be used to specify that a custom Healthy/Dry Noise Texture for this prototype. The foliage shader uses this for healthy/dry color variation and the manager will scale the prototypes based on this texture as well.


Use Custom Material: If you wish to use a custom material (with a custom shader) for the texture type detail prototypes instead of the foliage shader, you can specify it by enabling this option. Note that cross-quading and shadows are available for custom materials as well, the ability of cross-quads to billboard at a distance will not be available since GPU Instancer handles their billboarding in the foliage shader.


Custom Material: This field becomes visible if you choose to use a custom material for a texture type detail prototype. It can be used to specify the material that will be used instead of GPUI's foliage shader. The shader that this material uses will be automatically set up for use with GPU Instancer. This process creates a copy of the original shader (in the same folder) that has the necessary lines of code. Note that this process will NOT modify the material and is completely non-invasive.


Cross Quads



GPUI optionally renders the instances of texture type detail prototypes by generating cross-quads instead of the single quads used by the Unity terrain. This option can make grass and foliage on the terrain look lusher and denser; but comes at the cost of increased scene geometry. However, GPUI further optimizes this solution by billboarding the instances that are farther away for increased performance. In any case, using this option will result in less performance and better visuals in contrast to not using it. Cross-quadding can be enabled individually for each prototype, and they become visible only when the prototype is a texture type detail prototype.


Detail Prototype Cross Quads


Cross Quads: If enabled, a mesh with multiple quads will be generated for this detail texture (instead of a single quad or billboard). The generated quads will be equiangular to each other. Cross quadding means more polygons for a given prototype, so turning this off will increase performance if there will be a huge number of instances of this detail prototype.


Quad Count: Defines the number of generated quads for this detail texture. Using more quads will usually improve visual quality whereas using less quads will increase performance (especially where there will be a huge number of instances of this prototype). The options are 2, 3 or 4 quads.

The following Options are available only for the prototypes that use the default GPUI Foliage Shader (not a custom material):


CQ Billboard Distance: When cross-quadding is enabled, this option specifies the distance from the selected camera where the instances will be drawn as single quad billboards instead of cross-quads. Since instances that far away will look almost the same whether they are billboards or cross-quads, you can use this option to increase performance further without compromising too much of the visual quality. The value used here is similar to the screenRelativeTransitionHeight property of Unity LOD Groups.


CQ Distance Debug: When cross-quadding is enabled, you can enable this option to visually test the cross-quad billboarding distance. The billboards will be rendered with a specified color for this purpose. Please note that you have to either simulate at scene camera or enter the play mode to see this effect.


Debug Color: Visible when CQ Distance Debug is enabled, you can choose the color of the instances that will be billboarded at the specified distance.


CQ Billboard Face Cam. Pos.: If enabled, the billboard LODs of this cross quad will ignore the camera view matrix rotations and will always face the camera position. This is ideal for VR platforms."


Foliage 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 GPUInstancer/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 they can be used to change prototype settings individually.


Detail Prototype Foliage Shader Properties

Billboard: If enabled, the generated mesh for this prototype will be billboarded to always face the camera. Note that billboarding will turn off automatically if cross quads are enabled.


Billboard Face Cam. Pos.: If enabled, the billboards for this prototype will ignore the camera view matrix rotations and will always face the camera position. This is ideal for VR platforms.


Detail Healthy Color: The Healthy color of the the Healthy / Dry noise variation for the prototypes that use the foliage shader. This corresponds to the Healhy Color property of the detail prototypes in the Unity terrain. The Healthy / Dry noise texture can be changed globally (terrain specific) for all detail prototypes that use the foliage shader from the "Healthy/Dry Noise Texture" globally or on a per-prototype basis (see above).


Detail Dry Color: The Dry color of the the Healthy / Dry noise variation for the prototypes that use the foliage shader. This corresponds to the Dry Color property of the detail prototypes in the Unity terrain. The Healthy / Dry noise texture can be changed globally (terrain specific) for all detail prototypes that use the foliage shader from the "Healthy/Dry Noise Texture" globally or on a per-prototype basis (see above).


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: 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 globally (terrain specific) for all detail prototypes that use the foliage shader from the Wind Wave Normal Texture global property.


Wind Wave Tint Color: This is a shader property that acts similar to the Grass Tint property of the Unity terrain, except GPUI applies this on a per-prototype basis. This color applies to the Wind Wave Tint properties of all the instances of this prototype (see below).


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.


Actions



Apply Changes To Terrain: This button can be used to modify the Unity terrain with the changes that are made in Detail Manager.

Delete: You can use this button if you wish to remove the selected prototype from both the manager and the Unity terrain.


The Tree Manager


GPUI-TreeInstancing001.png


You can use the Tree Manager to instance Unity terrain trees. If you want to use trees without registering them to the Unity terrain, you can use the Prefab Manager instead. Adding a Tree Manager to your scene will let GPUI take the tree data from the Unity Terrain and generate the required GPUI prototypes. The tree manager also enables billboarding for the tree prototypes automatically, and generates the billboards.


The Tree Manager supports SpeedTree, TreeCreator and most of the custom tree shaders. For SpeedTrees, GPUI will use the generated billboard instead of the SpeedTree Billboard LOD - for all other trees, the generated billboard is used as a final LOD level.


Adding Tree Managers

You can add a Tree Manager from:

Tools -> GPU Instancer -> Add Tree Manager For Terrains

HelpButton.png   You can click the question mark icon at the top-right corner of the Tree Manager at any time to get detailed information about these settings.


When you click this menu item, GPU Instancer will create a Tree Manager for each Unity terrain that you have in the scene. Please note that this menu option becomes available only if you have at least one terrain in the scene. Below are the sections you will find in the Tree Manager.


Please note that after you add the Tree Manager, it is recommended to add/remove/update tree prototypes on the terrain from the manager rather than directly on the terrain object. From the Scene Settings section for the Tree Manager, you can easily switch to the Unity terrain that this manager is responsible to paint details on the terrain. You can also set and unset the terrain connection with this manager from there.


Below are the sections that are specific to the Tree Manager:


Global Tree Values



These settings are applied to all the tree prototypes defined in a Tree Manager. The Terrain Settings SO is a reference to the data object that contains these values and also serves as a container for the individual detail prototype data objects. This reference is not editable.


Tree Manager Global Tree Values


Max Tree Distance: Defines the maximum distance from the camera within which the terrain trees will be rendered. Trees that are farther than the specified distance will not be visible. This setting also provides the upper limit for the maximum view distance of each tree prototype.


Initialize With Coroutine: if enabled, makes the initialization calculations for tree instances in a Coroutine. This significantly reduces FPS drops caused by initialization, however it might take longer for the initialization to finish.

Actions



Delete: You can use this button if you wish to remove the selected prototype from both the manager and the Unity terrain.


GPU Instancer Preferences


GPU Instancer Preferences


GPU Instancer includes a Preferences Window where you can change setting that effect all the GPUI managers and prototypes. This window also can be used to execute various version update specific jobs and extract desired extra packages.


You can access the GPU Instancer Preferences Window from:

Edit -> Preferences -> GPU Instancer


HelpButton.png   You can hover your mouse over the labels for each setting to get detailed information about them. 



The following are the options that you can access from this window:


Constants



Max Detail Distance: Defines the maximum distance from the camera within which the terrain details will be rendered. Details that are farther than the specified distance will not be visible. This setting also provides the upper limit for the maximum view distance of each detail prototype.


Max Tree Distance: Defines the maximum distance from the camera within which the terrain trees will be rendered. Trees that are farther than the specified distance will not be visible. This setting also provides the upper limit for the maximum view distance of each tree prototype.


Max Prefab Distance: Defines the maximum distance from the camera within which Prefab Manager prototypes will be rendered.


Max Prefab Extra Buffer Size: Specifies the maximum amount of prefab instances that can be added without re-initializing compute buffers at runtime. Instances can be added at runtime with API calls or by enabling Automatically Add/Remove Instances option from the Prefab Manager.


Instancing Bounds Size: Defines the bounds parameter's size for the instanced rendering draw call.


Behavior



Auto Generate Billboards: If enabled, billboard textures will be automatically generated for known tree types when they are added to the GPUI Managers.


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.


Disable Instance Count Warnings: If enabled, Prefab Manager will not show warnings for prototypes with low instance counts.


VR



VR Rendering Mode: You can set which VR rendering mode you are using in your project here. Setting this will allow GPUI to use the correct rendering mode for VR operations such as occlusion culling. Please note that in Unity versions 2018.3 and above, this is automatically detected by GPUI and this option will not be visible.


Test Both Eyes for VR Occ. Culling: If disabled, GPUI will run occlusion test calculations for the left VR eye only. When enabled, both eyes will be tested. Testing both eyes can put more load on the GPU in some cases, but culling results will always be more accurate.


Theme



Custom Preview BG Color: If enabled, a custom background color can be used for preview icons of the prototypes.


Preview BG Color: The custom background color to be used for preview icons of the prototypes.


Update Jobs



If any actions are required after updating GPUI to a new version, you will be able to execute these actions from this section.


Package Definitions



You can see which optional GPUI packages are loaded for this section. You can also remove individual packages or reload them.

Tools

Scene Prefab Importer

GPUI-v097-ScenePrefabImporter.jpg

GPUI comes with a Scene Prefab Importer tool that can help you to easily create a Prefab Manager in your scene with the prefab instances in your scene as prototypes. This can reduce the amount of work greatly if you have a lot of prefabs in your scene, since you will be able to setup your Prefab Manager in only a few clicks. The Scene Prefab Importer also helps you to see the amounts prefab of instances that you have in the scene, and allows you to easily add prototypes that are above a certain instance count.


Instance counts are among the most important things to consider when adding a prefab to GPUI as a prototype to render with it. You can check the section on the Best Practices Page about this for more information.


Using the Scene Prefab Importer Tool is very easy. You can access it from:

Tools --> GPU Instancer --> Show Scene Prefab Importer

HelpButton.png   You can click the question mark icon at the top-right corner of the Scene Prefab Importer at any time to get detailed information about these settings.


The Scene Prefab Importer tool will show you all the GameObjects in the open scene that are instances of a Prefab - and their instance counts in the scene. You can use the Select Min. Instance Count slider and button to select prefabs with a given minimum amount. You can then Import Selected Prefabs and GPUI will create a Prefab Manager in your scene with selected prefabs as prototypes.

The Prefab Replacer

The Prefab Replacer Tool

GPUI comes with a Prefab Replacer tool that can help you to easily replace GameObjects in your scene hierarchy with prefab instances in a few clicks. This is very helpful especially if you did not follow a prefab workflow when creating your scene. You can also use this to easily replace instances of one or multiple prefabs with another while still keeping the transform data (positions, rotations and scales).


Using the Scene Prefab Importer Tool is very easy. You can access it from:

Tools --> GPU Instancer --> Show Prefab Replacer

HelpButton.png   You can click the question mark icon at the top-right corner of the Prefab Replacer at any time to get detailed information about these settings.


To use this tool, you can select multiple GameObjects by either shift clicking or ctrl/cmd clicking on them. The Prefab Replacer will show you the selected GameObjects' names. You can then assign a prefab in the tool; the selected GameObjects will be replaced with instances of this selected prefab. You can also choose to replace the names as well, which will properly name the new GameObjects with respect to the selected prefab. Clicking Replace Selection with Prefab button will execute the operation.


Don't forget to save your scene, and if the selected Prefab is already registered as prototype on a Prefab Manager, do not forget to Register Instances in Scene to update the instance counts.

Clear Shader Bindings

GPU Instancer automatically generates new versions of the shaders that are on the materials of your prototypes. The generated shaders are exactly the same with the original shader; the only difference being they are setup to work with GPUI. These shaders always in the same directory where the original shader is, and their filenames end with a [_GPUI] suffix. Also, these shaders always show as starting with [GPUInstancer/] followed by the original shader name.


GPUI internally keeps track of these shaders and re-generates them if the original shader is modified. Shader Bindings is an internal object that keeps track of these shaders. If for any reason you wish to clear this object, you can use the Clear Shader Bindings menu item for this. You can access it from:


Tools --> GPU Instancer --> Clear Shader Bindings


You can also use this tool to delete the shaders that GPUI generated. The tool will first ask you whether you really want to clear the shader bindings object, the ask also if it should delete the generated shaders. Please note that both operations are completely safe and this tool will never touch your original shaders. Also, the managers will instantly generate the necessary shaders again, so you don't have to worry about breaking GPUI while using this.


Components


GPUI Modification Collider



GPUI Modification Collider

GPU Instancer comes with a component that you can use to disable instancing inside a zone. This is called the GPU Instancer Modification Collider, and it can help you manage physics with GPUI in a more efficient way and with better performance.


The Modication Collider component can be used in various scenarios; for example in the PrefabInstancingDemo it is used to activate Rigidbodies on the asteroids that are close to the Spaceship. The Rigidbodies in this example move the asteroids around upon collision with the spaceship. When they stop moving (i.e enter Sleep state), The Modification Collider turns back instancing on them and deactivates their Rigidbodies again if they are outside the de-instancing zone.


The zone in which the Modification Collider works is determined by a trigger type Collider that must also exist on the same GameObject that the Modification Collider component exists - hence the name of the component.


Notice that you have to Enable Runtime Modifications for the prefabs that you wish to effect this way in the Prefab Manager; however you do not need to enable any other options in the Runtime Settings section. This is because transform/physics updates are not applied automatically for the instances that reside outside the Modification Collider at runtime, and this will result in better performance. You can see in the downloadable demos that GPUI can render 200k asteroids with physics in around 150-200 FPS by using this technique. The asteroid counts could even go much higher, but you need to follow a no-game object workflow for that since Unity restricts Collider usage to around 260k.


GPUI Modification Collider (Inspector)


Using the Modification Collider is very simple:


1) Add the included GPUInstancerModificationCollider.cs script to any GameObject with a Collider (must be trigger). This GameObject's collider will be used for the de-instancing zone. You can use the Add Component button in the inspector window to add the script as a component to this GameObject.


2) Enable the option Enable Runtime Modifications in the Prefab Manager for the prefabs you want to be effected by the de-instancing zone.


3) Optional: Assign the desired Prefab Manager to the Modification Collider's respective field. If you don't assign any, the first found Prefab Manager in the scene will be used to determine the prototypes.

That's all. The GameObject you added this can move at the runtime which will also move the de-instancing zone, and if your prototype prefabs have Rigidbody components on them, these components will be activated in the zone and deactivated when they're out and still.


Please note that the Modification Collider will use only the first Collider if your GameObject has multiple.


GPUI Instance Remover



GPUI Instance Remover


GPU Instancer comes with a component that you can use to easily remove instances from your scenes at runtime without any code. This component becomes particularly useful if you're using the Detail Manager; you can use it, for example, to remove the grass under a placed building at runtime. However, it can also be used for all the instances that are rendered by GPUI (including the Tree Manager and the Prefab Manager). This component is the GPU Instancer Instance Remover.


The Instance Remover will use either the bounds of the GameObject that it is on, or its Colliders to remove the instances that fall inside these zones. The removal of the instances is extremely fast (as you can see in the DetailInstancingDemo scene's grass mower) so you can even use it to remove instances in every Update loop.


Please note that the instances will be removed from GPUI's runtime session, and not the terrain itself. When you instantiate GameObjects with an Instance Remover component on them (or enter the playmode with them), the instances that fall inside the Bounds/Colliders of these GameObjects will instantly be removed. Notice that you can have as many of these as you like.


GPUI Instance Remover (Inspector)

Using the Instance Remover is very simple:


1) Add the included GPUInstancerInstanceRemover.cs script to any GameObject with a Collider. This GameObject's Collider or Collider Bounds (faster) will be used for instantly removing GPUI instances at runtime. You can use the Add Component button in the inspector window to add the script as a component to this GameObject.


2) That's actually all, you don't need to do anything else. The Instance Remover is an imposing GPUI component, so you don't need to have any additional settings on the managers or prototypes to use it; it will also target all active GPUI managers so you don't have to specify a manager.


There are a few options on the Instance Remover:


Use Bounds: If this is selected, GPUI will use object Bounds instead of the Colliders for removing instances.


Sellected Colliders:' You can see a list of Volliders that the Instance Remover will be using in this list. This list is automatically constructed upon Component Reset. The list contains all the components also in the child GameObjects of this GameObject. All of these Colliders are encapsulated to calculate the removal zone. If you're adding the Instance Remover component from script, you can modify this list after adding the script to define the Colliders that you wish to use with it.


Remove from Detail Manager: If this is enabled, the Instance Remover will remove prototype instances that are defined in Detail Managers as well. If not enabled, it will ignore them.


Remove from Tree Manager: If this is enabled, the Instance Remover will remove prototype instances that are defined in Tree Managers as well. If not enabled, it will ignore them.


Remove from Prefab Manager: If this is enabled, the Instance Remover will remove prototype instances that are defined in Prefab Managers as well. If not enabled, it will ignore them.


Remove at Update: Specifies whether GPUI will use this Instance Remover during the Update loop. Disabling this option will cause removal upon instantiating this object only, and the Instance Remover will not do anything during the Update Loops.


Offset: With this option you can specify an offset that will be used to expand or shrink the area that is calculated from the Bounds/Colliders.


Please also note that what the Instance Remover is doing is actually using two API methods that you can directly use instead. These are the RemoveInstancesInsideBounds and RemoveInstancesInsideCollider methods.


GPUI GUI Info



GPU Instancer also has an Info script that you can use for Debugging purposes. You can add the GPUInstancerGUIInfo.cs script at any GameObject in your scene and it will overlay a small red text on your camera that shows information on the GPUI prototypes. The inspector options on this script are self explanatory, but please notice that if you use the Show Rendered Amount option it will cause a readback from the GPU each frame and this will cause a great performance hit. You can, however have that information for debugging purposes.


GPUI LOD Color Debugger



GPUI LOD Color Debugger

You can use the included script GPUInstancerLODColorDebugger.cs to visualize the LOD levels of your GPUI prototypes during runtime. This script can be added on the manager GameObject for automatic setup. Please note that the shader that is used by the prototype must have a _Color property for this to work.


Extension: Crowd Animations


CrowdAnim-StoreBanner-Small-450.png


GPU Instancer - Crowd Animations is available as a separate asset in the Unity Asset Store.


Crowd Animations is an an extension for GPUI that is designed for using massive amounts of animated characters in your scenes with high performance. CA uses the GPU Instancer core and adds GPU skinning techniques on top of GPUI's indirect instancing solution and GPU culling techniques. This results in a combination which will allow you to get the most out of GPU Instancing in Unity for your animated characters.


Crowd Animations works by baking the bone data of animation clips into a texture and reading that texture in Compute Shaders to feed skinning data to the rendering pipeline for indirect skinned-mesh instancing. Using the GPU Instancer backend for visibility tests in the GPU as well, the Crowd Animations extension is designed to be the ultimate solution for a GPU based animation workflow.



The Crowd Manager



GPUI-CrowdAnimations-Chompers450.gif


The Crowd Manager allows you to use GPUI's indirect instancing with skinned mesh renderers, allowing you to define animated characters as prototypes to GPUI. Using the Crowd Manager, you can have massive amounts of characters that are animated individually with high performance. The Crowd Manager is also fully integrated into the GPUI core, meaning that it allows for LODs, multiple skinned meshes and multiple submeshes on your prototypes. Furthermore, GPUI's culling techniques such as GPU occlusion and frustum culling also apply to the prototypes of this manager.


You can use the Crowd Manager a lot like how you use the Prefab Manager: by adding your character prefabs to the Manager, the instances of these prefabs in your scenes will be rendered by GPU Instancer. Also, just like the Prefab Manager, the Crowd Manager provides additional functionality such as adding/removing/updating instances at runtime, choosing an LOD level to render the shadows from, and much more.


Note that the Crowd Manager only accepts user created prefabs. It will not accept prefabs that are generated when importing your 3D model assets. Please also note that, to use a prefab with the Crowd Manager, the prefab must have an Animator Component on it, and must also have Skinned Mesh Renderer(s). The animation clips that are in the Animator component will be baked and the Skinned Mesh Renderers will be used to gather the bone data.


Adding a Crowd Manager


You can add a Crowd Manager from:

Tools -> GPU Instancer -> Add Crowd Manager

HelpButton.png   You can click the question mark icon at the top-right corner of the Crowd Manager at any time to get detailed information about these settings.


Crowd Animations supports two different animator workflows: The Mecanim Animator workflow and the Crowd Animator workflow. Below, you can find information on how you can setup the Crowd Manager for both of these workflows.



Adding the Character Prototypes



The Crowd Manager: Registered Prototypes


You can add an animated character to the Crowd Manager as a GPUI Prototype as usual by either dragging and dropping its prefab on the Add Button (or the Multi. Add area), or by clicking the Add button to choose its prefab. This prefab must have at least one Skinned Mesh Renderer, and must also be a User Created Prefab and not a Model Prefab that is generated when importing your 3D character models.


For both the Mecanim Animator workflow and the Crowd Animator workflow, the next step is to bake the animation texture, and GPUI will use the same texture for both workflows. In order to bake this animation texture, there must be an Animator component on the added prefab. When the animation texture is baked, GPUI will gather the animation clips from this Animator component. Therefore, for both workflows, the prefab must also have an Animator Component on it that will define the available animation clips for this prototype.


The Registered Prototypes section works exactly like it does in the Prefab Manager. It shows the list of registered prefab instances and their current instance counts in the scene. The first time you add a prefab, the manager automatically registers the instances in your scene and shows the registered instance counts. When you add or remove instances while designing your scene, it is required to register the instances in the scene again by using the Register Instances in Scene button.


The Prototypes Section shows the list of animated characters that are added to the Crowd Manager as prototypes and will be rendered by GPU Instancer. By clicking on the icons of these prototypes (or their prefab names in the Text Mode) you can select each prototype and edit their settings individually. You can also shift or ctrl click on them to edit some settings for multiple prototypes at once. GPUI will track the instances of the prefabs in the scene and render these instances with the settings you define for these prototypes.


Once you add a prototype, you can than go ahead and bake the animation texture for this prototype from the Animation Bake Data section.



Baking the Animation Texture



Baking the Animation Data
Testing the Animation Data

Crowd Animations works by baking the bone data of animation clips into a texture and reading that texture at runtime in Compute Shaders to animate a Skinned Mesh.


Because of this, both Crowd Animations workflows require you to bake the animation texture first. When you add a prefab that has an Animator component to the Crowd Manager, you can use the Animation Bake Data section in the Crowd Manager to bake this animation texture and test the baked animations.


Frame Rate: The number of frames per second that the animation will be played in. A higher frame rate will result in a smoother animation playback, but also a larger animation texture size.


Animation Texture: This is the Animation texture that is created when you bake the animations for this prototype. This field is reference only.


Bake Animations: You can use this button to bake the animations for this prototype. When this button is used, GPUI will gather all the animation clips from the Animator component of the prefab and bone data from the Skinned Mesh Renderers found in this prefab and create the animation texture with respect to these.

Test Animations: You can use this button to test the animations that are baked for this prototype. When this button is used, GPUI will instantiate an instance of this prefab in the scene and add the The Crowd Prefab Debugger component on it. The instantiated prefab instance will have a test material on it which will allow you to test the animations that were found on the original prefab's Animator component. This test material mimics how GPUI will run the animations on runtime, so you can choose the animation that you want to test and use the Frame Index slider on this component to test the generated animation texture. Please note that this test material uses a generic test shader instead of the one that will be used for this prototype at runtime and some shader properties (e.g. specularity, metalic, etc.) may not be shown in this test.


Choosing the Animator Workflow



Once you add the prototype to the manager and bake its animation texture, you can choose which workflow you wish o use this prototype with from the Animator Settings section. The Mecanim Animator and Crowd Animator buttons in this section work as a toggle, allowing you to select the workflow for the selected individual prototype. These workflows are designed with ease of use in mind, and all you need to do is to select the your workflow and the options you need for its animator.


Animator Settings: Mechanim Animator

The Mecanim Animator Workflow


You can use the Unity Mecanim Animator to handle the state machine for animations as usual, and GPUI will read the animator states from the Mecanim Animator. This will let you use your existing Animators and scripts with Crowd Animations, and make it possible to use indirect GPU Instancing out of the box with all the GPUI features such as GPU frustum and occlusion culling. This workflow increases GPU performance while rendering skinned meshes, but it won't be an ideal solution for projects that are CPU bound since the Mecanim Animator will still create an overhang for each instance.


In this workflow, you can also attach GameObjects on the bone transforms of your prefab instances.


Apply Root Motion: When enabled, GPUI will apply root the motion of the animation clips to your transforms to the prefab instances.

Remove Bone GOs: This option will remove the bone GameObjects from the prefab instances at runtime, resulting in improved performance. It is recommended to enable this option if you will not use to the bone transforms in your prefab instances.


Extra Bone GameObjects to Expose: Even when you remove the bone GameObjects for this prototype, you can choose to enable the GameObjects of some specific bones; for example to attach a weapon to your character's hand. When the bones in this list are selected, GPUI will keep their corresponding GameObjects in your prefab instances and apply the transforms of the bone hierarchy to them. This will be better in terms of performance as opposed to keeping all bone GameObjects.


Please keep in mind, that although in this workflow GPUI uses your existing Mecanim Animators, there are some limitations: Animation Layers, masks, and IK are not supported. Also, the maximum number of animation blends are for four animations. If your animators have more blends than 4, the first four animation clips with highest blend weights at a given time will be used.


Animator Settings: Crowd Animator

The Crowd Animator Workflow


The Crowd Animator is designed to get the best performance out of GPUI when rendering animated characters. You can use the Crowd Animator to handle your animation clips in the GPU through the GPUInstancer API and decide which animation to play at a given time. This workflow will require you to write your own scripts (or use visual scripting tools) to handle animation states manually - but it will also let you get the most out of GPUI since there won't be any overhang created by the Mecanim Animator.


Default Clip: This is the animation clip that will start playing for the instances of this prototype without any scripting. The list of animations displayed here are gathered from the Animator component of the original prefab.

Apply Root Motion: When enabled, GPUI will apply root motion of the animation clips to transforms of the prefab instances.


In order to see how you can script your animation states and run blended animations (up to 4 animations) when using the Crowd Animator, you can take a look at the GPUI Crowd Animations API.



Using a Custom Shader on the Character Models



The Crowd Animations Extension works out of the box with materials using the Standard, Standard (Specular) and Autodesk Interactive shaders. However, if you wish to use a custom shader with CA, you need to manually setup the shader for work with it. Please note that this requires a working knowledge of shaders.


Below, you can find the necessary information on how you can manually setup a shader to work with Crowd Animations:


Includes and Pragmas

For all passes, you need to include the UnityCG.cginc and the GPUICrowdInclude.cginc. You also need the multi_compile_instancing, multi_compile _ GPUI_CA_BINDPOSEOFFSET and instancing_options procedural:setupGPUI pragma directives:


...
Pass 
{
    ...
    CGPROGRAM

    #include "UnityCG.cginc"
    #include "GPUInstancer-CrowdAnimations/Shaders/Include/GPUICrowdInclude.cginc"

    #pragma multi_compile _ GPUI_CA_BINDPOSEOFFSET
    #pragma multi_compile_instancing
    #pragma instancing_options procedural:setupGPUI
    ...
    ENDCG
}
...


Please note that these directives must be declared in this order and in the beginning of your shader pass (or SubShader, if you are using a surface shader).

Vertex Function Modifications

The vertex function must first include the UNITY_SETUP_INSTANCE_ID(v) and the GPUI_CROWD_VERTEX(v) macros:


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


The Vertex Input Struct

For Vertex/Fragment shaders, you can simply use appdata_full. Surface Shaders will also be using this input struct. In both these cases, you can skip this step.


However, if you are using a custom input struct, the vertex function input struct must have TEXCOORD2, TEXCOORD3, POSITION, TANGENT, NORMAL defined. The following is an example with minimum members:


struct appdata_custom 
{
    float4 vertex : POSITION;
    float4 tangent : TANGENT;
    float3 normal : NORMAL;
    float4 texcoord2 : TEXCOORD2;
    float4 texcoord3 : TEXCOORD3;
    UNITY_VERTEX_INPUT_INSTANCE_ID
};


For custom vertex input structs, you also need to add defines in your shader that declare the names you use for your input struct members. Here is an example:


#define GPUI_CUSTOM_INPUT 1 // needs to be declared so GPUI does not override your defines
#define GPUI_STRUCT_NAME appdata_custom // the name of your input struct
#define GPUI_BONE_INDEX texcoord2 // TEXCOORD2
#define GPUI_BONE_WEIGHT texcoord3 // TEXCOORD3
#define GPUI_VERTEX vertex // VERTEX
#define GPUI_NORMAL normal // NORMAL
#define GPUI_TANGENT tangent // TANGENT


UVs

The uv2 and uv3 channels on the mesh must not be used by the custom shader. Crowd Animations uses these channels to transmit bake data to the shader.



Crowd Animations Tools



Crowd Animator Randomizer



When using the Crowd Animator workflow, you can use this component to have the instances of your Crowd Prototypes run with randomized animations and animation frames without having to write any additional script.


The Crowd Animator Randomizer


GPUI Manager: The Crowd Manager that this randomizer component will work on.

Randomize Clips: When selected, the instances of all the prototypes of the selected Crowd Manager will start with playing a random animation clip.

Randomize Frames: When selected, the instances of all the prototypes of the selected Crowd Manager will start from a different frame index of their default animation clips.

Reset Animations: This option is designed to be activated from script at runtime, and when activated, it will reset all the prototypes to their default animations.



Integrations


MapMagic World Generator



GPUI - MapMagic Integration


GPU Instancer has a built-in integration with MapMagic World Generator. To use GPUI in your MapMagic Terrains, , you can use the following menu item:


Tools -> GPU Instancer -> Integration -> Add MapMagic Integration


Please note that GPUI checks the scripting define symbols in the player settings to determine whether you have MapMagic installed. If you don't have MapMagic, you will not see this menu item. If you have MapMagic, however, and if you don't see the integration menu item, the scripting define symbol might not be added to your player settings for some reason. In that case, you can manually add it by opening your Unity Player Settings (Edit -> Project Settings -> Player) and entering ;MAPMAGIC at the end of your scripting define symbols line.


When you add the integration from the menu, GPUI will add a GameObject to your scene with the options showing you what you want to import to GPUI from the MapMagic generation ruleset in the scene. You can then check the options you wish and click Import. This will turn the integration object into what looks like a combined version of all the GPUI Managers, and you can use the settings as you normally would in those managers.


This is all you need to do to render your MapMagic terrains with GPUI. If at any time you change or edit the MapMagic ruleset, you can click Import again and the changes will reflect on the integration as well.


Gaia



GPUI - Gaia Integration

GPU Instancer has a built-in integration with Gaia. If you wish to use Gaia generated terrains with GPUI, you can use the GX tab under the Gaia Manager to add all desired GPUI managers to your scene.


When you add the The Detail and the Tree Managers this way, it is exactly like adding them from the GPU Instancer Menu. They are there only for convenience.


When you use Add the Prefab Manager from the GX menu, however, GPUI shows you a window that is similar to GPUI's Scene Prefab Importer tool. Using this window, however, instead of the prefab instances in your scene, you are presented with prefab instances that come from the Gaia ruleset that that is defined in the scene.


We recommended you to check the Best Practices Page before using Gaia with GPUI - especially the section on Detail instancing - to get the most out of GPUI.