GPU Instancer:GettingStarted
About | Crowd Animations | Features | Getting Started | Terminology | Best Practices | API Documentation | F.A.Q.
GPU Instancer Pro is now available (Asset Store page). For documentation of the Pro version, please visit GPU Instancer Pro Documentation. |
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.
Contents
- 1 Quick Start
- 2 Common Manager Settings
- 3 Common Prototype Settings
- 4 The Prefab Manager
- 5 The Detail Manager
- 6 The Tree Manager
- 7 GPU Instancer Preferences
- 8 Tools
- 9 Components
- 10 Extension: Crowd Animations
- 11 Integrations
Quick Start
Getting Started with GPUI is extremely easy:
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.
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.
Disable Light Probes: While using Indirect GPU Instancing, by default all the instances share the same probe value. You can disable light probe usage by enabling this option.
Layer Mask: A layer mask can be used to discard specific MeshRenderers of the prototypes. When a Layer is not rendered by GPUI, it will be rendered by the Unity MeshRenderer component. GPUI will also not enable/disable the MeshRenderers of the discarded Layer when using a Prefab Manager. This allows you to disable GPUI for a specific child MeshRenderer of a prefab.
Enable MR on Disable: If this option is enabled, the manager will automatically re-enable the Mesh Renderers of the instances when the manager is disabled.
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.
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.
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.
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.
Min-Max Distance: Defines the minimum and 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.
Occlusion Cull Offset: Defines the depth value (ranged between 0 to 1) that the differences will be discarded while calculating culled objects from the depth texture. Higher offset values will result in less culling.
Occlusion Cull Accuracy: Defines the accuracy of occlusion culling. Higher values will result in more accurate culling with higher number of texture samples:
- 1 => 5 samples (middle point and corner points)
- 2 => 9 samples (adds 1/4 points)
- 3 => 17 samples (adds 1/8 and 3/8 points)
Min. Culling Distance: Defines the minimum distance that any kind of culling will occur. If it is a value higher than 0, the instances with a distance less than the specified value to the Camera will not be culled.
Bounds Size Offset: This value can be used to increase the bounding box size of the prototype. This will effect the culling and LOD calculations on the prototype. It is very useful for prototypes with shaders that modify vertex positions.
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.
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.
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
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.
You can add a Prefab Manager from:
Tools -> GPU Instancer -> Add Prefab Manager
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 Instances
Before entering the Play mode, 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 when Unity enters Play mode.
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.
When you enter Play mode, Registered Instances section shows you detailed information on the prototypes that are currently being rendered by GPUI.
This information consists of a breakdown of how many draw calls are being made for each prototype that is rendered by this manager.
Furthermore, this section shows the total instance count, total draw call count (that is made by this manager) and how many of these draw calls are made for shadows. You can use all this information to better design and optimize your usage of GPUI.
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.
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
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
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).
You can add a Detail Manager from:
Tools -> GPU Instancer -> Add Detail Manager For Terrains
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.
Keep Simulation Live: You can enable this option to keep the simulation live. When the simulation is live, deselecting the manager will not turn the simulation off. Please keep in mind however, that the terrain details that are painted during the simulation will not be rendered. Some detail prototype setting changes will also not be reflected. You can stop and start the simulation again to see these changes reflect on the simulation.
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.
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.
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.
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.
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
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.
You can add a Tree Manager from:
Tools -> GPU Instancer -> Add Tree Manager For Terrains
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.
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 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
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.
Auto Shader Conversion: If enabled, shaders of the prefabs that are added to the GPUI Managers will be automatically converted to support GPU Instancer. If you turn this feature off, you can use the shader conversion context menu to have GPUI convert your shaders.
Auto Shader Variant Handling: If enabled, shaders variants of the prefabs that are added to the GPUI Managers will be automatically added to a ShaderVariantCollection to be included in builds.
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.
Rendering Settings [ADVANCED]
Please note that the settings under this section are intended for advanced users only, and it is not recommended to change these settings if you're not certain you need to.
Custom Rendering Settings: By default, GPUI will decide the number of buffers and maximum thread counts being used depending on the target build platform. You can choose to enable the custom rendering settings here and set the maximum compute shader thread count that GPUI uses. You can also limit the number of compute buffers that are used. If you don't use any compute buffers, GPUI will write the buffer to a texture and use that texture on the GPU instead.
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 in this section. You can also remove individual packages or reload them.
Tools
Scene Prefab Importer
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
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
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 Replacer Tool is very easy. You can access it from:
Tools --> GPU Instancer --> Show Prefab Replacer
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.
Shaders Menu
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. By default, GPUI internally keeps track of these shaders and re-generates them if the original shader is modified.
GPUI offers various tools for you to manage the auto generated shaders it makes use of. You can access these tools from:
Tools --> GPU Instancer --> Shaders
Clear Shader Bindings: Shader Bindings is an internal object that keeps track of the generated (or compatible) shaders. If for any reason you wish to clear this object, you can use the Clear Shader Bindings menu item for this. 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, then 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, by default, the managers will instantly generate the necessary shaders again, so you don't have to worry about breaking GPUI while using this.
Regenerate GPUI Shaders: This tool will re-generate all the shaders that are defined in the shader bindings object. This operation will overwrite on the previously generated shaders.
Clear Shader Variants: GPUI makes use of a ShaderVariantCollection to make sure the variants of its auto generated shaders get into the build. By default, when you add a prefab to a manager, the variants of the shaders that the prefab's materials are using are added to this collection. If for any reason you wish to clear this object, you can use the Clear Shader Variants menu item for this.
Edit Shader Variants: This menu item selects the GPUIShaderVariantCollection
object in the project hierarchy. This will give you access to Unity's editor for this ShaderVariantCollection in the Inspector window. From there, you can add and remove shaders variants to this object easily by using the -
and +
buttons.
Please also note that you can disable the auto shader generation and variation handling features from the GPU Instancer Preferences window and use the automatic shader and variant setup features from the GPU Instancer Context Menu.
Context Menu Shader and Material Setup
You can use the GPU Instancer Context menu to have GPUI setup your shaders for you. Normally, when you add a prefab to a manager as a prototype, GPUI handles shader setup automatically. This auto conversion process creates a shader file in the original shader's folder with the [_GPUI] suffix and does not change the original shader in any way. However, if for any reason you need to manually execute this process, you can do this via the GPU Instancer context menu. To access this feature, you can right click on the shader (or a material using this shader) in your project hierarchy and either choose:
GPU Instancer --> Setup Shader for GPUI
or
GPU Instancer --> Setup Material for GPUI
Both of these options will create a version of your shader file in the same directory, and with the same file name and the [_GPUI] suffix. The material setup option will also add the shader variants that the Material is using to the GPUIShaderVariantCollection
. The generated shader's name is always [GPUInstancer/...] followed by the original shader name. GPUI will also add this shader to it's Shader Bindings and will start keeping track of changes to the original file. Any changes will be reflected on the generated shader file as well, and this generated shader will be used for prototype materials that use the original shader in your managers.
Using this feature might especially be required in cases where you create your prototypes from code at runtime instead of assigning them to a manager in the Editor.
Please note that GPUI can automatically setup your custom shaders in most cases; however, in the cases that this setup does not work, you can take a look at this F.A.Q article on how you can setup your shaders for GPUI manually.
Components
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.
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
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.
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
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.
GPUI Hi-Z Occlusion Generator and Debugger
If a GPUI Manager in the scene has the occlusion culling feature enabled, this script gets automatically attached to the camera that is defined (or auto-detected) in that manager. The Hi-Z Occlusion Generator makes sure the camera generates a Depth Texture, and uses this texture to create the Hi-Z Depth Texture that GPUI uses in the GPU for its occlusion culling operations.
Normally, you do not need to be concerned with this component at all. However, if you need to see the texture that GPUI is using for its operations (for debug purposes) this component is where you can activate the Hi-Z Occlusion Debugger to overlay that texture on the screen. This component also shows you some debug information such as the Depth Texture the camera is generating (Unity Depth Texture), the actual RenderTexture GPUI is using for occlusion culling (Hi-Z Depth Texture) and the resolution of the Hi-Z Depth Texture (Hi-Z Texture Size).
Debugger Enabled: You can use this checkbox to enable the debugger and overlay the Hi-Z Depth Texture on the rendering camera. When enabled, GPUI creates a UI canvas and displays the Hi-Z Depth Texture in this canvas.
Debugger GUI on Top: You can use this option to view the overlayed texture without any existing GUI that your scene might have.
Debugger Overlay: You can use this slider to increase/decrease the transparency of the overlaying Depth Texture.
Debugger Mip Level: The Hi-Z Occlusion Culling technique that GPUI employs for culling its instances works by selecting the correct mip level of a Depth Texture for culling the invisible object. This mip level usage is designed for both performance reasons and for accurate culling (e.g. not culling an object that is behind a cutout "wire fence" object). Using the Debugger Mip Level slider, you can see the generated mip levels for the current Hi-Z Depth Texture while overlaying this Depth Texture on the screen.
For more information on Occlusion Culling and how GPUI's implementation of this feature works, you can take a look at the Terminology section on occlusion culling.
Please note that the debugger features of this component do not enter your builds and having them enabled on this script has no effect on builds.
Extension: Crowd Animations
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
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.
You can add a Crowd Manager from:
Tools -> GPU Instancer -> Add Crowd Manager
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
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
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.
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.
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.
Has Optional Renderers: Use this option if you wish to enable/disable child GameObjects with SkinnedMeshRenderers at runtime. When enabled, you can choose the optional renderers from the list. New prototypes will be defined automatically at runtime for the optional renderers. When disabled, every skinned mesh will be rendered even if the GameObjects are disabled.
Enable Async Bone Updates: When this option is enabled, the Crowd Animator will make AsyncGPUReadbackRequest
to read the bone data from GPU memory and update the bone GameObjects accordingly. Since this works asynchroniously there will be some latency (e.g bone transforms will be updated every couple frames instead of every frame). There will still be some performance impact caused by the readback and applying the translation data back to the transforms. Please also note that the bone GameObjects will be child to the main GameObject and will not have a hierarchy at runtime.
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.
Animation Clip Settings
Even though the Crowd Animator Workflow requires you to handle animation states manually, GPUI gives you the option to define whether you want your animation clips to loop or not by default. You can make use of the Clip Settings section to define this behavior, and can also use this section to define animation events for specific frames.
Under the Clip Settings section, you can find the settings for specific animation clips that are baked for a prototype. You can start by selecting a clip from the dropdown menu.
Is Looping: You can use this option to define whether the clip is looping or not by default.
Animation Events: This section can be used to assign an event to the given frame with the given parameters (optional). Please note that the frame numbers can differ from the original animation depending on the baked FPS. You can also add multiple events by using the Add Event button. The event script itself is a MonoBehaviour that is assigned in the form of a GameObject in your scene, and it contains the event method.
For an example usage of animation events using the Crowd Animator Workflow, you can take a look at the included AnimationEvents demo scene.
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.
Optionally you can also add the shader_feature_vertex GPUI_CA_TEXTURE
pragma directive to be able to use the Test Animations feature with this shader.
... Pass { ... CGPROGRAM #include "UnityCG.cginc" #include "GPUInstancer-CrowdAnimations/Shaders/Include/GPUICrowdInclude.cginc" #pragma multi_compile _ GPUI_CA_BINDPOSEOFFSET #pragma shader_feature_vertex GPUI_CA_TEXTURE #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.
Shader Graph Setup
In order to use the Crowd Animations setup node, you need to first extract the GPU Instancer Shader Graph node. After that, you can extract the Crowd Animations setup package as well:
GPUInstancer-CrowdAnimations/Extras/GPUI-CA_ShaderGraph_Node.unitypackage
After importing the Crowd Animations package, GPU Instancer will add another ShaderGraph node in your project. You can find this new ShaderGraph node under the Sub Graphs
category with the name GPUI Crowd Setup
.
As shown in the image, you can use these nodes as pass-through nodes. You need to first connect the GPU Instancer node, and the Crowd Setup node after that. The GPUI node takes any position node as input, so that you can add it as the final step of your (vertex) position node network before the Crowd node.
Amplify Shader Editor Setup
You can use Amplify shader as depicted in this example. Important things to notice are that the vertex output should be absolute and the output of the node should be connected as in the picture.
If you can not find the "GPUI Crowd ASE Setup" node, please import the package under GPUInstancer-CrowdAnimations/Extras/GPUI-CA_ASE_Setup.unitypackage.
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.
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 and MapMagic II
GPU Instancer has a built-in integration with MapMagic World Generator. To use GPUI in your MapMagic Terrains, You need to first extract the package for the MapMagic version you are using from:
GPUInstancer/Extras/GPUI_MapMagic_Integration
or
GPUInstancer/Extras/GPUI_MapMagic2_Integration
You can then use the following menu item:
Tools -> GPU Instancer -> Integration -> Add MapMagic Integration
or
Tools -> GPU Instancer -> Integration -> Add MapMagic 2 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 (or for MapMagic 2, ;MAPMAGIC2
).
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.