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.
|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.|
- 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 Integrations
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.
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.
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.
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.
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.
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.
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.
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.
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.
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. 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.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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:
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.
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 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.
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.
If any actions are required after updating GPUI to a new version, you will be able to execute these actions from this section.
You can see which optional GPUI packages are loaded for this section. You can also remove individual packages or reload them.
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 Importer 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.
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.
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
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.
MapMagic World Generator
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.
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.