[email protected]

## [1.0.0-pre.65] - 2023-03-21

### Added

* Burst Occlusion Culling occlusion browser tool

### Changed

* Disable Entities Graphics error message if there is no active SRP.

CHANGELOG.md

@@ -1,8 +1,16 @@
----
-uid: changelog
----
 # Changelog
 
+## [1.0.0-pre.65] - 2023-03-21
+
+### Added
+
+* Burst Occlusion Culling occlusion browser tool
+
+### Changed
+
+* Disable Entities Graphics error message if there is no active SRP.
+
+
 ## [1.0.0-pre.44] - 2023-02-13
 
 ### Added
@@ -33,7 +41,6 @@ uid: changelog
 * Light baking will cause the MeshRenderers to bake, thus automatically updating the light map in the entities scene. This previously required forcing the reimport of the entity scene.
 * 'GraphicsDeviceType.OpenGLES2' is obsolete: 'OpenGL ES 2.0 is no longer supported in Unity 2023.1'
 
-
 ## [1.0.0-pre.15] - 2022-11-16
 
 ### Added
@@ -66,7 +73,7 @@ uid: changelog
 * Fixed an issue where Entities Graphics would cause issues with the device being able to idle.
 
 
-## [1.0.0-exp.8] - 2022-09-21
+## [1.0.0-epx.8] - 2022-09-21
 
 ### Added
 

Documentation~/TableOfContents.md

