Merge pull request #8166 from Unity-Technologies/internal/2021.3/staging

Internal/2021.3/staging

Author: claire-nicholson

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

@@ -114,6 +114,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

@@ -56,7 +56,7 @@ 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>**Deferred**: The Deferred Rendering Path. For more information, refer to [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> |
+| **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).| 
 | &#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 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>**Force Prepass**: URP does a depth prepass to generate the scene depth texture. |
 

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"
 {
@@ -143,8 +145,6 @@ This block contains the HLSL program code.
 
 > **NOTE**: HLSL language is the preferred language for URP shaders.
 
-> **NOTE**: URP supports the CG language. If you add the CGPROGRAM/ENDCGPROGRAM block in a shader, Unity includes shaders from the Built-in Render Pipeline library automatically. If you include shaders from the SRP shader library, some SRP shader macros and functions might conflict with the Built-in Render Pipeline shader functions. Shaders with the CGPROGRAM block are not SRP Batcher compatible.
-
 This block contains the `#include` declaration with the reference to the `Core.hlsl` file.
 
 ```c++
@@ -164,6 +164,8 @@ Varyings vert(Attributes IN)
 }
 ```
 
+> **Note**: Don't import shader library files from both the Scriptable Render Pipeline (SRP) and the Built-In Render Pipeline in the same shader. Some SRP shader macros and functions might conflict with the Built-in Render Pipeline shader functions. For more information, refer to [Shader methods in URP](use-built-in-shader-methods) and [Import a file from the shader library in the Built-In Render Pipeline](../SL-BuiltinIncludes).
+
 The fragment shader in this basic HLSL code outputs the single color predefined in the code:
 
 ```c++

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)

Packages/com.unity.visualeffectgraph/Documentation~/Operator-ProbabilitySampling.md

@@ -6,7 +6,7 @@ Menu Path : **Operator > Logic > Probability Sampling**
 
 The **Probability Sampling** Operator performs a kind of switch/case operation where a weight controls the probability of selecting a case. If all weights are equal, this Operator produces a uniform distribution of the different output values.
 
-![img](Images/Operator-ProbabilitySamplingExample.gif)
+![A Random Selector Weighted Operator, and its effect on a 32 x 32 grid. In the Operator, Value 0 is red with a weight of 1, Value 1 is green with a weight of 0, and Value 2 is blue with a weight of 0. The grid is fully red. As the weight of Value 1 is dragged from 0 to 1, more red squares turn green. As the weight of Value 2 is then dragged from 0 to 1, more red and green squares turn blue.](Images/Operator-ProbabilitySamplingExample.gif)
 
 ## Operator settings