[Port] [2022.3] DOCG-3869 Clarify depth priming and custom shaders

Author: markg-unity

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

@@ -129,6 +129,7 @@
     * [URP unlit shader with color input](writing-shaders-urp-unlit-color.md)
     * [Drawing a texture](writing-shaders-urp-unlit-texture.md)
     * [Visualizing normal vectors](writing-shaders-urp-unlit-normals.md)
+    * [Write depth only in a shader in URP](writing-shaders-urp-depth-only.md)
     * [Reconstruct the world space positions](writing-shaders-urp-reconstruct-world-position.md)
     * [Shader methods in URP](use-built-in-shader-methods.md)
       * [Import a file from the URP shader library](use-built-in-shader-methods-import.md)

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

@@ -62,9 +62,9 @@ This section contains properties related to rendering.
 | Property | Description |
 |:-|:-|
 | **Rendering&#160;Path** | Select the Rendering Path.<br/>Options:<ul><li>**Forward**: The Forward Rendering Path.</li><li>**Forward+**: The [Forward+ Rendering Path](rendering/forward-plus-rendering-path.md).</li><li>**Deferred**: The [Deferred Rendering Path](rendering/deferred-rendering-path.md).</li></ul> |
-| &#160;&#160;**Depth&#160;Priming&#160;Mode** | Specify whether Unity uses scene depth data to identify pixels the camera can't see, then skips the shader fragment stage for those pixels. This speeds up rendering, but has an upfront memory and performance cost. The amount rendering speeds up depends on how many pixels are hidden, and the complexity of the fragment shader code Unity skips.<br/><br/>The options are:<ul><li>**Disabled**: Unity doesn't perform depth priming.</li><li>**Auto**: Unity performs depth priming only if it's already performed a depth prepass. A depth prepass renders scene depth data early in the render pipeline. This option is not supported on Android, iOS, and Apple TV.</li><li>**Forced**: Unity always performs a depth prepass and depth priming.</li></ul><br/>Depth priming isn't compatible with the following:<ul><li>Platforms that use tile-based rendering.</li><li>The Deferred rendering path.</li><li>Multisample anti-aliasing (MSAA).</li></ul> |
-| &#160;&#160;**Accurate G-buffer normals** | Indicates whether to use a more resource-intensive normal encoding/decoding method to improve visual quality.<br /><br />This property is available only if **Rendering Path** is set to **Deferred**. |
-| **Depth&#160;Texture&#160;Mode** | Specifies at which stage in the render pipeline URP should copy the scene depth to a depth texture. The options are:<ul><li>**After Opaques**: URP copies the scene depth after the opaques render pass.</li><li>**After Transparents**: URP copies the scene depth after the transparents render pass.</li><li>**Force Prepass**: URP does a depth prepass to generate the scene depth texture.</li></ul>**Note**: On mobile devices, the **After Transparents** option can lead to a significant improvement in memory bandwidth. This is because the Copy Depth pass causes a switch in render target between the Opaque pass and the Transparents pass. When this occurs, Unity stores the contents of the Color Buffer in the main memory, and then loads it again once the Copy Depth pass is complete. The impact increases significantly when MSAA is enabled, because Unity must also store and load the MSAA data alongside the Color Buffer. |
+| **Depth Priming Mode** | Skips drawing overlapping pixels, to speed up rendering. Unity uses the depth texture to check which pixels overlap. The rendering improvement depends on the number of overlapping pixels and the complexity of the pixel shaders.<br/><br/>**Note**: If you use custom shaders, Unity renders opaque objects as invisible unless you add passes with `DepthOnly` and `DepthNormals` tags. For more information, refer to [Write depth only in a shader](writing-shaders-urp-depth-only.md).<br/><br/>The options are:<ul><li>**Disabled**: Doesn't perform depth priming.</li><li>**Auto**: Performs depth priming only if a depth prepass already exists in the render pipeline. This setting isn't supported on Android, iOS and Apple TV platforms.</li><li>**Forced**: Adds a depth prepass to the render pipeline if it doesn't already exist, and performs depth priming. Adding the depth prepass has an impact on memory and performance.</li></ul>**Note**: Depth priming isn't supported if you use a [deferred rendering path](rendering/deferred-rendering-path-landing.md) or [Multisample Anti-aliasing](anti-aliasing.md#multisample-anti-aliasing-msaa), or at runtime on mobile devices that use tile-based deferred rendering (TBDR).| 
+| **Accurate G-buffer normals** | Indicates whether to use a more resource-intensive normal encoding/decoding method to improve visual quality.<br /><br />This property is available only if **Rendering Path** is set to **Deferred**. |
+| **Depth Texture Mode** | Specifies the stage in the render pipeline at which to copy the scene depth to a depth texture. The options are:<ul><li>**After Opaques**: URP copies the scene depth after the opaques render pass.</li><li>**After Transparents**: URP copies the scene depth after the transparents render pass.</li><li>**Force Prepass**: URP does a depth prepass to generate the scene depth texture.</li></ul>**Note**: On mobile devices, the **After Transparents** option can lead to a significant improvement in memory bandwidth. This is because the Copy Depth pass causes a switch in render target between the Opaque pass and the Transparents pass. When this occurs, Unity stores the contents of the Color Buffer in the main memory, and then loads it again once the Copy Depth pass is complete. The impact increases significantly when MSAA is enabled as Unity must also store and load the MSAA data alongside the Color Buffer. |
 
 ### Native RenderPass
 

Packages/com.unity.render-pipelines.universal/Documentation~/writing-custom-shaders-urp.md

@@ -10,6 +10,7 @@ The section contains the following topics:
 * [URP unlit shader with color input](writing-shaders-urp-unlit-color.md)
 * [Drawing a texture](writing-shaders-urp-unlit-texture.md)
 * [Visualizing normal vectors](writing-shaders-urp-unlit-normals.md)
+* [Write depth only in a shader in URP](writing-shaders-urp-depth-only.md)
 * [Reconstruct the world space positions](writing-shaders-urp-reconstruct-world-position.md)
 * [Built-in shader methods in URP](use-built-in-shader-methods.md)
 

Packages/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-basic-unlit-structure.md

@@ -4,7 +4,9 @@ This example shows a basic URP-compatible shader. This shader fills the mesh sha
 
 To see the shader in action, copy and paste the following ShaderLab code into the Shader asset.
 
-```c++
+**Note**: If you enable **Depth Priming Mode** in the [URP asset](universalrp-asset.md), this shader renders opaque objects as invisible. For more information, refer to [Write depth only in a shader](writing-shaders-urp-depth-only.md).
+
+``` lang-cpp
 // This shader fills the mesh shape with a color predefined in the code.
 Shader "Example/URPUnlitShaderBasic"
 {

Packages/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-depth-only.md

@@ -0,0 +1,79 @@
+# Write a depth-only pass in a Universal Render Pipeline shader
+
+To create a depth prepass that writes the depth of objects before the opaque and transparent passes, add a shader pass that has the `DepthOnly` tag.
+
+Add this pass if you enable a setting that requires a depth prepass, otherwise Unity might render incorrectly. For example, if you enable **Depth Priming** in the [Universal Render Pipleine (URP) Asset](urp-universal-renderer.md), opaque objects are invisible.
+
+**Important**: To render correctly, make sure that every shader pass renders the same number of fragments in the same positions. For example, use an include or a macro to share the same code between passes, especially if you change the positions of vertices, use alpha clipping, or use effects like dithering. 
+
+## Add a depth-only pass
+
+The following example shows how to add a depth-only pass to a shader:
+
+```lang-hlsl
+Shader "Example/CustomShader"
+{
+    SubShader
+    {
+
+        Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" }
+
+        // Add a depth-only pass
+        Pass
+        {
+            Name "DepthOnlyPass"
+            Tags { "LightMode" = "DepthOnly" }
+
+            // Write depth to the depth buffer
+            ZWrite On
+
+            // Don't write to the color buffer
+            ColorMask 0 
+
+            ...
+        }
+
+        // The forward pass. This pass also writes depth by default.
+        Pass
+        {
+            Name "ForwardPass"
+            Tags { "LightMode" = "UniversalForward" }
+
+            ...
+        }
+    }
+}
+```
+
+## Add a depth and normals pass
+
+The recommended best practice is to also add a pass that has the `DepthNormals` tag, to write both the depth and normals of objects. Otherwise, if you enable features like screen space ambient occlusion (SSAO), Unity might not render objects correctly.
+
+For more information about outputting normals, refer to [Visualize normal vectors in a shader in URP](writing-shaders-urp-unlit-normals.md).
+
+For example:
+
+```lang-hlsl
+Pass
+{
+    Name "DepthNormalsPass"
+    Tags { "LightMode" = "DepthNormals" }
+
+    // Write depth to the depth buffer
+    ZWrite On
+
+    ...
+
+    float4 frag(Varyings input) : SV_TARGET
+    {
+        // Return the normal as a value between 0 and 1
+        float3 normalWS = normalize(input.normalWS);
+        return float4(normalWS * 0.5 + 0.5, 1);
+    }}
+```
+
+## Additional resources
+
+- [ShaderLab Pass tags](urp-shaders/urp-shaderlab-pass-tags.md)
+- [Shader methods](use-built-in-shader-methods.md)
+- [Universal Render Pipleine (URP) Asset](urp-universal-renderer.md)