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

Internal/2021.3/staging

Author: UnityAljosha

Packages/com.unity.render-pipelines.core/Runtime/Inputs/InputRegistering.cs

@@ -59,11 +59,14 @@ static void CopyEntry(SerializedProperty spAxis, InputManagerEntry entry)
 
         static void AddEntriesWithoutCheck(SerializedProperty spAxes, List<InputManagerEntry> newEntries)
         {
+            if (newEntries.Count == 0)
+                return;
+
             int endOfCurrentInputList = spAxes.arraySize;
             spAxes.arraySize = endOfCurrentInputList + newEntries.Count;
-
-            SerializedProperty spAxis = spAxes.GetArrayElementAtIndex(endOfCurrentInputList - 1);
-            spAxis.Next(false);
+            // Assignment to spAxes.arraySize resizes the spAxes array to at least 1 larger than it used to be, and 
+            // therefore it is OK to use endOfCurrentInputList ("one-past-end of previous size") to get the array iterator.
+            SerializedProperty spAxis = spAxes.GetArrayElementAtIndex(endOfCurrentInputList);
             for (int i = 0; i < newEntries.Count; ++i, spAxis.Next(false))
                 CopyEntry(spAxis, newEntries[i]);
         }
@@ -74,6 +77,9 @@ static void AddEntriesWithoutCheck(SerializedProperty spAxes, List<InputManagerE
             int size = spAxes.arraySize;
             List<(string name, InputManagerEntry.Kind kind)> result = new List<(string name, InputManagerEntry.Kind kind)>(size);
 
+            if (size == 0)
+                return result;
+
             SerializedProperty spAxis = spAxes.GetArrayElementAtIndex(0);
             for (int i = 0; i < size; ++i, spAxis.Next(false))
                 result.Add((spAxis.FindPropertyRelative("m_Name").stringValue, (InputManagerEntry.Kind)spAxis.FindPropertyRelative("type").intValue));

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

@@ -10,19 +10,24 @@
   * [Package samples](package-samples.md)
     * [URP Package Samples](package-sample-urp-package-samples.md)
   * [Scene Templates](scene-templates.md)
+  * [Change Quality settings with code](quality/quality-settings-through-code.md)
   * [Understand performance](understand-performance.md)
   * [Configure for better performance](configure-for-better-performance.md)
 * [Render Pipeline Concepts](urp-concepts.md)
   * [The URP Asset](universalrp-asset.md)
   * [URP Global Settings](urp-global-settings.md)
   * [Universal Renderer](urp-universal-renderer.md)
   * [Deferred Rendering Path](rendering/deferred-rendering-path.md)
-  * [Renderer Feature](urp-renderer-feature.md)
+  * [Graphics settings window reference in URP](urp-global-settings.md)
+  * [Pre-built effects (Renderer Features)](urp-renderer-feature.md)
     * [How to add a Renderer Feature](urp-renderer-feature-how-to-add.md)
-    * [Render Objects Renderer Feature](renderer-features/how-to-custom-effect-render-objects.md)
-    * [Ambient Occlusion](post-processing-ssao.md)
-    * [Decal](renderer-feature-decal.md)
-      * [Decal Shader Graph](decal-shader.md)
+    * [Render Objects Renderer Feature](renderer-features/renderer-feature-render-objects-landing.md)	
+      * [Example: How to create a custom rendering effect using the Render Objects Renderer Feature](renderer-features/how-to-custom-effect-render-objects.md)
+      * [Render Objects Renderer Feature reference](renderer-features/renderer-feature-render-objects.md)
+    * [Decal Renderer Feature](renderer-feature-decal-landing.md)
+	    * [Decal Renderer Feature](renderer-feature-decal.md)
+	    * [Decal Shader Graph](decal-shader.md)
+    * [Screen Space Ambient Occlusion (SSAO) Renderer Feature](post-processing-ssao.md)
 * [Upgrade guides](upgrade-guides.md)
   * [Render Pipeline Converter](features/rp-converter.md)
   * [Upgrading to URP 12.0.x](upgrade-guide-2021-2.md)
@@ -96,6 +101,7 @@
   * [Particles Unlit](particles-unlit-shader.md)
   * [Decal](decal-shader.md)
   * [Upgrading shaders from Built-in](upgrading-your-shaders.md)
+    * [Upgrade custom shaders for URP compatibility](urp-shaders/birp-urp-custom-shader-upgrade-guide.md)
   * [Shader stripping](shader-stripping.md)
   * [Writing custom shaders](writing-custom-shaders-urp.md)
     * [Creating a sample scene](writing-shaders-urp-basic-prerequisites.md)
@@ -105,14 +111,19 @@
     * [Visualizing normal vectors](writing-shaders-urp-unlit-normals.md)
     * [Reconstruct the world space positions](writing-shaders-urp-reconstruct-world-position.md)
   * [URP ShaderLab Pass tags](urp-shaders/urp-shaderlab-pass-tags.md)
-* [How to](how-to.md)
-  * [Blit in XR](renderer-features/how-to-fullscreen-blit-in-xr-spi.md)
-  * [Use Render Objects Renderer Feature](renderer-features/how-to-custom-effect-render-objects.md)
-  * [Create custom Renderer Feature](containers/create-custom-renderer-feature-1.md)
-  * [Change Quality settings with code](quality/quality-settings-through-code.md)
-* [Customizing URP](customizing-urp.md)
-  * [beginCameraRendering event](using-begincamerarendering.md)
-  * [Create custom Renderer Feature](renderer-features/create-custom-renderer-feature.md)
+* [Custom rendering and post-processing](customizing-urp.md)
+  * [Custom render passes](renderer-features/custom-rendering-passes.md)
+    * [Custom render pass workflow in URP](renderer-features/custom-rendering-pass-workflow-in-urp.md)
+    * [Scriptable Render Passes](renderer-features/scriptable-render-passes.md)
+      * [Scriptable Render Passes](renderer-features/intro-to-scriptable-render-passes.md)
+      * [Write a Scriptable Render Pass](renderer-features/write-a-scriptable-render-pass.md)
+      * [Inject a pass via scripting](customize/inject-render-pass-via-script.md)    
+    * [Scriptable Renderer Features](renderer-features/scriptable-renderer-features/scriptable-renderer-features-landing.md)
+      * [Introduction to Scriptable Renderer Features](renderer-features/scriptable-renderer-features/intro-to-scriptable-renderer-features.md)
+      * [Inject a custom render pass using a Scriptable Renderer Feature](renderer-features/scriptable-renderer-features/inject-a-pass-using-a-scriptable-renderer-feature.md)
+      * [Apply a Scriptable Renderer Feature to a specific camera type](renderer-features/scriptable-renderer-features/apply-scriptable-feature-to-specific-camera.md)
+      * [Example of a complete Scriptable Renderer Feature](renderer-features/create-custom-renderer-feature.md)  
+  * [Scriptable Renderer Feature and Scriptable Render Pass API reference](renderer-features/scriptable-renderer-features/scriptable-renderer-feature-reference.md)
 * [Optimization](urp-optimization.md)
   * [Rendering Debugger](features/rendering-debugger.md)
   * [Optimize for better performance](optimize-for-better-performance.md)

Packages/com.unity.render-pipelines.universal/Documentation~/using-begincamerarendering.md renamed to Packages/com.unity.render-pipelines.universal/Documentation~/customize/inject-render-pass-via-script.md

@@ -1,21 +1,57 @@
-# Using the beginCameraRendering event
+# Inject a render pass via scripting
 
-The example on this page shows how to use the [beginCameraRendering](https://docs.unity3d.com/ScriptReference/Rendering.RenderPipelineManager-beginCameraRendering.html) event to run a custom method.
-
-## beginCameraRendering event overview
-
-Unity raises a `beginCameraRendering` event before it renders each active Camera in every frame. If a Camera is inactive (for example, if the __Camera__ component checkbox is cleared on a Camera GameObject), Unity does not raise a `beginCameraRendering` event for this Camera.
+Unity raises a [beginCameraRendering](https://docs.unity3d.com/ScriptReference/Rendering.RenderPipelineManager-beginCameraRendering.html) event before it renders each active Camera in every frame. If a Camera is inactive (for example, if the **Camera** component checkbox is cleared on a Camera GameObject), Unity does not raise a `beginCameraRendering` event for this Camera.
 
 When you subscribe a method to this event, you can execute custom logic before Unity renders the Camera. Examples of custom logic include rendering extra Cameras to Render Textures, and using those Textures for effects like planar reflections or surveillance camera views.
 
 Other events in the [RenderPipelineManager](https://docs.unity3d.com/ScriptReference/Rendering.RenderPipelineManager.html) class provide more ways to customize URP. You can also use the principles described in this article with those events.
 
-## beginCameraRendering event example
+## Use the RenderPipelineManager API
+
+1. Subscribe a method to one of the events in the [RenderPipelineManager](https://docs.unity3d.com/ScriptReference/Rendering.RenderPipelineManager.html) class.
+
+2. In the subscribed method, use the `EnqueuePass` method of a `ScriptableRenderer` instance to inject a custom render pass into the URP frame rendering.
+
+Example code:
+
+```C#
+public class EnqueuePass : MonoBehaviour
+{
+    [SerializeField] private BlurSettings settings;    
+    private BlurRenderPass blurRenderPass;
+
+    private void OnEnable()
+    {
+        ...
+        blurRenderPass = new BlurRenderPass(settings);
+        // Subscribe the OnBeginCamera method to the beginCameraRendering event.
+        RenderPipelineManager.beginCameraRendering += OnBeginCamera;
+    }
+
+    private void OnDisable()
+    {
+        RenderPipelineManager.beginCameraRendering -= OnBeginCamera;
+        blurRenderPass.Dispose();
+        ...
+    }
+
+    private void OnBeginCamera(ScriptableRenderContext context, Camera cam)
+    {
+        ...
+        // Use the EnqueuePass method to inject a custom render pass
+        cam.GetUniversalAdditionalCameraData()
+            .scriptableRenderer.EnqueuePass(blurRenderPass);
+    }
+}
+```
+
+## Example
 
 This example demonstrates how to subscribe a method to the `beginCameraRendering` event.
-To follow the steps in this example, create a [new Unity project using the __Universal Project Template__](https://docs.unity3d.com/Packages/[email protected]/manual/creating-a-new-project-with-urp.html).
 
-1. In the Scene, create a Cube. Name it Example Cube.
+To follow the steps in this example, create a [new Unity project using the **Universal Project Template**](../creating-a-new-project-with-urp.md)
+
+1. In the scene, create a Cube. Name it Example Cube.
 2. In your Project, create a C# script. Call it `URPCallbackExample`.
 3. Copy and paste the following code into the script.
     ```C#
@@ -46,14 +82,14 @@ To follow the steps in this example, create a [new Unity project using the __Uni
         }
     }
     ```
-    > **NOTE**: When you subscribe to an event, your handler method (in this example, `WriteLogMessage`) must accept the parameters defined in the event delegate. In this example, the event delegate is `RenderPipeline.BeginCameraRendering`, which expects the following parameters: `<ScriptableRenderContext, Camera>`.
+    > **Note**: When you subscribe to an event, your handler method (in this example, `WriteLogMessage`) must accept the parameters defined in the event delegate. In this example, the event delegate is `RenderPipeline.BeginCameraRendering`, which expects the following parameters: `<ScriptableRenderContext, Camera>`.
 
 4. Attach the `URPCallbackExample` script to Example Cube.
 
-5. Select __Play__. Unity prints the message from the script in the Console window each time Unity raises the `beginCameraRendering` event.
+5. Select **Play**. Unity prints the message from the script in the Console window each time Unity raises the `beginCameraRendering` event.
 
-    ![Unity prints log message in console.](Images/customizing-urp/log-message-in-console.png)
+    ![Unity prints log message in console.](../Images/customizing-urp/log-message-in-console.png)
 
 6. To raise a call to the `OnDisable()` method: In the Play mode, select Example Cube and clear the checkbox next to the script component title. Unity unsubscribes `WriteLogMessage` from the `RenderPipelineManager.beginCameraRendering` event and stops printing the message in the Console window.
 
-    ![Deactivate the script component. Clear the checkbox next to the script component title.](Images/customizing-urp/deactivate-script-component.png)
+    ![Deactivate the script component. Clear the checkbox next to the script component title.](../Images/customizing-urp/deactivate-script-component.png)

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

@@ -1,7 +1,12 @@
-# Customizing URP
+# Custom rendering and post-processing 
 
-This section contains information on how to customize and extend the rendering process in URP.
+Customize and extend the rendering process in the Universal Render Pipeline (URP). URP uses Renderer Features to implement certain effects. URP includes a selection of pre-built Renderer Features and the ability to create customized Renderer Features known as Scriptable Renderer Features.
 
-This section contains the following articles:
+| Page | Description |
+|-|-|
+|[Custom render passes](renderer-features/custom-rendering-passes.md)|Create a custom render pass in a C# script and inject it into the URP frame rendering loop.|
+|[Scriptable Renderer Feature and Scriptable Render Pass API reference](renderer-features/scriptable-renderer-features/scriptable-renderer-feature-reference.md)|Common methods you can use to write Scriptable Renderer Passes and Scriptable Renderer Features.|
 
-* [Using the beginCameraRendering event](using-begincamerarendering.md)
+## Additional resources
+
+- [Pre-built effects (Renderer Features)](urp-renderer-feature.md)

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

@@ -68,7 +68,3 @@ You can set the Background Type in the Camera Inspector to control how a Camera'
 ## What rendering space does URP work in?
 
 By default, URP uses a linear color space while rendering. You can also use a gamma color space, which is non-linear. To do so, toggle it in the Player Settings.
-
-## How do I extend URP with scriptable render pass?
-
-To create a scriptable render pass, you have to create a `ScriptableRendererFeature` script. This is because the scriptable render feature is a container that can have the pass in it. To create the scriptable render feature in the Editor, click on **Asset** > **Create** > **Rendering** > **Universal Render Pipeline** > **Renderer Feature**.

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

@@ -46,7 +46,9 @@ When a GameObject is within multiple reflection probe volumes, maximum two of th
 
 * If the Importance values and the box volumes are the same, Unity determines which two reflection probe volumes contain larger surface areas of a GameObject, and picks the probes of those volumes.
 
-When two reflection probes affect a GameObject, for each pixel, Unity calculates the weight of each probe depending on the distance of this pixel from the faces of the probe box volumes and the values of the **Blend Distance** properties. If the pixel is relatively close to faces of both box volumes and the sum of weights of both probes is less than 1, Unity assigns the remaining weight to the skybox reflection.
+When two reflection probes affect a GameObject, for each pixel, Unity calculates the weight of each probe depending on the distance of this pixel from the faces of the probe box volumes and the values of the **Blend Distance** properties.
+
+If the pixel is relatively close to faces of both box volumes and the sum of weights of both probes is less than 1, Unity assigns the remaining weight to the `_GlossyEnvironmentCubeMap`. This cube map contains the reflection from the lighting source set in the Lighting window under **Environment Lighting** > **Source**. In most cases this source is the skybox.
 
 If the pixel is within both box volumes and farther than the Blend Distance values from faces of both volumes:
 

Packages/com.unity.render-pipelines.universal/Documentation~/lighting/reflection-probes.md

@@ -0,0 +1,8 @@
+# Decal Renderer Feature
+
+A Decal Renderer Features projects specific materials (decals) onto other objects in the scene. Decals interact with the scene's lighting and wrap around meshes.
+
+|Page|Description|
+|-|-|
+|[Decal Renderer Feature](renderer-feature-decal.md)|Use a Decal Renderer Feature in your scene.|
+|[Decal Shader Graph](decal-shader.md)|Project a material as a decal if the material uses a Shader Graph with the Decal Material type.|

Packages/com.unity.render-pipelines.universal/Documentation~/renderer-feature-decal-landing.md

@@ -1,6 +1,6 @@
-# How to create a custom Renderer Feature
+# Example of a complete Scriptable Renderer Feature
 
-This section describes how to create a custom Renderer Feature for a URP Renderer.
+The example workflow on this page implements a custom Renderer Feature that uses [custom Render Passes](./intro-to-scriptable-render-passes.md) to add a blur effect to the camera output.
 
 This section assumes the following:
 

Packages/com.unity.render-pipelines.universal/Documentation~/renderer-features/create-custom-renderer-feature.md

@@ -0,0 +1,32 @@
+# Custom render pass workflow in URP
+
+A custom render pass is a way to change how the Universal Render Pipeline (URP) renders a scene or the objects within a scene. A custom render pass contains your own rendering code, which you add to the rendering pipeline at an injection point.
+
+To add a custom render pass, complete the following tasks:
+
+- [Create the code](#create-code) for a custom render pass using the Scriptable Render Pass API.
+- [Inject the custom render pass](#inject-pass) using the `RenderPipelineManager` API, or by [creating a Scriptable Renderer Feature](#create-srf) that you add to the URP Renderer.
+
+## <a name="create-code"></a>Create the code for a custom render pass
+
+Use the `ScriptableRenderPass` to create the code for a custom render pass.
+
+Refer to [Write a Scriptable Render Pass](write-a-scriptable-render-pass.md) for more information.
+
+## <a name="inject-pass"></a>Inject the custom render pass using the RenderPipelineManager API
+
+Unity raises a [beginCameraRendering](https://docs.unity3d.com/ScriptReference/Rendering.RenderPipelineManager-beginCameraRendering.html) event before it renders each active Camera in every frame. You can subscribe a method to this event, to execute your custom render pass before Unity renders the Camera.
+
+Refer to [Inject a render pass via scripting](../customize/inject-render-pass-via-script.md) for more information.
+
+## <a name="create-srf"></a>Create a Scriptable Renderer Feature
+
+Scriptable Renderer Features control when and how the Scriptable Render Passes apply to a particular renderer or camera, and can also manage multiple Scriptable Render Passes at once.
+
+To create a Scriptable Renderer Feature, you do the following:
+
+* Create a Scriptable Renderer Feature using the API.
+* Add the Scriptable Renderer Feature to the Universal Renderer asset, so it's included in the rendering pipeline.
+* Enqueue your custom render pass in the Scriptable Renderer Feature.
+
+Refer to [Inject a pass using a Scriptable Renderer Feature](scriptable-renderer-features/inject-a-pass-using-a-scriptable-renderer-feature.md) for more information.