Internal/2022.3/staging

Internal/2022.3/staging

Author: claire-nicholson

Packages/com.unity.render-pipelines.high-definition/Documentation~/Light-Component.md

@@ -204,7 +204,7 @@ This section is only available in Realtime or Mixed light **Mode**.
 | **Property**               | **Description**                                              |
 | -------------------------- | ------------------------------------------------------------ |
 | **Enable**                 | Enable the checkbox to let this Light cast shadows.          |
-| **Update Mode**            | Use the drop-down to select the mode that HDRP uses to determine when to update a shadow map.<br />For information on the modes available, see the [Shadows in HDRP documentation](Shadows-in-HDRP.md#ShadowUpdateMode). |
+| **Update Mode** | Determines how often HDRP updates the shadow map for the Light. The options are: <ul><li><b>Every Frame</b>: Updates the shadow maps for the Light every frame. This is the default value.</li><li><b>On Enable</b>: Updates the shadow maps for the Light only when you enable the GameObject.</li><li><b>On Demand</b>: Updates the shadow maps for the Light only when you call the [`HDAdditionalLightData.RequestShadowMapRendering`](xref:UnityEngine.Rendering.HighDefinition.HDAdditionalLightData.RequestShadowMapRendering) API to update them.</li></ul>For more information, refer to [Update shadows less frequently](shadow-update-mode.md). |
 | **Resolution**             | Set the resolution of this Light’s shadow maps. Use the drop-down to select which quality mode to derive the resolution from. If you don't enable **Use Quality Settings**, or you select **Custom**, set the resolution, measured in pixels, in the input field.<br/>A higher resolution increases the fidelity of shadows at the cost of GPU performance and memory usage, so if you experience any performance issues, try using a lower value. |
 | **Near Plane**             | The distance, in meters, from the Light that GameObjects begin to cast shadows. |
 | **Shadowmask Mode**        | Defines how the shadowmask behaves for this Light. For detailed information on each **Shadowmask Mode**, see the documentation on [Shadowmasks](Shadows-in-HDRP.md#ShadowmaskModes). This property is only visible if you tet the **Mode**, under [General](#GeneralProperties), to **Mixed**. |

Packages/com.unity.render-pipelines.high-definition/Documentation~/Mask-Map-and-Detail-Map.md

@@ -19,6 +19,8 @@ The mask map contains four grayscale textures, one in each color channel. The de
 | **Blue**          | Detail mask |
 | **Alpha**         | Smoothness  |
 
+**Note:** The detail mask texture allows you to control where the detail texture is applied on your model. Use a value of `1` to display the detail texture and a value of `0` to mask it. For instance, if your model has skin pores, you might mask the lips and eyebrows to prevent the pores from appearing in those areas.
+
 To create a mask map, create a linear composited map in a photo editor, using the channels as described in the table above.
 
 The following example image demonstrates the individual components of a full mask map.

Packages/com.unity.render-pipelines.high-definition/Documentation~/Shadows-in-HDRP.md

@@ -32,6 +32,8 @@ To enable this feature:
 
 HDRP renders all real-time shadows for a frame using a shadow map atlas for all [punctual light](Glossary.md#PunctualLight) shadows, an atlas for area lights and another one for Directional Light shadows.
 
+HDRP also renders separate shadow atlases for cached shadows. For more information, refer to [Update shadows less frequently](shadow-update-mode.md).
+
 Set the size of these atlases in your Unity Project’s [HDRP Asset](HDRP-Asset.md). The atlas size determines the maximum resolution of shadows in your Scene.
 
 For example, the default size of an atlas is 4096 x 4096, which can fit:
@@ -101,50 +103,6 @@ Directional Lights don't use **Fade Distance**. Instead they use the **Max Dista
 
 **Shadowmask** is more memory intensive because the Camera uses shadowmask textures for static GameObjects close to the Camera, requiring a larger resolution shadowmask texture.
 
-<a name="ShadowUpdateMode"></a>
-
-## Shadow Update Mode
-
-You can use **Update Mode** to specify the calculation method HDRP uses to update a [Light](Light-Component.md)'s shadow maps. The following Update Modes are available:
-
-| **Update Mode** | **Description**                                              |
-| --------------- | ------------------------------------------------------------ |
-| **Every Frame** | HDRP updates the shadow maps for the light every frame.      |
-| **On Enable**   | HDRP updates the shadow maps for the light whenever you enable the GameObject. |
-| **On Demand**   | HDRP updates the shadow maps for the light every time you request them. To do this, call the RequestShadowMapRendering() method in the Light's HDAdditionalLightData component. |
-
-The High Definition Render Pipeline (HDRP) uses shadow caching to increase performance by only updating the shadow maps for [Lights](Light-Component.md) when it's necessary. HDRP has shadow atlases for punctual, area, and directional Lights, and separate shadow atlases specifically for cached punctual and cached area Lights. For cached directional Lights, they use the same atlas as normal directional Lights.
-
-When a Light that caches its shadows renders its shadow map for the first time, HDRP registers it with the cached shadow manager which assigns the shadow map to a cached shadow atlas. For directional Lights, HDRP uses the same shadow atlas for cached and non-cached directional Lights.
-
-A Light's **Update Mode** determines whether HDRP caches its shadow map:
-
-* If you set a Light's **Update Mode** to **OnEnable** or **OnDemand**, HDRP caches the Light's shadow map.
-* If you set a Light's **Update Mode** to **Every Frame**, HDRP doesn't cache the Light's shadow map.
-
-If you set the Light's **Update Mode** to **OnDemand**, you can manually request HDRP to update the Light's shadow map. To do this:
-
-1. Select a Light in your scene to view it in the Inspector window.
-2. Go to **HDAdditionalLightData** and open the More menu (&#8942;).
-3. Select **Edit Script**.
-2. Call the `RequestShadowMapRendering` function in the script.
-
-If the Light has multiple shadows (for example, multiple cascades of a directional light), you can request the update of a specific sub-shadow. To do this, use the `RequestSubShadowMapRendering(shadowIndex)` function.
-
-When you set **Update Mode** to **OnDemand** HDRP renders the shadow maps `OnEnable` for the first time, or when first registered with the system by default. You can change this using the `onDemandShadowRenderOnPlacement` property. If you set this property to false, HDRP doesn't render the shadows until you call `RequestShadowMapRendering` or `RequestSubShadowMapRendering(shadowIndex)`.
-
-For a Light that caches its shadows, if you disable it or set its **Update Mode** to **Every Frame**, HDRP can preserve the Light's shadow map's place in the cached shadow atlas. This means that, if you enable the Light again, HDRP doesn't need to re-render the shadow map or place it into a shadow atlas. For information on how to make a Light preserve its shadow map's place in the cached shadow atlas, see [Preserving shadow atlas placement](#preserving-shadow-atlas-placement).
-
-As a shortcut for a common case, HDRP offers an option to automatically trigger an update when either the position or rotation of a light changes above a certain threshold. To enable this option:
-
-1. Select a Light in your Scene to view it in the Inspector window.
-2. Go to **Light** > **Shadows** and set **Update Mode** to **On Enable**
-3. Enable **Update on light movement**.
-
-You can customize the threshold that HDRP uses to determine how much a light needs to move or rotate to trigger an update. To do this, use the properties: `cachedShadowTranslationUpdateThreshold` and `cachedShadowAngleUpdateThreshold` properties on the Light's **HDAdditionalLightData** component.
-
-**Note**: Point lights ignore the angle differences when determining if they need to perform an update in this mode.
-
 ### Customising shadow caching
 HDRP caches shadow maps for Punctual Lights into one atlas, Area Lights into another, and Directional Lights into the same atlas as non-cached Directional Lights. You can change the resolution of the first two cached shadow atlases independently of one another. To do this:
 
@@ -161,19 +119,6 @@ After a Scene loads with the Lights you have already placed, if you add a new Li
 
 It's possible to check if a Light's shadow maps have a place in the cached shadow atlas by using `HDCachedShadowManager.instance.LightHasBeenPlacedInAtlas`. It's also possible to check if a Light's shadow maps have been placed and rendered at least once with `HDCachedShadowManager.instance.LightHasBeenPlaceAndRenderedAtLeastOnce`.
 
-### Preserving shadow atlas placement
-
-If you disable the Light or change its **Update Mode** to **Every Frame**, the cached shadow manager unreserves the Light's shadow map's space in the cached shadow atlas and HDRP begins to render the Light's shadow map to the normal shadow atlases every frame. If the cached shadow manager needs to allocate space on the atlas for another Light, it can overwrite the space currently taken up by the original Light's shadow map.
-
-If you want to temporarily set a Light's **Update Mode** to **Every Frame** and want to set it back to **On Enable** or **On Demand** later, you can preserve the Light's shadow map placement in its atlas. This is useful, for example, if you want HDRP to cache a far away Light's shadow map, but update it every frame when it gets close to the [Camera](HDRP-Camera.md). To do this:
-
-1. Select a Light in your scene to view it in the Inspector window.
-2. Go to **HDAdditionalLightData** and open the More menu (&#8942;)
-3. Select **Edit Script**
-4. Enable **preserveCachedShadow** and set it to **True**. HDRP preserves the Light's shadow map's space in its shadow atlas.
-
-**Note**: Even if you enable **preserveCachedShadow**, if you destroy the Light, it loses its placement in the shadow atlas.
-
 ### Mixed Cached Shadow Maps
 
 In HDRP it's possible to cache only some of the shadow map. To do this:

Packages/com.unity.render-pipelines.high-definition/Documentation~/TableOfContents.md

@@ -193,6 +193,7 @@
   * [Local Volumetric Fog](Local-Volumetric-Fog.md)
   * [Light Layers](Light-Layers.md)
   * [Shadows](Shadows-in-HDRP.md)
+  * [Update shadows less frequently](shadow-update-mode.md)
   * [Shadowmasks](Lighting-Mode-Shadowmask.md)
   * [Volumetric Lighting](Volumetric-Lighting.md)
   * [Physical Light Units and Intensities](Physical-Light-Units.md)

Packages/com.unity.render-pipelines.high-definition/Documentation~/shadow-update-mode.md

@@ -0,0 +1,55 @@
+# Update shadows less frequently
+
+By default, the High Definition Render Pipline (HDRP) calculates the shadow map of a Light every frame. To improve performance, reduce how often HDRP updates the shadow map.
+
+## Reduce shadow map updates
+
+Follow these steps:
+
+1. Select a Light in your Scene.
+1. In the Inspector window, in the **Shadows** section, set **Update Mode** to **On Enable** or **On Demand**.
+
+   - **On Enable**: Updates the shadow map only when the Light is enabled.
+   - **On Demand**: Updates the shadow map only when you use an API to update the shadows manually.
+
+In these modes, HDRP caches the shadow map when the shadows update, and uses the cached version between updates.
+
+Point Lights and Area Lights have their own shadow atlas for cached shadows. Directional Lights store cached shadows in the same shadow atlas as non-cached Directional Lights. For more information about shadow atlases, refer to [Control shadow resolution and quality](Shadows-in-HDRP.md). 
+
+## Updates shadows manually
+
+If you set the **Update Mode** of the Light to **On Demand**, follow these steps to update the shadows:
+
+1. In the Inspector window for the Light, go to **HDAdditionalLightData** and open the **More** (⋮) menu.
+1. Select **Edit Script**.
+1. Call the `RequestShadowMapRendering` API in the script when you want to update the shadows.
+
+HDRP also updates the shadows when you first enable [Contact Shadows](Override-Contact-Shadows.md).
+
+If you set a Directional Light to **On Demand**, update shadows frequently so they stay up-to-date with the camera position. Otherwise you might see visual artifacts.
+
+For more information about customizing which shadows HDRP updates and when, refer to the [`HDAdditionalLightData`](xref:UnityEngine.Rendering.HighDefinition.HDAdditionalLightData) API.
+
+## Update shadows when the Light moves
+
+To update the shadow map only when the position or rotation of the Light changes, follow these steps:
+
+1. Set **Update Mode** to **On Enable**.
+1. Enable **Update on light movement**.
+
+To customize how much a light needs to move or rotate to trigger an update, use the [`cachedShadowAngleUpdateThreshold`](xref:UnityEngine.Rendering.HighDefinition.HDAdditionalLightData.cachedShadowAngleUpdateThreshold) and [`cachedShadowTranslationUpdateThreshold`](xref:UnityEngine.Rendering.HighDefinition.HDAdditionalLightData.cachedShadowTranslationUpdateThreshold) APIs.
+
+**Note**: Point Lights ignore `cachedShadowAngleUpdateThreshold`.
+
+## Preserve cached shadows
+
+To preserve a cached shadow map when you disable a Light or set its **Update Mode** back to **Every Frame**, edit your script to set the [`UnityEngine.Rendering.HighDefinition.HDAdditionalLightData.preserveCachedShadow`](HighDefinition.HDAdditionalLightData.preserveCachedShadow) property to `true`. 
+
+HDRP keeps the shadow map in the shadow atlas, so it doesn't need to re-render the shadow map or place it into a shadow atlas again. This is useful if, for example, you want HDRP to cache the shadow map of a distant Light, but update the shadow map every frame when the Light gets closer to the camera.
+
+**Note**: If you destroy the Light, HDRP no longer preserves its shadow map in the shadow atlas.
+
+## Additional resources
+
+- [Realtime shadows](Realtime-Shadows.md)
+- [Contact Shadows](Override-Contact-Shadows.md)

Packages/com.unity.render-pipelines.universal/Documentation~/2d-customlit.md

@@ -109,6 +109,7 @@
       * [Fullscreen Master Stack in Shader Graph reference for URP](urp-shaders/fullscreen-master-stack-reference.md)
 * [Shaders and Materials](shaders-in-universalrp.md)
   * [Shading Models](shading-model.md)
+  * [Assign a channel-packed texture to a material](shaders-in-universalrp-channel-packed-texture.md)
   * [Material Variants](materialvariant-URP.md)
   * [Complex Lit](shader-complex-lit.md)
   * [Lit](lit-shader.md)

Packages/com.unity.render-pipelines.universal/Documentation~/TableOfContents.md

@@ -140,7 +140,7 @@ This section contains information related to the impact of Rendering Layers on p
 
 * When using Rendering Layers only for Lights in the Forward Rendering Path, the performance impact is insignificant.
 
-* Performance impact grows more significantly when the Rendering Layer count exceeds a multiple of 8. For example: increasing the layer count from 8 to 9 layers has a bigger relative impact than increasing the layer count from 9 to 10 layers. The same consideration applies to increasing the count from 16 to 17, from 24 to 25 and so on.
+* Performance impact increases more significantly when the number of Rendering Layers reaches 9, 17, 25, and so on. This is because when the Rendering Layers exceed a multiple of 8, URP adds an extra texture channel the GPU must access.
 
 ## Additional resources
 

Packages/com.unity.render-pipelines.universal/Documentation~/features/rendering-layers.md

@@ -47,6 +47,8 @@ The __Surface Options__ control how URP renders the Material on a screen.
 
 The __Surface Inputs__ describe the surface itself. For example, you can use these properties to make your surface look wet, dry, rough, or smooth.
 
+You can use a single RGBA texture for the metallic, smoothness, and occlusion properties. For more information, refer to [Assign a channel-packed texture to a material in URP](shaders-in-universalrp-channel-packed-texture.md).
+
 **Note:** If you are used to the [Standard Shader](https://docs.unity3d.com/Manual/Shader-StandardShader.html) in the built-in Unity render pipeline, these options are similar to the Main Maps settings in the [Material Editor](https://docs.unity3d.com/Manual/StandardShaderContextAndContent.html).
 
 

Packages/com.unity.render-pipelines.universal/Documentation~/lit-shader.md

@@ -49,6 +49,8 @@ The __Surface Options__ control how URP renders the Material on a screen.
 
 The __Surface Inputs__ describe the surface itself. For example, you can use these properties to make your surface look wet, dry, rough, or smooth.
 
+You can use a single RGBA texture for the metallic, smoothness, and occlusion properties. For more information, refer to [Assign a channel-packed texture to a material in URP](shaders-in-universalrp-channel-packed-texture.md).
+
 **Note:** If you are used to the [Standard Shader](https://docs.unity3d.com/Manual/Shader-StandardShader.html) in the built-in Unity render pipeline, these options are similar to the Main Maps settings in the [Material Editor](https://docs.unity3d.com/Manual/StandardShaderContextAndContent.html).