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

Internal/master

Author: claire-nicholson

Packages/com.unity.render-pipelines.core/Documentation~/Images/ExampleOutputTexture.png

@@ -35,4 +35,14 @@
 * [Look Dev](Look-Dev.md)
   * [Environment Library](Look-Dev-Environment-Library.md)
 * [Rendering Debugger](Rendering-Debugger.md)
-* [Light Anchor](view-lighting-tool.md)
+* [Light Anchor](view-lighting-tool.md)
+* [Unified Raytracing API](UnifiedRayTracing/unified-ray-tracing-api.md)
+  * [Get started with ray tracing](UnifiedRayTracing/get-started.md)
+  * [Ray tracing workflow](UnifiedRayTracing/workflow.md)
+  * [Create the ray tracing context](UnifiedRayTracing/create-ray-tracing-context.md)
+  * [Create an acceleration structure](UnifiedRayTracing/create-acceleration-structure.md)
+  * [Create a unified ray tracing shader](UnifiedRayTracing/create-shader.md)
+  * [Write your ray tracing code](UnifiedRayTracing/write-shader.md)
+  * [Execute your ray tracing code](UnifiedRayTracing/execute-shader.md)
+  * [Sample code: Tracing camera rays](UnifiedRayTracing/trace-camera-rays-full-sample.md)
+  * [Unified ray tracing shader code reference](UnifiedRayTracing/shader-code-reference.md)

Packages/com.unity.render-pipelines.core/Documentation~/Images/RayTracingContext.jpg

@@ -0,0 +1,51 @@
+# Create an acceleration structure
+[`IRayTracingAccelStruct`](xref:UnityEngine.Rendering.UnifiedRayTracing.IRayTracingAccelStruct) is the data structure used to represent a collection of instances and geometries that are used for GPU ray tracing.
+
+Create an acceleration structure with the following code:
+```C# 
+var options = new AccelerationStructureOptions();
+IRayTracingAccelStruct rtAccelStruct = rtContext.CreateAccelerationStructure(options);
+```
+
+## Build options
+[`AccelerationStructureOptions`](xref:UnityEngine.Rendering.UnifiedRayTracing.AccelerationStructureOptions) allows you to configure the build algorithm. The trade-off is as follows: A faster build results in worse ray tracing performance, and conversely, a slower build can improve ray tracing performance.
+
+The following fields can be configured:
+
+|Field|Description|
+|-|-|
+|`buildFlags`|Adjust the buildFlags to prioritize either faster construction of the acceleration structure or faster ray tracing.|
+|`useCPUBuild` (Compute backend)|When set to true, Unity builds the acceleration structure on the CPU instead of the GPU. This option has no effect when using the `Hardware` backend. CPU-based builds use a more advanced algorithm, resulting in a higher-quality acceleration structure, which enhances overall ray tracing performance.|
+
+The following example demonstrates how to get the best ray tracing performance. These options make the acceleration structure longer to build, however.
+```HLSL 
+var options = new AccelerationStructureOptions() {
+    buildFlags = BuildFlags.PreferFastTrace,
+    useCPUBuild = true
+}
+```
+
+## Populate the acceleration structure
+Unlike [`RayTracingAccelerationStructure`](xref:UnityEngine.Rendering.RayTracingAccelerationStructure), there is no support for automatic synchronization between the acceleration structure's instances and the scene instances. You need to add them manually, for example:
+```C#
+var instanceDesc = new MeshInstanceDesc(mesh, 0 /*subMeshIndex*/);
+instanceDesc.localToWorldMatrix = /* desired transform */;
+rtAccelStruct.AddInstance(instanceDesc);
+```
+
+To trace rays against all the Mesh-based GameObjects in your scene, add them to the [`IRayTracingAccelStruct`](xref:UnityEngine.Rendering.UnifiedRayTracing.IRayTracingAccelStruct). For example:
+```C# 
+var meshRenderers = UnityEngine.Object.FindObjectsByType<MeshRenderer>(FindObjectsSortMode.None);
+foreach (var renderer in meshRenderers)
+{
+    var mesh = renderer.GetComponent<MeshFilter>().sharedMesh;
+    int subMeshCount = mesh.subMeshCount;
+
+    for (int i = 0; i < subMeshCount; ++i)
+    {
+        var instanceDesc = new MeshInstanceDesc(mesh, i);
+        instanceDesc.localToWorldMatrix = renderer.transform.localToWorldMatrix;
+        rtAccelStruct.AddInstance(instanceDesc);
+    }
+}
+```

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

