Merge pull request #8209 from Unity-Technologies/internal/master

Internal/master

Author: claire-nicholson

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

@@ -9,15 +9,22 @@
   * [Create a simple render loop in a custom render pipeline](srp-creating-simple-render-loop.md)
   * [Execute rendering commands in a custom render pipeline](srp-using-scriptable-render-context.md)
   * [Scriptable Render Pipeline callbacks reference](srp-callbacks-reference.md) 
+* [Creating a custom render pipeline using the render graph system](render-graph-system-landing.md)
+  * [Render graph system](render-graph-system.md)
+  * [Write a render pipeline with render graph](render-graph-writing-a-render-pipeline.md)
+  * [Write a render pass using the render graph system](render-graph-write-render-pass.md)
+  * [Resources in the render graph system](render-graph-resources-landing.md)
+    * [Introduction to resources in the render graph system](render-graph-resources.md)
+    * [Blit using the render graph system](render-graph-blit.md)
+    * [Create a texture in the render graph system](render-graph-create-a-texture.md)
+    * [Import a texture into the render graph system](render-graph-import-a-texture.md)
+    * [Access a texture in a render pass](render-graph-read-write-texture.md)
+  * [Use the CommandBuffer interface in a render graph](render-graph-unsafe-pass.md)
 * Camera components
   * [Free Camera](Free-Camera.md)
   * [Camera Switcher](Camera-Switcher.md)
 * [Render Requests](User-Render-Requests.md)
 * [Render from another camera inside a camera's rendering loop](in-loop-render-requests.md)
-* [Render Graph](render-graph-system.md)
-  * [Benefits of the render graph system](render-graph-benefits.md)
-  * [Render graph fundamentals](render-graph-fundamentals.md)
-  * [Writing a Render Pipeline](render-graph-writing-a-render-pipeline.md)
 * [RTHandle system](rthandle-system.md)
   * [RTHandle fundamentals](rthandle-system-fundamentals.md)
   * [Using the RTHandle system](rthandle-system-using.md)

Packages/com.unity.render-pipelines.core/Documentation~/render-graph-benefits.md

@@ -0,0 +1,58 @@
+# Blit using the render graph system in SRP Core
+
+To blit from one texture to another in the render graph system, use the [`AddBlitPass`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.Rendering.RenderGraphModule.Util.RenderGraphUtils.html#UnityEngine_Rendering_RenderGraphModule_Util_RenderGraphUtils_AddBlitPass_UnityEngine_Rendering_RenderGraphModule_RenderGraph_UnityEngine_Rendering_RenderGraphModule_Util_RenderGraphUtils_BlitMaterialParameters_System_String_System_Boolean_) API. The API generates a render pass automatically, so you don't need to use a method like `AddRasterRenderPass`.
+
+Follow these steps:
+
+1. To create a shader and material that works with a blit render pass, from the main menu select **Assets** > **Create** > **Shader** > **SRP Blit Shader**, then create a material from it.
+
+1. Add `using UnityEngine.Rendering.RenderGraphModule.Util` to your render pass script.
+
+1. In your render pass, create a field for the blit material. For example:
+
+    ```lang-cs
+    public class MyBlitPass : ScriptableRenderPass
+    {
+        Material blitMaterial;
+    }
+    ```
+
+1. Set up the texture to blit from and blit to. For example:
+
+    ```lang-cs
+    TextureHandle sourceTexture = renderGraph.CreateTexture(sourceTextureProperties);
+    TextureHandle destinationTexture = renderGraph.CreateTexture(destinationTextureProperties);
+    ```
+
+1. To set up the material, textures, and shader pass for the blit operation, create a [`RenderGraphUtils.BlitMaterialParameters`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.Rendering.RenderGraphModule.Util.RenderGraphUtils.BlitMaterialParameters.html) object. For example:
+
+    ```lang-cs
+    // Create a BlitMaterialParameters object with the blit material, source texture, destination texture, and shader pass to use.
+    var blitParams = new RenderGraphUtils.BlitMaterialParameters(sourceTexture, destinationTexture, blitMaterial, 0);
+    ```
+
+1. To add a blit pass, call the [`AddBlitPass`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.Rendering.RenderGraphModule.Util.RenderGraphUtils.html#UnityEngine_Rendering_RenderGraphModule_Util_RenderGraphUtils_AddBlitPass_UnityEngine_Rendering_RenderGraphModule_RenderGraph_UnityEngine_Rendering_RenderGraphModule_Util_RenderGraphUtils_BlitMaterialParameters_System_String_System_Boolean_) method with the blit parameters. For example:
+
+    ```lang-cs
+    renderGraph.AddBlitPass(blitParams, "Pass created with AddBlitPass");
+    ```
+
+If you use `AddBlitPass` with a default material, Unity might use the `AddCopyPass` API instead, to optimize the render pass so it accesses the framebuffer from the on-chip memory of the GPU instead of video memory. This process is sometimes called framebuffer fetch. For more information, refer to [`AddCopyPass`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.Rendering.RenderGraphModule.Util.RenderGraphUtils.html#UnityEngine_Rendering_RenderGraphModule_Util_RenderGraphUtils_AddCopyPass_UnityEngine_Rendering_RenderGraphModule_RenderGraph_UnityEngine_Rendering_RenderGraphModule_TextureHandle_UnityEngine_Rendering_RenderGraphModule_TextureHandle_System_String_System_Boolean_) API.
+
+## Customize the render pass
+
+To customize the render pass that the methods generate, for example to change settings or add more resources, call the APIs with the `returnBuilder` parameter set to `true`. The APIs then return the `IBaseRenderGraphBuilder` object that you usually receive as `var builder` from a method like `AddRasterRenderPass`.
+
+For example:
+
+```lang-cs
+using (var builder = renderGraph.AddBlitPass(blitParams, "Pass created with AddBlitPass", returnBuilder: true))
+{
+    // Use the builder variable to customize the render pass here.
+}
+```
+
+## Additional resources
+
+- [The RTHandle System](rthandle-system.md)
+- [Shaders](shaders.md)

Packages/com.unity.render-pipelines.core/Documentation~/render-graph-blit.md

@@ -0,0 +1,48 @@
+# Create a texture in the render graph system in SRP Core
+
+To create a texture in the render graph system, use the `CreateTexture` method of the render graph instance.
+
+When you create a texture inside a render pass, the render graph system handles the creation and disposal of the texture. This process means the texture might not exist in the next frame, and other cameras might not be able to use it. To make sure a texture is available across frames and cameras, [import a texture](render-graph-import-a-texture.md) instead.
+
+When the render graph system optimizes the render pipeline, it might not create a texture if the final frame doesn't use the texture, to reduce the memory and bandwidth the render passes use.
+
+## Create a texture
+
+To create a texture, in follow these steps:
+
+1. Create a [`TextureDesc`](xref:UnityEngine.Rendering.RenderGraphModule.TextureDesc) object with the texture properties you need.
+
+2. Use the [`CreateTexture`](xref:UnityEngine.Rendering.RenderGraphModule.RenderGraph.CreateTexture(UnityEngine.Rendering.RenderGraphModule.TextureDesc@)) method of the render graph instance to create a texture and return a texture handle.
+
+For example, the following creates a texture the same size as the screen.
+
+``` lang-cs
+void RenderCamera(ScriptableRenderContext context, Camera cameraToRender)
+{
+    ...
+
+    var textureProperties = new TextureDesc(Vector2.one)
+    {
+        colorFormat = GraphicsFormat.R8G8B8A8_UNorm,
+        width = cameraToRender.pixelWidth,
+        height = cameraToRender.pixelHeight,
+        clearBuffer = true,
+        clearColor = Color.blue,
+        name = "New render graph Texture",
+    };
+
+    TextureHandle tempTexture = renderGraph.CreateTexture(textureProperties);
+
+    ...
+}
+```
+
+You can then [use the texture](render-graph-read-write-texture.md) in the same custom render pass.
+
+The render graph system manages the lifetime of textures you create with `CreateTexture`, so you don't need to manually release the memory they use when you're finished with them.
+
+## Additional resources
+
+- [Import a texture into the render graph system](render-graph-import-a-texture.md)
+- [Textures](https://docs.unity3d.com/Manual/Textures.html)
+

Packages/com.unity.render-pipelines.core/Documentation~/render-graph-create-a-texture.md

@@ -0,0 +1,60 @@
+# Import a texture into the render graph system in SRP Core
+
+To use a texture from outside the render graph system, or to make sure a texture is available across frames and cameras, import it into the render graph system using the `ImportTexture` API.
+
+For example, you can import the back buffer, or create a texture that points to a texture in your project, such as a [texture asset](https://docs.unity3d.com/Manual/ImportingTextures.html).
+
+The render graph system doesn't manage the lifetime of imported textures, so it can't optimize the render graph by removing unneeded render passes. Where possible, [Create a texture inside the render graph system](render-graph-create-a-texture) instead, so the render graph system manages its lifetime. 
+
+## Import a texture
+
+To import a texture, follow these steps:
+
+1. Create a [RenderTextureDescriptor](https://docs.unity3d.com/ScriptReference/RenderTextureDescriptor.html) object with the texture properties you need.
+
+    For example:
+
+    ``` lang-cs
+    RenderTextureDescriptor textureProperties = new RenderTextureDescriptor(Screen.width, Screen.height, RenderTextureFormat.Default, 0);
+    ```
+
+2. Use the `RenderTextureDescriptor` to instantiate a new render texture. For example:
+
+    ```lang-cs
+    RenderTexture renderTexture = new RenderTexture(textureProperties);
+    ```
+
+3. Create a handle to the render texture. For example:
+
+    ``` lang-cs
+    RTHandle renderTextureHandle = RTHandles.Alloc(renderTexture);
+    ```
+
+4. Import the texture, to convert the `RTHandle` object to a `TextureHandle` object the render graph system can use. 
+
+    For example:
+    
+    ``` lang-cs
+    TextureHandle texture = renderGraph.ImportTexture(renderTextureHandle);
+    ```
+
+You can then use the `TextureHandle` object to [read from or write to the render texture](render-graph-read-write-texture.md).
+
+<a name="dispose-of-a-render-texture"></a>
+### Dispose of the render texture
+
+You must free the memory a render texture uses at the end of a render pass.
+
+For example, you can create the following `Dispose` method:
+
+``` lang-cs
+public void Dispose()
+{
+    renderTexture.Release();
+}
+```
+
+## Additional resources
+
+* [Textures](https://docs.unity3d.com/Manual/Textures.html)
+* [The RTHandle system](rthandle-system.md)

Packages/com.unity.render-pipelines.core/Documentation~/render-graph-fundamentals.md

@@ -0,0 +1,60 @@
+# Use a texture in a render pass in SRP Core
+
+You can use the render graph system API to set a texture as an input or output for a custom render pass, so you can read from or write to it.
+
+## Set a texture as an input
+
+To set a texture as an input for a custom render pass, follow these steps:
+
+1. In your pass data, add a texture handle field to the data your pass uses.
+
+    For example:
+
+    ``` lang-cs
+    // Create the data your pass uses
+    public class MyPassData
+    {
+        // Add a texture handle
+        public TextureHandle textureToUse;
+    }
+    ```
+
+2. Set the texture handle to the texture you want to use. For more information, refer to [Create a texture in the render graph system](render-graph-create-a-texture.md) or [Import a texture into the render graph system](render-graph-import-a-texture.md).
+
+3. Call the [`UseTexture`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.Rendering.RenderGraphModule.IBaseRenderGraphBuilder.html#UnityEngine_Rendering_RenderGraphModule_IBaseRenderGraphBuilder_UseTexture_UnityEngine_Rendering_RenderGraphModule_TextureHandle__UnityEngine_Rendering_RenderGraphModule_AccessFlags_) method to set the texture as an input.
+
+    For example:
+
+    ``` lang-cs
+    builder.UseTexture(passData.textureToUse, AccessFlags.Read);
+    ```
+
+In your `SetRenderFunc` method, you can now use the `TextureHandle` object in the pass data as an input for APIs. 
+
+## Set a texture as the render target
+
+To set a texture as the output for APIs, use the [`SetRenderAttachment`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.Rendering.RenderGraphModule.IRasterRenderGraphBuilder.html#UnityEngine_Rendering_RenderGraphModule_IRasterRenderGraphBuilder_SetRenderAttachment_UnityEngine_Rendering_RenderGraphModule_TextureHandle_System_Int32_UnityEngine_Rendering_RenderGraphModule_AccessFlags_) method. The `SetRenderAttachment` method sets the texture as write-only by default.
+
+For example:
+
+```lang-cs
+builder.SetRenderAttachment(textureHandle, 0);
+```
+
+You don't need to add the texture to your pass data. The render graph system sets up the texture for you automatically before it executes the render pass.
+
+You can't use `UseTexture` and `SetRenderAttachment` on the same texture in a `AddRasterRenderPass` render pass. Refer to [Change the render target during a render pass](#change-the-render-target-during-a-pass) for more information.
+
+<a name="change-the-render-target-during-a-pass"></a>
+## Change the render target during a render pass
+
+You can't change which texture Unity writes to during a render graph system render pass.
+
+You can do either of the following instead:
+
+- Create a second custom render pass, and use `builder.SetRenderAttachment` during the second render pass to change the render target.
+- Use the `UnsafePass` API so you can use the `SetRenderTarget` API in the `SetRenderFunc` method. For more information, refer to [Use the CommandBuffer interface in a render graph](render-graph-unsafe-pass.md).
+
+You can use these methods to read from and write to the same texture, by first copying from the texture to a temporary texture you create, then copying back.
+
+If you blit between several textures with different properties, rendering might be slow because Unity can't merge the blits into a single native render pass. Use the `AddUnsafePass` API and the `SetRenderTarget()` method instead.