Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
---
uid: changelog
---
# Changelog

## [1.0.0-exp.8] - 2022-09-21

### Added

* Hybrid assemblies will not be included in DOTS Runtime builds.
* Error/loading shader support for Hybrid Renderer
* Implement error/loading shader support for Entities Graphics.
* Implement Entity picking
* Shadow receiver sphere culling, which culls entities that cannot cast a visible shadow in the camera.
* Support for skinned motion vectors for High Definition Render Pipeline.

### Changed

* HLOD now requires root LOD nodes to have an HLODParent component rather than any GameObject parent.
* Removed use of the obsolete AlwaysUpdateSystem attribute. The new RequireMatchingQueriesForUpdate attribute has been added where appropriate.
* use the existing mesh buffer to retrieve the shared mesh in bind pose.
* use the existing graphics buffer to retrieve the skin weights for skinning.
* use the existing graphics buffer to retrieve the vertex deltas for blendshapes.
* DeformationsInPresentation and SkinnedMeshRendererConversion are now sealed.
* RegisterMaterialMeshSystem  is now internal instead of public.

### Removed

* PushMeshDataSystem, PushSkinMatrixSystem, PushBlendWeightSystem, InstantiateDeformationSystem, BlendShapeDeformationSystem and SkinningDeformationSystem are no longer part of the public API. Use DeformationsInPresentation instead.
* ENABLE_COMPUTE_DEFORMATIONS define, compute deformations are always enabled.

### Fixed

* Mesh and material indices not updating correctly if entity was created ad disabled and later enabled.
* Improved multi threaded load balancing of the Entities Graphics frustum culling Burst job
* Guard against overflow of static readonly int k_MaxSize for the deformation buffers.

## [0.14.0] - 2021-09-17

### Added

* Hybrid Renderer is automatically disabled when required support is not present or -nographics is given on the command line.

### Removed

* Hybrid Renderer V1 is now removed. V2 is the default renderer

### Fixed

* Fixed memory leak on frames where no data uploading happened.
* `HybridRendererSystem` was not correctly tracking all its component read/write dependencies.
* Warning about erroneous materials did not have enough information to act on them.

## [0.13.0] - 2021-03-15

### Removed

* Removed an unused internal struct that could cause compiler warnings.

### Fixed

* Entities that use the ambient light probe now have no SH components and use much less memory.
* Fixed a bug where global ambient probes were not always rendered correctly.

## [0.12.0] - 2021-01-26

### Added

* `CountNewChunksJob`, which is responsible for counting the number of new chunks since last frame, and filling the `newChunks` array.
* New #define DISABLE_HYBRID_LIGHT_PROBES to disable light probes globally to save memory.

### Changed

* (Root)LodRequirement component split to (Root)LodRange and (Root)LodWorldReferencePoint. The LOD ranges are created during conversion and the world reference point gets recalculated every frame. Splitting them allows performance optimizations.
* LODGroupWorldReferencePoint component added to LOD/HLOD groups. Allows us to transform the LOD pivot point once per group and storing it instead of doing repeated work per leaf entity. Total LODRequirementSystem performance increase up to 2x (when combined with the optimization above).
* Cache `GetComponentTypeHandle<>()` calls instead of doing them for each jobs.
* `UpdateAllHybridChunksJob` does not count the number of new chunks since last frame anymore.
* No longer track shader reflection version changes in `HybridRendererSystem`. A new system is now taking care of that in the `StructuralChangePresentationSystemGroup`
* No longer add/remove chunks in the `HybridRendererSystem`. A new system is now taking care of that in the `StructuralChangePresentationSystemGroup`
* Update minimum editor version to 2020.2.1f1-dots.3
*Loaded the Samples project in a 2020.2.1f1-dots.3 editor without any issues or console errors.
*Ran `Full CI [Entities] [project version]`

### Fixed

* LOD bitfield becoming stale when entities get removed or LOD components modified using LiveLink incremental update
* Fixed edge case bug in instance GPU allocation behavior.
* Improved GameObject conversion of light mapped objects during incremental conversion.
* Fixed a performance regression related to ambient probe update when probe grid was not available
* Do not perform structural changes in the `HybridRendererSystem` anymore.
* Static objects now always have per-object motion vectors disabled, regardless of MeshRenderer settings.