@@ -0,0 +1,57 @@
+# Create the ray tracing context
+
+The [`RayTracingContext`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingContext) serves as the initial API entry point, allowing the creation of all essential objects required to execute ray tracing code.
+
+Follow these steps:
+1. Load the ray tracing resources.
+2. Create the context.
+
+## Load the ray tracing resources
+The [`RayTracingContext`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingContext) needs a few utility shaders that the [`RayTracingResources`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingResources) object supplies. You can load these resources in several different ways.
+
+If your project uses SRP (Scriptable Render Pipeline), load the resources via [`RayTracingResources.LoadFromRenderPipelineResources`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingContext.LoadFromRenderPipelineResources()). This always works in the Editor.
+```C#
+var rtResources = new RayTracingResources();
+bool result = rtResources.LoadFromRenderPipelineResources();
+```
+You can instruct Unity to also include the resources in Player builds:
+```C#
+using UnityEngine.Rendering;
+using UnityEngine.Rendering.UnifiedRayTracing;
+
+#if UNITY_EDITOR
+class MyURTStripping: IRenderPipelineGraphicsSettingsStripper<RayTracingRenderPipelineResources>
+{
+    public bool active => true;
+    public bool CanRemoveSettings(RayTracingRenderPipelineResources settings) => false;
+}
+#endif
+```
+
+You can also load the resources via the Asset Database:
+```C# 
+var rtResources = new RayTracingResources();
+rtResources.Load();
+```
+**Note:** Since the Player doesn't give access to the Asset Database, this method only works in the Editor.
+
+To load the [`RayTracingResources`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingResources) in the Player, you can also build the **unifiedraytracing** AssetBundle. For more information about how to build and load AssetBundles, refer to [AssetBundles](xref:AssetBundlesIntro).
+```C# 
+var rtResources = new RayTracingResources();
+
+// Load the AssetBundle 
+var asssetBundle = AssetBundle.LoadFromFile("Assets/pathToYourBuiltAssetBundles/unifiedraytracing");
+
+// Load the RayTracingResources
+rtResources.LoadFromAssetBundle(asssetBundle);
+```
+
+## Create the context
+Once the [`RayTracingResources`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingResources) are loaded, use them to create the [`RayTracingContext`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingContext).
+```C# 
+// Choose a backend
+var backend = RayTracingContext.IsBackendSupported(RayTracingBackend.Hardware) ? RayTracingBackend.Hardware : RayTracingBackend.Compute;
+
+// Create the context
+var context = new RayTracingContext(backend, rtResources);
+```

Packages/com.unity.render-pipelines.core/Documentation~/UnifiedRayTracing/create-acceleration-structure.md