@@ -1,4 +1,4 @@
-* [Entities Graphics](index.md)
+* [Entities Graphics package](index.md)
   * [What's new](whats-new.md)
   * [Upgrade guide](upgrade-guide.md)
 * [Requirements](requirements-and-compatibility.md)
@@ -12,10 +12,19 @@
     * [Material Overrides Using an Asset](material-overrides-asset.md)
   * [Hybrid Entities](hybrid-entities.md)
   * [The BatchRendererGroup API](batch-renderer-group-api.md)
-* Animation
   * [Mesh deformations](mesh_deformations.md)
+* [Burst occlusion culling](burst-occlusion-culling.md)
+  * [Requirements and compatibility](burst-occlusion-culling-requirements.md)
+  * [Overview](burst-occlusion-culling-overview.md)
+  * [Setup](burst-occlusion-culling-setup.md)
+  * [Optimize occlusion culling](burst-occlusion-culling-optimize.md)
+  * [Rendering Debugger Culling tab reference](burst-occlusion-culling-debug.md)
+  * [Components](burst-occlusion-culling-components.md)
+    * [Occluder component](burst-occlusion-culling-components-occluder.md)
+    * [Occlusion View component](burst-occlusion-culling-components-occlusion-view.md)
 * [Runtime Usage](runtime-usage.md)
   * [Runtime Entity Creation](runtime-entity-creation.md)
 * Sample Content
   * [Sample Projects](sample-projects.md)
+* [Known Issues](known-issues.md)
 

Documentation~/burst-occlusion-culling-components-occluder.md

@@ -0,0 +1,19 @@
+# Occluder component
+
+An Occluder MonoBehaviour component specifies which entities are occluders. After you attach this component to a GameObject, the [baking process](https://docs.unity3d.com/Packages/com.unity.entities@latest?subfolder=/manual/baking.html) attaches the relevant occluder ECS components to the converted entity.
+
+> [!TIP]
+> The [Scene view](xref:UsingTheSceneView) provides a visual [Gizmo](xref:GizmosMenu) that displays a wireframe of the assigned occluder mesh using the current settings. This helps you to position, rotate, and scale the occluder mesh, if necessary, so it's inscribed within the visual mesh.
+
+## Occluder Inspector reference
+
+| **Property**       | **Description**                                              |
+| ------------------ | ------------------------------------------------------------ |
+| **Mesh**           | The mesh to use for occlusion culling calculations. This should be a low-poly mesh that is inscribed within the visual mesh. |
+| **Local Position** | The position offset to apply to the occlusion mesh.          |
+| **Local Rotation** | The rotation offset to apply to the occlusion mesh.          |
+| **Local Scale**    | The scale offset to apply to the occlusion mesh.             |
+
+## Additional resource
+
+* [Occlusion View component](burst-occlusion-culling-components-occlusion-view.md)

Documentation~/burst-occlusion-culling-components-occlusion-view.md

@@ -0,0 +1,16 @@
+# Occlusion View component
+
+An Occlusion View MonoBehaviour component specifies which cameras, lights, and reflection probes use Burst occlusion culling. It also configures the size of the buffer to use for occlusion culling calculations which affects the resource intensity and precision of the calculations.
+
+## Occlusion View Inspector reference
+
+| **Property**                | **Description**                                              |
+| --------------------------- | ------------------------------------------------------------ |
+| **Occlusion Enabled**       | Controls whether the attached cameras, light, or reflection probes uses Burst occlusion culling. |
+| **Occlusion Buffer Width**  | The width of the buffer to use for occlusion culling calculations. This value should always be a multiple of 16. |
+| **Occlusion Buffer Height** | The height of the buffer to use for occlusion culling calculations. This value should always be a multiple of 16. |
+
+## Additional resource
+
+* [Occluder component](burst-occlusion-culling-components-occluder.md)
+* [Optimize occlusion views](burst-occlusion-culling-optimize.md#optimize-occlusion-views)

Documentation~/burst-occlusion-culling-components.md

@@ -0,0 +1,12 @@
+# Burst occlusion culling components
+
+This section contains information on the MonoBehaviour components that configure Burst occlusion culling.
+
+| **Topic**                                                                        | **Description**                                                                                                                          |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| [Occluder component](burst-occlusion-culling-components-occluder.md)             | Understand the Occluder component, which creates and configures occluders.                                                               |
+| [Occlusion View component](burst-occlusion-culling-components-occlusion-view.md) | Understand the Occlusion View component, which configures Burst occlusion culling for individual cameras, lights, and reflection probes. |
+
+## Additional resources
+
+- [MonoBehaviour](xref:class-MonoBehaviour)

Documentation~/burst-occlusion-culling-debug.md

@@ -0,0 +1,55 @@
+# Rendering Debugger Culling tab reference
+
+The **Culling** tab in the [Rendering debugger](https://docs.unity3d.com/Packages/com.unity.render-pipelines.high-definition@latest?subfolder=/manual/Render-Pipeline-Debug-Window.html) includes debugging options and visualizations to help you investigate Burst occlusion culling issues.
+
+<table>
+  <thead>
+    <tr>
+      <th><strong>Property</strong></th>
+      <th colspan="2"><strong>Description</strong></th>
+    </tr>
+  </thead>
+  <tbody>
+<tr>
+  <td><strong>Freeze Occlusion</strong></td>
+  <td colspan="2">Indicates whether to temporarily pause the occlusion culling system and maintain the current occlusion results.<br/><br/>This is useful to confirm that objects you expect to be occluded during a single frame from a particular point-of-view are.<br/><br/>For an example of how to use this: enable **Freeze Occlusion** and identify some objects that you expect to be occluded from the current camera’s current point-of-view. Move the camera to a different position to view those objects and visually confirm what was occluded and what wasn't.<br/><br/>**Note**: The culling results include both occlusion culling and frustum culling.</td>
+</tr>
+<tr>
+  <td><strong>Pinned View</strong></td>
+  <td colspan="2">Specifies a view to use the occlusion culling results from. Unity uses the occlusion results from the pinned view in all other views. For example, other cameras, reflection probes, and the Scene view camera. When enabled, all views won't render objects that are occluded from the perspective of the pinned view, even if the objects aren't occluded from the perspective of the other views.<br/><br/>This is useful to view occlusion culling results over time.<br/><br/>For an example of how to use this: pin the [main camera](xref:UnityEngine.Camera.main) in your scene, [move the Scene view camera](xref:SceneViewNavigation) around to inspect which objects are hidden. Then move the main camera around to update the culling results.<br/><br/>Select **None** to disable view pinning.<br/><br/>**Note**: The culling results include both occlusion culling and frustum culling.</td>
+</tr>
+<tr>
+  <td rowspan="7"><strong>Debug Mode</strong></td>
+  <td colspan="2">Specifies an occlusion culling debug visualization to render.</td>
+</tr>
+<tr>
+  <td><strong>None</strong></td>
+  <td>Disables occlusion culling debug visualizations.</td>
+</tr>
+<tr>
+  <td><strong>Depth</strong></td>
+  <td>Visualizes the rasterized depth from the camera viewport.</td>
+</tr>
+<tr>
+  <td><strong>Test</strong></td>
+  <td>Visualizes the rasterized depth and shows occluded entities as red squares.</td>
+</tr>
+<tr>
+  <td><strong>Mesh</strong></td>
+  <td>Visualizes the occluders attached to GameObjects in the scene.</td>
+</tr>
+<tr>
+  <td><strong>Bounds</strong></td>
+  <td>Visualizes the axis-aligned bounding boxes for all meshes in the viewport.</td>
+</tr>
+<tr>
+  <td><strong>Inverted</strong></td>
+  <td>Inverts the logic Unity uses to display culling results. When enabled, Unity shows culled objects and hides not-culled objects.</td>
+</tr>
+</tbody>
+</table>
+
+## Additional resources
+
+- [Universal Render Pipeline Rendering Debugger](https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@latest?subfolder=/manual/features/rendering-debugger.html)
+- [High Definition Render Pipeline Rendering Debugger](https://docs.unity3d.com/Packages/com.unity.render-pipelines.high-definition@latest?subfolder=/manual/Render-Pipeline-Debug-Window.html)

Documentation~/burst-occlusion-culling-optimize.md

@@ -0,0 +1,13 @@
+# Optimize Burst occlusion culling
+
+If Burst occlusion culling is a good fit for a scene (refer to [When to use Burst occlusion culling](burst-occlusion-culling-overview.md#when-to-use-burst-occlusion-culling)), you can configure it to be bespokely optimized for the scene. This page explains the different methods you can use to get the best performance out of Burst occlusion culling for a particular scene.
+
+## Optimize occlusion views
+
+The Burst occlusion culling system can use a different buffer resolution for each view it processes. A lower-resolution buffer is less resource-intensive to process but produces a less precise culling result. If a view doesn't require precise occlusion culling results, you can reduce the resolution of its occlusion buffer to increase the performance of the Burst occlusion culling process.
+
+If an occlusion view uses a lower resolution buffer, the Burst occlusion culling system can misidentify some totally hidden objects as being visible. This means that the rendering system must unnecessarily process the objects. If you reduce the resolution of an occlusion view buffer, it's best practice to [profile](xref:Profiler) the scene to make sure that the reduced resolution doesn't degrade overall performance.
+
+## Additional resources
+
+- [Rendering Debugger Culling tab reference](burst-occlusion-culling-debug.md)

Documentation~/burst-occlusion-culling-overview.md

@@ -0,0 +1,39 @@
+# Burst occlusion culling overview
+
+The Burst occlusion culling system disables rendering for entities that are hidden behind other entities. This reduces the amount of data that Unity uploads to the GPU every frame and the amount of unnecessary work that the GPU must do.
+
+## How Burst occlusion culling works
+
+From the point of view of the cameras, lights, and reflection probes you specify, the Burst occlusion culling system determines which entities are completely hidden and don't need to be sent to the GPU for rendering. To do this, the system splits entities into occluders and occludees. The system gets all occluders and calculates which occludees are hidden by them.
+
+For performance reasons, the culling system doesn't use the same meshes in its culling calculations that the rendering system uses to draw entities. Instead, each occluder entity needs an additional lower-resolution mesh for the culling system to use instead. This occlusion mesh must be completely inscribed within the original mesh to avoid artifacts such as visible popping which is where objects appear and disappear visibly on-screen.
+
+Entities that use the Mesh Renderer component with **Dynamic Occlusion** set at [author time](https://docs.unity3d.com/Packages/com.unity.entities@latest?subfolder=/manual/editor-authoring-runtime.html) will be occludees. It's your responsibility to specify which entities are occluders. For help on how to decide which entities should be occluders, refer to [How to choose occluders](#how-to-choose-occluders).
+
+## When to use Burst occlusion culling
+
+Burst occlusion culling isn't appropriate for every application or scene. Scenes with many unique objects (with unique meshes or materials) that produce a lot of overdraw are perfect for Burst occlusion culling. Examples of this type of scene include large open worlds, dense cities, or interiors with separate rooms.
+
+Entities graphics can render instanced objects very quickly so it's often not beneficial to calculate which instanced objects are or aren't occluded and instead pass them all to the GPU to render. This is because the overhead of the occlusion culling calculations can exceed the overhead saved by reducing the number of instanced objects to draw.
+
+If there is a mix of unique and instanced objects in a scene, you can enable Burst occlusion culling for the scene, but make the instanced objects not occludees (disable **Dynamic Occlusion** on their Mesh Renderer component). This makes Burst occlusion culling optimize the draw submission for unique objects without wasting resources processing the instanced objects.
+
+## How to choose occluders
+
+Occlusion culling gives performance improvements if the overhead of the occlusion culling process is less than the overhead saved by reducing the number of entities to draw. The more occluders there are and the more complex their shape, the more resource intensive the occlusion culling process is. This means that it's important to choose which entities to set as occluders. An entity's size and shape decide its suitability as an occluder. 
+
+Entities likely to be suitable occluders are:
+
+* Entities that fill a significant part of the screen. For example, in a first-person perspective, items in the character’s hands are close to the camera. Also buildings and other large objects that the character can approach, that move toward the character, or that move around the scene.
+* Entities that are likely to occlude other entities. For example, a large mountain or building located in the center of the scene, or the walls in the interior of a building.
+
+Entities likely to be unsuitable occluders are:
+
+* Entities unlikely to fill a significant part of the screen. For example, a small book that the camera will never go very close to, or large objects that will always be far away from the camera and will therefore have small screen-space coverage.
+* Entities that are unlikely to occlude other entities. For example, mountains at the far distant edge of  a world, or a road mesh where there are few/no objects below the ground. Objects that are thin from more than one perspective are also unlikely to occlude other entities.
+* Entities that have a complex and non-convex shape. For example, hands or a tree with many branches and leaves.
+
+
+## Additional resources
+
+- [Set up Burst occlusion culling](burst-occlusion-culling-setup.md)

Documentation~/burst-occlusion-culling-requirements.md

@@ -0,0 +1,45 @@
+# Burst occlusion culling requirements and compatibility
+
+This page contains information on requirements and feature compatibility of Burst occlusion culling. Burst occlusion culling currently only supports [Entities](https://docs.unity3d.com/Packages/com.unity.entities@latest/index.html)-based applications.
+
+## Hardware requirements
+
+Burst occlusion culling requires the target CPU to support SSE4 or Neon instructions. Burst doesn't support 32-bit intrinsics for Neon so, to build for ARM, you must use a 64-bit build target.
+
+## Renderer compatibility
+
+The following table shows which renderers Burst occlusion culling supports.
+
+| Renderer                 | Occludee support | Occluder support |
+| ------------------------ | ---------------- | ---------------- |
+| Mesh Renderer            | Yes              | Yes              |
+| Skinned Mesh Renderer    | No               | No               |
+| Visual Effect            | No               | No               |
+| Particle System Renderer | No               | No               |
+| Light Probe Proxy Volume | No               | N/A              |
+| Sprite Renderer          | No               | No               |
+| Decal Projectors         | No               | No               |
+| TextMesh                 | No               | No               |
+
+## Occlusion view compatibility
+
+The following table shows which components Burst occlusion culling supports as views:
+
+| Component                | View support |
+| ------------------------ | ------------ |
+| Camera                   | Yes          |
+| Light (for shadows)      | Yes          |
+| Reflection Probe         | Yes          |
+| Planar Reflection Probe  | Yes          |
+
+
+## Feature compatibility
+
+Burst occlusion culling doesn't support the following:
+
+* [Mesh deformations](mesh_deformations.md).
+* Concurrent usage with Unity's [built-in occlusion culling system](xref:OcclusionCulling).
+
+## Additional resources
+
+* [Burst occlusion culling overview](burst-occlusion-culling-overview.md)