## [0.11.0] - 2020-11-13

### Added

* Frame queuing limiting solution to avoid hazards in the GPU uploader
* Hybrid V2 should now render objects with errors (e.g. missing or broken material) as bright magenta when the used SRP contains compatible error shaders, and display warnings.
* Support for lightmaps in hybrid renderer. You will need to bake with subscenes open, upon closing the lightmaps will be converted into the subscene. (Note: Requires release 10.1.0 of graphics packages).
* Support for lightprobes in hybrid renderer. Entities can dynamically look up the the current ambient probe or probe grid. (Note: Requires release 10.1.0 of graphics packages).
* Added error message when total used GPU memory is bigger than some backends can handle (1 GiB)
* HybridBatchPartition shared component that can force entities into separate batches.
* It is now possible to override DOTS instanced material properties using `ISharedComponentData`.
* RenderMeshDescription and RenderMeshUtility.AddComponent APIs to efficiently create Hybrid Rendered entities.

### Changed

* Log warning instead of error message when shader on SMR does not support DOTS Skinning
* Update minimum editor version to 2020.1.2f1

### Fixed

* Fixed float2 and float3 material properties like HDRP emissive color to work correctly.
* GPU buffer now grows by doubling, so initial startup lag is reduced.
* GPU resources are now cleaned up better in case of internal exceptions, leading to less errors in subsequent frames.
* Hybrid Renderer forces entities using URP and HDRP transparent materials into separate batches, so they are rendered in the correct order and produce correct rendering results.
* Fixed a bug with motion vector parameters not getting set correctly.
* HLOD conversion code now properly handles uninitialized components
* Removed internal frame queuing and replace it with frame fencing. Hybrid renderer will now longer wait for GPU buffers to be available, making it easier to see if you are GPU or CPU bound and avoiding some potential deadlocks.
* Disable deformation systems when no graphics device is present instead of throwing error.
* Fixed a bug with converting ambient light probe settings from GameObjects.

## [0.10.0] - 2020-09-24

### Added

* Error message when trying to convert SkinnedMeshRenderer that is using a shader that does not support skinning.

### Removed

* HybridRendererSettings asset was removed since memory management for the hybrid renderer data buffer is now automatic.

### Fixed

* Fixed missing mesh breaking subscene conversion
* Fixed chunk render bounds getting stale when RenderMesh shared component is changed.
* Improved Hybrid V2 memory usage during GPU uploading.
* Chunk render bounds getting stale when RenderMesh shared component is changed.
* Reduced Hybrid V2 peak memory use when batches are deleted and created at the same time.

## [0.9.0] - 2020-08-26

### Added

* Added: Hybrid component conversion support for: ParticleSystem and Volume+collider pairs (local volumes).
* Hybrid component conversion support for: ParticleSystem and Volume+collider pairs (local volumes).

### Fixed

* Fixed parallel for checking errors in Hybrid Renderer jobs.
* Fixed parallel for checking errors in occlusion jobs.

## [0.8.0] - 2020-08-04

### Changed

* Changed SkinnedMeshRendererConversion to take the RootBone into account. The render entities are now parented to the RootBone entity instead of the SkinnedMeshRenderer GameObject entity. As a result the RenderBounds will update correctly when the root bone is transformed.
* Changed SkinnedMeshRendererConversion to compute the SkinMatrices in SkinnedMeshRenderer's root bone space instead of worldspace.

### Fixed

* Fixed the Hybrid V2 uploading code not supporting more than 65535 separate upload operations per frame.
* Fixed render bounds being offset on converted SkinnedMeshRenderers.
* Partially fixed editor picking for Hybrid V2. Picking should now work in simple cases.
* Fixed a memory leak in the HeapAllocator class used by Hybrid Renderer.

## [0.7.0] - 2020-07-10

### Added

* Added support for controling persistent GPU buffer sizes through project settings

### Changed

* Updated minimum Unity Editor version to 2020.1.0b15 (40d9420e7de8)

### Fixed

* Improved hashing of the RenderMesh component.
* Fixed blendshapes getting applied with incorrect weights when the blendshapes are sparse.

### Known Issues