@@ -0,0 +1,53 @@
+# Create a unified ray tracing shader
+
+Depending on the backend you choose in the [`RayTracingContext`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingContext), write your ray tracing code in either a `.raytrace` or a `.compute` shader.
+
+To create both a `.raytrace` shader and a `.compute` shader, write your shader code in a unified ray tracing shader (`.urtshader`).
+
+To create a shader, follow these steps:
+
+1. Create the shader asset file.
+2. Load the shader.
+
+## Create the shader asset file
+To create a unified ray tracing shader:
+
+1. Launch the Unity Editor.
+
+1. In the **Project** window, open the **Assets** folder.
+
+1. Open or create the folder in which you want to create your shader.
+
+1. Open the context menu (right-click) and select **Create** > **Shader** > **Unified Ray Tracing Shader**.
+
+1. Enter a name for the shader.
+ 
+Ray tracing occurs in the `RayGenExecute` function. You can edit the example code snippet.
+
+For more information about writing a ray tracing shader, refer to [Write your shader code](write-shader.md).
+
+## Load the shader
+To load the `.urtshader` file in the Editor, use the following code snippet:
+```C# 
+IRayTracingShader shader = rtContext.LoadRayTracingShader("Assets/yourShader.urtshader");
+```
+
+To load the shader in the Player, add the `.urtshader` shader to an <xref:UnityEngine.AssetBundle> then load it with the following:
+```C# 
+// Load the AssetBundle 
+var asssetBundle = AssetBundle.LoadFromFile("Assets/pathToYourBuiltAssetBundles/yourAssetBundle");
+
+// Load the shader
+IRayTracingShader shader = rtContext.LoadRayTracingShaderFromAssetBundle(asssetBundle, "Assets/yourShader.urtshader");
+```
+
+To have more control, load the underlying Compute or Ray Tracing shader asset yourself and pass it to [`RayTracingContext.CreateRayTracingShader`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingContext.CreateRayTracingShader(UnityEngine.Object)). 
+
+[`RayTracingContext.LoadRayTracingShaderFromAssetBundle`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingContext.LoadRayTracingShaderFromAssetBundle(UnityEngine.AssetBundle,System.String)) is a convenience function that performs the following operations:
+```C# 
+public IRayTracingShader LoadRayTracingShaderFromAssetBundle(AssetBundle assetBundle, string name)
+{
+    Object asset = assetBundle.LoadAsset(name, BackendHelpers.GetTypeOfShader(BackendType));
+    return CreateRayTracingShader(asset);
+}
+```

Packages/com.unity.render-pipelines.core/Documentation~/UnifiedRayTracing/create-ray-tracing-context.md

@@ -0,0 +1,55 @@
+# Execute your ray tracing code
+This section assumes you have [a shader](create-shader.md) containing your ray tracing logic and an [acceleration structure](create-acceleration-structure.md) representing the geometry that the rays will intersect.
+
+To execute your ray tracing shader on the GPU:
+1. Build the acceleration structure.
+2. Bind resources to the shader.
+3. Dispatch the shader.
+
+## Build the acceleration structure
+You must build the acceleration structure after you create it and every time you modify it. For example:
+```C#
+IRayTracingAccelStruct rtAccelStruct = /* your acceleration structure */;
+var cmd = new CommandBuffer();
+
+// A scratch buffer is required to build the acceleration structure, this helper function allocates one with the required size.
+GraphicsBuffer buildScratchBuffer = RayTracingHelper.CreateScratchBufferForBuild(rtAccelStruct);
+
+// Build the ray tracing acceleration structure
+rtAccelStruct.Build(cmd, buildScratchBuffer);
+```
+
+## Bind resources to the shader
+You must bind the acceleration structure and any additional GPU resources declared in your shader, such as constants, buffers, and textures. For example:
+```C#
+IRayTracingShader rtShader = /* your shader */;
+
+// Bind the acceleration structure. It is declared in the shader as: UNIFIED_RT_DECLARE_ACCEL_STRUCT(_YourAccelStruct);
+rtShader.SetAccelerationStructure(cmd, "_YourAccelStruct", rtAccelStruct);
+
+// Bind the other GPU resources (constants/uniforms, buffers and textures)
+rtShader.SetIntParam(cmd, Shader.PropertyToID("_YourInteger"), 5);
+```
+
+## Dispatch the shader
+To make the GPU run your ray tracing shader, call the [`Dispatch`](xref:UnityEngine.Rendering.UnifiedRayTracing.IRayTracingShader.Dispatch(UnityEngine.Rendering.CommandBuffer,UnityEngine.GraphicsBuffer,System.UInt32,System.UInt32,System.UInt32)) method. For example:
+```C#
+const int threadCountX = 256, threadCountY = 256, threadCountZ = 1;
+
+// A scratch buffer is required to trace rays, this helper function allocates one with the required size.
+GraphicsBuffer traceScratchBuffer = RayTracingHelper.CreateScratchBufferForTrace(rtShader, threadCountX, threadCountY, threadCountZ);
+
+// Dispatch rays. Workgrid dimensions are supplied in threads, not workgroups
+rtShader.Dispatch(cmd, traceScratchBuffer, threadCountX, threadCountY, threadCountZ);
+
+// Execute the command buffer to effectively run all the previously registered commands.
+Graphics.ExecuteCommandBuffer(cmd);
+```
+
+**Note:**  If its size satisfies the requirements for both operations, you can use the same scratch buffer for both the build and trace steps.
+
+
+
+
+
+

