GPU Instancer:GettingStarted

From GurBu Wiki
Jump to: navigation, search

About | Features | Getting Started | Terminology | Best Practices | F.A.Q.


GPU Instancer consists of three main Monobehavior classes. These are the Prefab Manager, Detail Manager and Tree Manager. The managers are designed with mainly ease of use in mind, and adding them to your scene is as easy as clicking a menu item. On this page, you will find information about these managers and everything GPUI comes with - including, various tools and components that will quickly get you started using GPUI.


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



Quick Start


Getting Started with GPUI is extremely easy:


1. Add the desired Managers to your scene


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


2. Thats all. Your prefabs/details/trees will now be rendered with GPUI.

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



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


The Prefab Manager


GPUI-PrefabInstancing002.png

By adding your prefabs to the GPU Instancer Prefab Manager, the prefab instances you add to your scenes are automatically rendered by GPU Instancer. It also provides additional functionality such as adding/removing/updating instances at runtime, changing material properties per instance, choosing an LOD level to render the shadows from, and much more. Note that the Prefab Manager only accepts user created prefabs. It will not accept prefabs that are generated when importing your 3D model assets.


Adding a Prefab Manager

You can add a Prefab Manager from:

Tools -> GPU Instancer -> Add Prefab Manager

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


Below are the sections you will find in the Prefab Manager.


The Prefab Manager

Scene Settings



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


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.


Registered Prefabs



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


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.


Prototypes



Prototypes show the list of objects that will be rendered by GPU Instancer. To modify the settings of a prototype, you can click on its image.


Add: Click on this button to select a prefab from your project and add it as a prototype to the manager. You can also drag and drop a prefab, a prefab instance or a GPUI prototype scriptable object on this button; in all these cases the referenced prefab is added to the manager. You can take a look at this section of the Best Practices Page to see how you can add multiple prefabs like this. Please note that you can also use the Scene Prefab Importer tool to create a Prefab Manager with the selected prefab instances in your scene.


The following settings can be edited for each individual prototype.


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.


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.


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.


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.


Runtime Settings



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


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.


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.


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.


The Detail Manager


GPUI-DetailInstancing002.png

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


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


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


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


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


Adding Detail Managers

You can add a Detail Manager from:

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

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


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


The Detail Manager

Scene Settings



The Scene Settings section contains scene specific settings like camera selection and global culling settings that effect all the prototypes in this manager. You can also easily switch to the Unity terrain that this manager is responsible for to paint details on the terrain. You can also set and unset the terrain connection with this manager from here.


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.


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


Unset Terrain: This button will severe the connection between the Unity terrain and this manager. You can use this to effectively disable GPUI's rendering of the terrain. It can later be enabled again by using the Set Terrain button.


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, 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: 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.


Debug



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


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


Global Detail Values



These settings are applied to all the detail prototypes defined in the manager.


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.


Prototypes



Prototypes show the list of objects that will be used in GPU Instancer. To modify a prototype, click on its image.


Generate Prototypes: This button can be used to synchronize the detail prototypes on the Unity terrain and GPU Instancer. It will reset the detail prototype properties with those from the Unity terrain, and use default values for properties that don't exist on the Unity terrain.


Add: Click on this button and select a texture or prefab to add as a detail prototype to the manager. You can also drag and drop a prefab or a texture on this button, and the Detail Manager will create a texture or prefab type prototype. The manager also adds the new prototype to the terrain as a detail prototype as either a grass texture or detail mesh respectively. Please also note that you can add prefabs with LOD Groups on them - in which case the Detail Manager will add only the first LOD level to the terrain as a detail mesh, but will render the whole prefab with all LOD Levels during play mode.


The following settings can be edited for each individual prototype.


Shadows


You can selectively turn shadows on and off for individual prototypes in this section. Please note that using shadows in grass prototypes is probably the costliest feature of the Detail Manager. This performance cost also depends on the amount of Shadow Cascades that are defined in the Unity Quality Settings.


Is Shadow Casting: This option specifies whether the instances of this prototype will cast shadows or not.


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.


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


Is Frustum Culling: Specifies whether prototype instances 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.


LOD



This section becomes visible only when a prefab type Detail Prototype in the manager is selected and the referenced prefab has an LOD Group. Using such prefabs with the Detail Manager is a great way to improve performance further. GPUI supports LOD groups on your prefabs and automatically renders them with indirect instancing while managing the necessary GPU buffer automatically. When using such prefabs, the first LOD level is added to the Unity terrain to show the prototype without simulating or entering the play mode.


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.


Detail Properties



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


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.


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.


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.


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


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


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


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


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


Wind Waves: Specifies whether there will be wind waves for the detail prototypes that use the foliage shader. The normal texture that is used to calculate winds can be changed globally (terrain specific) for all detail prototypes that use the foliage shader from the Wind Wave Normal Texture global property.


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


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


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


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


Actions



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

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


The Tree Manager


GPUI-TreeInstancing001.png


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


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


Adding Tree Managers

You can add a Tree Manager from:

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

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


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


The Tree Manager

Scene Settings



The Scene Settings section contains scene specific settings like camera selection and global culling settings that effect all the prototypes in this manager. You can also easily switch to the Unity terrain that this manager is responsible for to paint details on the terrain. You can also set and unset the terrain connection with this manager from here.


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.


Paint on Terrain: This button can be used to navigate to the Unity terrain component that this manager is referencing. Trees should be painted on the terrain using Unity's native tools as usual. 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 Tree Manager button to come back to the manager.


Unset Terrain: This button will severe the connection between the Unity terrain and this manager. You can use this to effectively disable GPUI's rendering of the terrain. It can later be enabled again by using the Set Terrain button.


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.


Global Tree Values



These settings apply to all the tree prototypes in this Manager.


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.


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.


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.


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.


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


For SpeedTrees, GPUI replaces the SpeedTree billboard with the generated one and render it in the original's place. For all other trees, the generated billboard is added as a final LOD level.


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.


Tools

Scene Prefab Importer

GPUI-v097-ScenePrefabImporter.jpg

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


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


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

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

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


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

The Prefab Replacer

The Prefab Replacer Tool

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


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

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

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


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


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

Clear Shader Bindings

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


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


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


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


Components


GPUI Modification Collider



GPUI Modification Collider

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


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


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


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


GPUI Modification Collider (Inspector)


Using the Modification Collider is very simple:


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


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


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

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


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


GPUI Instance Remover



GPUI Instance Remover


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


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


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


GPUI Instance Remover (Inspector)

Using the Instance Remover is very simple:


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


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


There are a few options on the Instance Remover:


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


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


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


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


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


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


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


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


GPUI GUI Info



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


Integrations


MapMagic World Generator



GPUI - MapMagic Integration


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


GPU Instancer -> Integration -> Add MapMagic Integraton


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


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


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


Gaia



GPUI - Gaia Integration

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


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


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


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