* This version is not compatible with 2020.2.0a17. Please update to the forthcoming alpha.

## [0.6.0] - 2020-05-27

### Added

* Added support for Mesh Deformations using compute shaders.
* Added support for sparse Blendshapes in the compute deformation system.
* Added support for Skinning using sparse bone weights with n number of influences in the compute deformation system.
* Added support for storing matrices as 3x4 on the GPU side. This will used for SRP 10.x series of packages and up.
* Added support for ambient probe environment lighting in URP.

### Changed

* Updated minimum Unity Editor version to 2020.1.0b9 (9c0aec301c8d)

### Fixed

* Fix floating point precision issue in vertex shader skinning.
* Fixed culling of hybrid lights in SceneView when using LiveLink (on 2020.1).

## [0.5.1] - 2020-05-04

### Changed

* Updated dependencies of this package.

## [0.5.0] - 2020-04-24

### Changed

Changes that only affect *Hybrid Renderer V2*:
* V2 now computes accurate AABBs for batches.
* V2 now longer adds WorldToLocal component to renderable entities.

Changes that affect both versions:
* Updated dependencies of this package.

### Deprecated

* Deprecated `FrozenRenderSceneTagProxy` and `RenderMeshProxy`. Please use the GameObject-to-Entity conversion workflow instead.

### Fixed

* Improved precision of camera frustum plane calculation in FrustumPlanes.FromCamera.
* Improved upload performance by uploading matrices as 4x3 instead of 4x4 as well as calculating inverses on the GPU
* Fixed default color properties being in the wrong color space

## [0.4.2] - 2020-04-15

### Changes

* Updated dependencies of this package.

## [0.4.1] - 2020-04-08

### Added (Hybrid V2)

* DisableRendering tag component for disabling rendering of entities

### Changed

* Improved hybrid.renderer landing document. Lots of new information.

### Fixed

* Fixed shadow mapping issues, especially when using the built-in renderer.

### Misc

* Highlighting additional changes introduced in `0.3.4-preview.24` which were not part of the previous changelogs, see below.

## [0.4.0] - 2020-03-13

### Added (All Versions)

* HeapAllocator: Offset allocator for sub-allocating resources such as NativeArrays or ComputeBuffers.

### Added (Hybrid V2)

Hybrid Renderer V2 is a new experimental renderer. It has a significantly higher performance and better feature set compared to the existing hybrid renderer. However, it is not yet confirmed to work on all platforms. To enable Hybrid Renderer V2, use the `ENABLE_HYBRID_RENDERER_V2` define in the Project Settings.

* HybridHDRPSamples Project for sample Scenes, unit tests and graphics tests.
* HybridURPSamples Project for sample Scenes, unit tests and graphics tests.
* MaterialOverride component: User friendly way to configure material overrides for shader properties.
* MaterialOverrideAsset: MaterialOverride asset for configuring general material overrides tied to a shader.
* SparseUploader: Delta update ECS data on GPU ComputeBuffer.
* Support for Unity built-in material properties: See BuiltinMaterialProperties directory for all IComponentData structs.
* Support for HDRP material properties: See HDRPMaterialProperties directory for all IComponentData structs.
* Support for URP material properties: See URPMaterialProperties directory for all IComponentData structs.
* New API (2020.1) to directly write to ComputeBuffer from parallel Burst jobs.
* New API (2020.1) to render Hybrid V2 batches though optimized SRP Batcher backend.

### Changes (Hybrid V2)

* Full rewrite of RenderMeshSystemV2 and InstancedRenderMeshBatchGroup. New code is located at `HybridV2RenderSystem.cs`.
* Partial rewrite of culling. Now all culling code is located at `HybridV2Culling.cs`.
* Hybrid Renderer and culling no longer use hash maps or IJobNativeMultiHashMapVisitKeyMutableValue jobs. Chunk components and chunk/forEach jobs are used instead.
* Batch setup and update now runs in parallel Burst jobs. Huge performance benefit.
* GPU persistent data model. ComputeBuffer to store persistent data on GPU side. Use `chunk.DidChange<T>` to delta update only changed data. Huge performance benefit.
* Per-instance shader constants are no longer setup to constant buffers for each viewport. This makes HDRP script main thread cost significantly smaller and saves significant amount of CPU time in render thread.