Packages/com.unity.render-pipelines.core/Documentation~/UnifiedRayTracing/create-shader.md

@@ -0,0 +1,28 @@
+# Get started with ray tracing
+The `UnifiedRayTracing` API enables you to write ray tracing code that executes on a wide range of GPUs. Unlike the [`RayTracingAccelerationStructure`](xref:UnityEngine.Rendering.RayTracingAccelerationStructure) API,
+its key advantage is that it is able to operate without requiring hardware ray tracing support. It achieves this by offering multiple backends that can be dynamically selected based on the GPU’s capabilities.
+
+## Backends
+The following backends are available:
+- `Hardware`: Requires a GPU that supports hardware-accelerated ray tracing. This backend uses the [`RayTracingAccelerationStructure`](xref:UnityEngine.Rendering.RayTracingAccelerationStructure) API.
+- `Compute` : Software implementation of ray tracing that works only on GPUs that support compute shaders.
+
+By abstracting these different implementations behind a unified interface, the API allows you to write your ray tracing code once, and have it automatically adapt to the appropriate backend.
+
+## Main concepts
+The API entry point is the [`RayTracingContext`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingContext) which is initialized for a specific backend.
+
+The [`RayTracingContext`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingContext) enables you to create the 2 essential objects you need to perform ray tracing:
+- an acceleration structure ([`IRayTracingAccelStruct`]((xref:UnityEngine.Rendering.UnifiedRayTracing.IRayTracingAccelStruct))) which represents the geometry to trace rays against.
+- a shader ([`IRayTracingShader`]((xref:UnityEngine.Rendering.UnifiedRayTracing.IRayTracingShader))) which contains your ray tracing code that will run on the GPU.
+
+![RayTracingContext class features](../Images/RayTracingContext.jpg)
+
+For more information, refer to [Using the API workflow](workflow.md).
+
+## Limitations
+In order to accomodate both hardware-accelerated and non-accelerated GPUs, the API is more constrained than Unity's [`RayTracingAccelerationStructure` API](xref:UnityEngine.Rendering.RayTracingAccelerationStructure). 
+- The API doesn't support any automatic scene updates. You must explicitly call [`IRayTracingAccelStruct.AddInstance`](xref:UnityEngine.Rendering.UnifiedRayTracing.IRayTracingAccelStruct.AddInstance(UnityEngine.Rendering.UnifiedRayTracing.MeshInstanceDesc)) or 
+[`IRayTracingAccelStruct.RemoveInstance`](xref:UnityEngine.Rendering.UnifiedRayTracing.IRayTracingAccelStruct.RemoveInstance(System.Int32)) to update the acceleration structure.
+- The API supports only ray tracing with mesh geometries.
+- Once a hit is found, the `TraceRay` function returns immediately with the hit information. You need to write the shading code in the ray generation shader (`.urtshader`).

Packages/com.unity.render-pipelines.core/Documentation~/UnifiedRayTracing/execute-shader.md