### Fixed

* Fixed culling issues (disappearing entities) 8000+ meters away from origin.
* Fixes to solve chunk fragmentation issues with ChunkWorldRenderBounds and other chunk components. Some changes were already included in 0.3.4 package, but not documented.
* Removed unnecessary reference to Unity.RenderPipelines.HighDefinition.Runtime from asmdef.
* Fixed uninitialized data issues causing flickering on some graphics backends (2020.1).

### Misc

* Highlighting `RenderBounds` component change introduced in `0.3.4-preview.24` which was not part of the previous changelogs, see below.

## [0.3.5] - 2020-03-03

### Changed

* Updated dependencies of this package.

## [0.3.4] - 2020-02-17

### Changed

* Updated dependencies of this package.
* When creating entities from scratch with code, user now needs to manually add `RenderBounds` component. Instantiating prefab works as before.
* Inactive GameObjects and Prefabs with `StaticOptimizeEntity` are now correctly treated as static
* `RenderBoundsUpdateSystem` is no longer `public` (breaking)
* deleted public `CreateMissingRenderBoundsFromMeshRenderer` system (breaking)

## [0.3.3] - 2020-01-28

### Changed

* Updated dependencies of this package.

## [0.3.2] - 2020-01-16

### Changed

* Updated dependencies of this package.

## [0.3.1] - 2019-12-16

**This version requires Unity 2019.3.0f1+**

### Changes

* Updated dependencies of this package.

## [0.3.0] - 2019-12-03

### Changes

* Updated dependencies of this package.

## [0.2.0] - 2019-11-22

**This version requires Unity 2019.3 0b11+**

### New Features

* Added support for vertex skinning.

### Fixes

* Fixed an issue where disabled UnityEngine Components were not getting ignored when converted via `ConvertToEntity` (it only was working for subscenes).

### Changes

* Removed `LightSystem` and light conversion.
* Updated dependencies for this package.

### Upgrade guide

  * `Lightsystem` was not performance by default and the concept of driving a game object from a component turned out to be not performance by default. It was also not maintainable because every property added to lights has to be reflected in this package.
  * `LightSystem` will be replaced with hybrid entities in the future. This will be a more clean uniform API for graphics related functionalities.

## [0.1.1] - 2019-08-06

### Fixes

* Adding a disabled tag component, now correctly disables the light.

### Changes

* Updated dependencies for this package.

## [0.1.0] - 2019-07-30

### New Features

* New `GameObjectConversionSettings` class that we are using to help manage the various and growing settings that can tune a GameObject conversion.
* New ability to convert and export Assets, which is initially needed for Tiny.
  * Assets are discovered via `DeclareReferencedAsset` in the `GameObjectConversionDeclareObjectsGroup` phase and can then be converted by a System during normal conversion phases.
  * Assets can be marked for export and assigned a guid via `GameObjectConversionSystem.GetGuidForAssetExport`. During the System `GameObjectExportGroup` phase, the converted assets can be exported via `TryCreateAssetExportWriter`.
* `GetPrimaryEntity`, `HasPrimaryEntity`, and the new `TryGetPrimaryEntity` all now work on `UnityEngine.Object` instead of `GameObject` so that they can also query against Unity Assets.

### Upgrade guide

* Various GameObject conversion-related methods now receive a `GameObjectConversionSettings` object rather than a set of misc config params.
  * `GameObjectConversionSettings` has implicit constructors for common parameters such as `World`, so much existing code will likely just work.
  * Otherwise construct a `GameObjectConversionSettings`, configure it with the parameters you used previously, and send it in.
* `GameObjectConversionSystem`: `AddLinkedEntityGroup` is now `DeclareLinkedEntityGroup` (should auto-upgrade).
* The System group `GameObjectConversionDeclarePrefabsGroup` is now `GameObjectConversionDeclareObjectsGroup`. This cannot auto-upgrade but a global find&replace will fix it.
* `GameObjectConversionUtility.ConversionFlags.None` is gone, use 0 instead.

### Changes

* Changing `entities` dependency to latest version (`0.1.0-preview`).

## [0.0.1-preview.13] - 2019-05-24

### Changes

* Changing `entities` dependency to latest version (`0.0.12-preview.33`).

## [0.0.1-preview.12] - 2019-05-16

### Fixes

* Adding/fixing `Equals` and `GetHashCode` for proxy components.

## [0.0.1-preview.11] - 2019-05-01

Change tracking started with this version.
  • Loading branch information
Unity Technologies committed Sep 21, 2022
0 parents commit 08ee8c2
Show file tree
Hide file tree
Showing 322 changed files with 25,951 additions and 0 deletions.
1 change: 1 addition & 0 deletions .footignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
ValidationExceptions.json
Empty file.
435 changes: 435 additions & 0 deletions CHANGELOG.md

Large diffs are not rendered by default.

7 changes: 7 additions & 0 deletions CHANGELOG.md.meta

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

21 changes: 21 additions & 0 deletions Documentation~/TableOfContents.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
* [Entities Graphics](index.md)
* [What's new](whats-new.md)
* [Upgrade guide](upgrade-guide.md)
* [Requirements](requirements-and-compatibility.md)
* [Getting Started](getting-started.md)
* [Entities Graphics Overview](overview.md)
* [Installing Entities Graphics](creating-a-new-entities-graphics-project.md)
* [Entities Graphics Feature Matrix](entities-graphics-versions.md)
* [Entities Graphics Features](entities-graphics-features.md)
* [Material Overrides](material-overrides.md)
* [Material Overrides Using C#](material-overrides-code.md)
* [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)
* [Runtime Usage](runtime-usage.md)
* [Runtime Entity Creation](runtime-entity-creation.md)
* Sample Content
* [Sample Projects](sample-projects.md)

7 changes: 7 additions & 0 deletions Documentation~/batch-renderer-group-api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# The BatchRendererGroup API

Entities Graphics is built on top of the Unity Engine [BatchRendererGroup](https://docs.unity3d.com/ScriptReference/Rendering.BatchRendererGroup.html) API. This API connects Entities Graphics to the Unity Engine rendering backend. If you use Entities Graphics, you don't need to interact with this API directly.

Unity updated the `BatchRendererGroup` API in Unity 2022.1 and replaced the old code paths with a single unified code path. The new API is easier to use, more efficient, more flexible, and has full test coverage.

For more information about the new BatchRendererGroup API, see the [BatchRendererGroup](https://docs.unity3d.com/ScriptReference/Rendering.BatchRendererGroup.html) documentation.
18 changes: 18 additions & 0 deletions Documentation~/creating-a-new-entities-graphics-project.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Creating a new Entities Graphics project

1. Create a new project. Depending on which render pipeline you want to use with Entities Graphics, the project should use a specific template:
* For the Universal Render Pipeline (URP), use the **Universal Render Pipeline** template.
* For the High Definition Render Pipeline (HDRP), use the **High Definition RP** template.
* Entities Graphics doesn't support the Built-in Render Pipeline (**3D** template).
2. Install the Entities Graphics package. Since this is an experimental package, it's not visible in the Package Manager window. The most consistent way to install this package for all versions of Unity is to use the [manifest.json](https://docs.unity3d.com/Manual/upm-manifestPrj.html).
1. In the Project window, go to **Packages** and right-click in an empty space.
2. Click **Show in Explorer** then, in the File Explorer window, open **Packages > manifest.json**.
3. Add `"com.unity.entities.graphics": "*<package version>*"` to the list of dependencies where \<version number> is the version of the Entities Graphics Package you want to install. For example:<br/>`"com.unity.entities.graphics": "0.x.y"`
4. Installing the Entities Graphics package also installs all of its dependencies including the DOTS packages.
3. Make sure SRP Batcher is enabled in your Project's URP or HDRP Assets. Creating a Project from the URP or HDRP template enables SRP Batcher automatically.
* **URP**: Select the [URP Asset](https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@latest?subfolder=/manual/universalrp-asset.html) and view it in the Inspector, go to **Advanced** and make sure **SRP Batcher** is enabled.
* **HDRP**: Select the [HDRP Asset](https://docs.unity3d.com/Packages/com.unity.render-pipelines.high-definition@latest?subfolder=/manual/index.html) and view it in the Inspector, enter [Debug Mode ](https://docs.unity3d.com/Manual/InspectorOptions.html)for the Inspector, and make sure **SRP Batcher** is enabled.
4. Entities Graphics does not support gamma space. Your Project must use linear color space. To do this:
1. Go to **Edit > Project Settings > Player > Other Settings** and locate the **Color Space** property.
2. Select **Linear** from the **Color Space** drop-down.
5. Entities Graphics is now installed and ready to use.
7 changes: 7 additions & 0 deletions Documentation~/entities-graphics-features.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Entities Graphics features

This section of the documentation contains information on the various features in Entities Graphics. The pages in this section are:

- [Material Property Overrides](material-overrides.md)
- [Hybrid Entities](hybrid-entities.md)
- [BatchRendererGroup API](batch-renderer-group-api.md)
31 changes: 31 additions & 0 deletions Documentation~/entities-graphics-versions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# Entities Graphics feature matrix

Entities Graphics is in active development. The goal is to reach full High Definition Render Pipeline (HDRP) and Universal Render Pipeline (URP) feature coverage. The only exceptions are select old deprecated features in each render pipeline that now have modern replacements.

The following table compares Entities Graphics feature support between HDRP and URP:

| **Feature** | **URP** | **HDRP** |
| ------------------------------- | ------------ | ---------------- |
| **Material property overrides** | Yes | Yes |
| **Built-in property overrides** | Yes | Yes |
| **Shader Graph** | Yes | Yes |
| **Lit shader** | Yes | Yes |
| **Unlit shader** | Yes | Yes |
| **Decal shader** | N/A | Yes |
| **LayeredLit shader** | N/A | Yes |
| **RenderLayer** | Yes | Yes |
| **TransformParams** | Yes | Yes |
| **DisableRendering** | Yes | Yes |
| **Motion blur** | Yes | Yes |
| **Temporal AA** | N/A | Yes |
| **Sun light** | Yes | Yes |
| **Point + spot lights** | 2022 | Yes |
| **Ambient probe** | Yes | Yes |
| **Light probes** | Yes | Yes |
| **Reflection probes** | 2022 | Yes |
| **Lightmaps** | Experimental | Experimental |
| **LOD crossfade** | 2021 | 2021 |
| **Custom pass shader override** | Yes | Yes |
| **Sorted Transparencies** | Yes | Yes |
| **Dynamic Occlusion culling** | Experimental | Experimental |
| **Skinning & deformations** | Experimental | Experimental |
20 changes: 20 additions & 0 deletions Documentation~/filter.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
apiRules:
- exclude:
# inherited Object methods
uidRegex: ^System\.Object\..*$
type: Method
- exclude:
# mentioning types from System.* namespace
uidRegex: ^System\..*$
type: Type
- exclude:
hasAttribute:
uid: System.ObsoleteAttribute
type: Member
- exclude:
hasAttribute:
uid: System.ObsoleteAttribute
type: Type
- exclude:
uidRegex: Tests$
type: Namespace
8 changes: 8 additions & 0 deletions Documentation~/getting-started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Getting started

Before you use the Entities Graphics package, make sure that its feature and platform coverage match your needs:

- For information about the graphics features Entities Graphics supports, see [Entities Graphics feature matrix](entities-graphics-versions.md).
- For information about render pipeline and Unity version compatibility, see [Requirements and compatibility](requirements-and-compatibility.md).

For information on how to create and set up your project, see [Creating a new Entities Graphics project](creating-a-new-entities-graphics-project.md).
40 changes: 40 additions & 0 deletions Documentation~/hybrid-entities.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Hybrid entities

Hybrid entities is a new DOTS feature. This feature allows you to attach MonoBehaviour components to DOTS entities, without converting them to IComponentData. A conversion system calls AddHybridComponent to attach a managed component to DOTS entity.

The following graphics related hybrid components are supported by Entities Graphics:

- Light + HDAdditionalLightData (HDRP)
- Light + UniversalAdditionalLightData (URP)
- ReflectionProbe + HDAdditionalReflectionData (HDRP)
- TextMesh
- SpriteRenderer
- ParticleSystem
- VisualEffect
- DecalProjector (HDRP)
- DensityVolume (HDRP)
- PlanarReflectionProbe (HDRP)
- Volume
- Volume + Sphere/Box/Capsule/MeshCollider pair (local volumes)

Note that the conversion of Camera (+HDAdditionalCameraData, UniversalAdditionalCameraData) components is disabled by default, because the scene main camera can't be a hybrid entity. To enable this conversion, add **HYBRID_ENTITIES_CAMERA_CONVERSION** define to your project settings.

Unity updates the transform of a hybrid entity whenever it updates the DOTS LocalToWorld component. Parenting a hybrid entity to a standard DOTS entity is supported. Hybrid entities can be included in DOTS subscenes. The managed component is serialized in the DOTS subscene.

You can write DOTS ECS queries including both IComponentData and managed hybrid components. However, these queries cannot be Burst compiled and must run in the main thread, as managed components are not thread safe. Use WithoutBurst(), and call .Run() instead of .Schedule().

An example of setting HDRP Light component intensity:

```C#
class AnimateHDRPIntensitySystem : SystemBase
{
protected override void OnUpdate()
{
Entities.WithoutBurst().ForEach((HDLightAdditionalData hdLight) =>
{
hdLight.intensity = 1.5f;
})
.Run();
}
}
```
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Documentation~/images/GPUInstancingMaterial.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Documentation~/images/HybridRendererSplash.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Documentation~/images/ProjectSettingsDialog.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 18 additions & 0 deletions Documentation~/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
uid: hybrid-render-overview
---
# Entities Graphics

![](images/HybridRendererSplash.png)

Entities Graphics provides systems and components for rendering [ECS](https://docs.unity3d.com/Packages/com.unity.entities@latest) entities. Entities Graphics is not a render pipeline: it is a system that collects the data necessary for rendering ECS entities, and sends this data to Unity's existing rendering architecture.

The Universal Render Pipeline (URP) and High Definition Render Pipeline (HDRP) are responsible for authoring the content and defining the rendering passes.

## Requirements

For information about Entities Graphics's requirements, see [Requirements and compatibility](requirements-and-compatibility.md).

## Getting started with Entities Graphics

For information on getting started with Entities Graphics, see the [Getting started](getting-started.md) section.
25 changes: 25 additions & 0 deletions Documentation~/material-overrides-asset.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
uid: material-overrides-howto

# Material overrides using the Material Override Asset

In Entities Graphics, you can override material properties without writing any code. This document describes the process on how to setup Material overrides for a material without writing any code. For more information on Material overrides, see [Material overrides](material-overrides.md).

The Material Override Asset is experimental.

## Setting up Material overrides

This section explains how to set up overrides for a material.

1. Select the material you want to override. If one does not exists, create a new one (menu: **Assets > Create > Material**) and select it.
2. If the material uses a Shader Graph, enable **Override Property Declaration** then set **Shader Declaration** to **Hybrid Per Instance** for every custom property you want to override.<br/>![](images/HybridInstancingProperty2020-2.png)
3. Create a new Material Override Asset (menu: **Assets > Create > Shader > Material Override Asset**) and select it.
4. In the Inspector, add your material to the **Material** property.<br/>![](images/MaterialOverrideMaterialSelect.png)
5. Click **Add Property Override** and select the properties you want this asset to override. Note that, if the material uses custom properties from a Shader Graph, you may have to wait for an asset data refresh and import to happen after you select the properties. When you add the property overrides, Unity creates a C# script next to your material in the Project window. Do not touch this file.<br/>![](images/MaterialOverridePropertySelect.png)
6. After you add the property overrides, modify them to be the values you want.
7. Select a GameObject that uses the material (or assign the material to a GameObject in your scene). Then, in the Inspector, click **Add Component** and select **Material Override**.
8. In the Inspector for that component, add your new Material Override Asset to the **Override Asset** field.<br/>![](images/MaterialOverrideAssetSelect.png)
9. You can add this asset to all GameObjects you want to give this set of overrides. Editing the material properties from the Inspector while the Material Override Asset is selected updates all the corresponding GameObjects.
10. You can also edit the properties on a GameObject's **Material Override** component as well to only affect that instance. When you do this, the margin turns blue and the property text becomes bold. This means you have overridden the defaults of the Material Override Asset.
11. You can either push the instance's setting to the asset to update all other GameObjects or reset it to the asset's default by right clicking on the property. This does not affect GameObjects that also override the asset's default values.<br/>![](images/MaterialOverridePerInstance.png)
12. You can create more Material Override Assets for the same material with the same or a different set of properties and then modify those properties per-GameObject as well. It does not interfere with other Material Override Assets.

88 changes: 88 additions & 0 deletions Documentation~/material-overrides-code.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Material overrides using C#

Entities Graphics supports per-entity overrides of various HDRP and URP material properties as well as overrides for custom Shader Graphs. You can write C#/Burst code to setup and animate material override values at runtime.

# Built-in Material overrides

Entities Graphics contains a built-in library of IComponentData components that you can add to your entities to override their material properties.

**Supported HDRP Material overrides:**

- AlphaCutoff
- AORemapMax
- AORemapMin
- BaseColor
- DetailAlbedoScale
- DetailNormalScale
- DetailSmoothnessScale
- DiffusionProfileHash
- EmissiveColor
- Metallic
- Smoothness
- SmoothnessRemapMax
- SmoothnessRemapMin
- SpecularColor
- Thickness
- ThicknessRemap
- UnlitColor (HDRP/Unlit)

**Supported URP Material overrides:**

- BaseColor
- BumpScale
- Cutoff
- EmissionColor
- Metallic
- OcclusionStrength
- Smoothness
- SpecColor

If you want to override a built-in HDRP or URP property not listed here, you can do that with custom Shader Graph Material overrides.

## Custom Shader Graph Material overrides

You can create your own custom Shader Graph properties, and expose them to DOTS as IComponentData. This allows you to write C#/Burst code to setup and animate your own shader inputs. To do this, see the following steps:

### Shader Graph Asset

1. Select your Shader Graph custom property and view it in the **Graph Inspector**.
2. Open the **Node Settings** tab.
3. Enable **Override Property Declaration** then set **Shader Declaration** to **Hybrid Per Instance**.<br/>![](images/HybridInstancingProperty2020-2.png)

### IComponentData

For the DOTS IComponentData struct, use the `MaterialProperty` Attribute, passing in the **Reference** and type for the Shader Graph property. For example, the IComponentData for the color (float4) property in the above step would be:

```
[MaterialProperty("_Color", MaterialPropertyFormat.Float4)]
public struct MyOwnColor : IComponentData
{
public float4 Value;
}
```

Ensure that the *Reference* name in Shader Graph and the string name in MaterialProperty attribute match exactly. The type declared in the MaterialPropertyFormat should also be compatible with both the Shader Graph and the struct data layout. If the binary size doesn't match, you will see an error message in the console window.

### Burst C# system

Now you can write Burst C# system to animate your Material property:

```
class AnimateMyOwnColorSystem : SystemBase
{
protected override void OnUpdate()
{
Entities.ForEach((ref MyOwnColor color, in MyAnimationTime t) =>
{
color.Value = new float4(
math.cos(t.Value + 1.0f),
math.cos(t.Value + 2.0f),
math.cos(t.Value + 3.0f),
1.0f);
})
.Schedule();
}
}
```

**Important:** You need to create a matching IComponentData struct for every custom Shader Graph property that has **Hybrid Per Instance** enabled. For information on how to do this, see [IComponentData](#icomponentdata). If you don't do this for a custom property, Entities Graphics zero fills the property.
15 changes: 15 additions & 0 deletions Documentation~/material-overrides.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Material overrides

Entities Graphics enables you to override the property values of various HDRP and URP material properties. It also enables you to override material properties for custom Shader Graphs. There are two ways to do this, either:

- [Using C#/Burst code](material-overrides-code.md)
- [Using the Material Override Asset](material-overrides-asset.md)

## Sample scenes

Entities Graphics provides sample scenes to show you material overrides using both the Universal Render Pipeline (URP) and the High Definition Render Pipeline (HDRP). For information on where to download the samples from, see [Sample Projects](sample-projects.md).

The paths to the per-render pipeline sample scenes are as follows:

- **HDRP**: **HybridHDRPSamples > SampleScenes > MaterialOverridesSample**
- **URP**: **HybridURPSamples > SampleScenes > MaterialOverridesSample**
Loading

0 comments on commit 08ee8c2

Please sign in to comment.