@@ -0,0 +1,74 @@
+# Unified ray tracing shader code reference
+This section presents the different functions and structs provided by the API for tracing rays in a shader.
+
+All types are defined inside the `UnifiedRT` namespace. In your code, you need to prefix them with ```UnifiedRT::```. Alternatively, you can add ```using namespace UnifiedRT;``` after your `TraceRayAndQueryHit.hlsl` include statement.
+
+## function TraceRayClosestHit
+```HLSL 
+Hit TraceRayClosestHit(DispatchInfo dispatchInfo, RayTracingAccelStruct accelStruct, uint instanceMask, Ray ray, uint rayFlags)
+ ```
+Searches for intersections between a ray and an acceleration structure. It returns hit information about the closest triangle encountered along the ray. 
+### Parameters
+|Type|Name|Description|
+|-|-|-|
+|[`DispatchInfo`](#struct-dispatchinfo)|*dispatchInfo*|The dispatch info. Must be the value that is passed by `RayGenExecute`.|
+|`RayTracingAccelStruct`|*accelStruct*|The acceleration structure to test the ray against.|
+|`uint`|*instanceMask*|The lower 8 bits of this mask are used to include geometry instances based on the instance mask that was set in `MeshInstanceDesc` for each instance.|
+|[`Ray`](#struct-ray)|*ray*|Describes the ray segment that is intersected against the acceleration structure.|
+|`uint`|*rayFlags*|Flags that filter out the triangles that participate in the intersection test. Can be one of the following: <ul><li>kRayFlagNone</li><li>kRayFlagCullBackFacingTriangles</li><li>kRayFlagCullFrontFacingTriangles</li> </ul>|
+### Returns
+[`Hit`](#struct-hit) containing geometry information about the hit triangle. When no primitive has intersected with the ray, `hit.IsValid()` returns false.
+
+## function TraceRayAnyHit
+```HLSL 
+bool TraceRayAnyHit(DispatchInfo dispatchInfo, RayTracingAccelStruct accelStruct, uint instanceMask, Ray ray, uint rayFlags)
+```
+Searches for any intersection between a ray and an acceleration structure. The search ends as soon as a valid triangle hit is found. This function can typically be used to trace shadow rays or perform occlusion queries.  
+### Parameters
+|Type|Name|Description|
+|-|-|-|
+|[`DispatchInfo`](#struct-dispatchinfo)|*dispatchInfo*|The dispatch info. Must be the value that is passed by `RayGenExecute`.|
+|`RayTracingAccelStruct`|*accelStruct*|The acceleration structure to test the ray against.|
+|`uint`|*instanceMask*|The lower 8 bits of this mask are used to include geometry instances based on the instance mask that was set in `MeshInstanceDesc` for each instance.|
+|[`Ray`](#struct-ray)|*ray*|Describes the ray segment that is intersected against the acceleration structure.|
+|`uint`|*rayFlags*|Flags that filter out the triangles that participate in the intersection test. Can be one of the following: <ul><li>kRayFlagNone</li><li>kRayFlagCullBackFacingTriangles</li><li>kRayFlagCullFrontFacingTriangles</li> </ul>|
+### Returns
+A boolean that is true if any primitive was hit by the ray.
+
+## struct Ray
+Describes a ray.
+The `tMin` and `tMax` fields define the segment of the ray to be tested against the acceleration structures's primitives.
+Mathematically, the ray consists of all the points defined as `P = ray.origin + t * ray.direction`, where `ray.tMin ≤ t ≤ ray.tMax`.
+### Fields
+|Type|Name|Description|
+|-|-|-|
+|`float3`|*origin*|The ray's origin.|
+|`float3`|*direction*|The ray's direction.|
+|`float`|*tMin*|The ray's starting point.|
+|`float`|*tMax*|The ray's endpoint.|
+
+## struct DispatchInfo
+Provides information about the current thread that is invoked.
+### Fields
+|Type|Name|Description|
+|-|-|-|
+|`uint3`|*dispatchThreadID*|Same semantic as `SV_DispatchThreadID`.|
+|`uint`|*localThreadIndex*|Same semantic as `SV_GroupIndex`.|
+|`uint3`|*dispatchDimensionsInThreads*|Total numbers of threads dispatched in the X, Y, and Z workgrid directions.|
+|`uint`|*globalThreadIndex*|Global thread index that is unique within the workgrid.|
+
+## struct Hit
+Describes a Hit.
+### Fields
+|Type|Name|Description|
+|-|-|-|
+|`uint`|*instanceID*|Matches the `instanceID` supplied from C# in `MeshInstanceDesc.instanceID`.|
+|`uint`|*primitiveIndex*|Index of the hit triangle in its source Mesh.|
+|`float2`|*uvBarycentrics*|Barycentric coordinates of the hit triangle.|
+|`float`|*hitDistance*|Defines the hit position: `hitPos = ray.origin + ray.direction * hit.hitDistance`.|
+|`bool`|*isFrontFace*|Indicates whether the hit triangle is front-facing or back-facing.|
+### Methods
+```HLSL 
+bool IsValid();
+```
+Returns true when a hit has been found. When a hit is invalid `hit.instanceID` is equal to `~0` and the other fields are undefined.