Merge pull request #8295 from Unity-Technologies/internal/6000.3/staging

Internal/6000.3/staging

Author: rolandk-unity

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

@@ -9,7 +9,7 @@ Follow these steps:
 ## 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.
+If your project uses SRP (Scriptable Render Pipeline), load the resources via [`RayTracingResources.LoadFromRenderPipelineResources`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingResources.LoadFromRenderPipelineResources()). This always works in the Editor.
 ```C#
 var rtResources = new RayTracingResources();
 bool result = rtResources.LoadFromRenderPipelineResources();
@@ -49,9 +49,12 @@ 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;
+var context = new RayTracingContext(rtResources);
+```
+
+By default, Unity checks if the device supports hardware ray tracing, and selects either hardware ray tracing or compute shaders. To manually select the backend, pass in a `RayTracingBackend`. For example:
 
-// Create the context
+```C# 
+var backend = RayTracingBackend.Compute;
 var context = new RayTracingContext(backend, rtResources);
 ```

Packages/com.unity.render-pipelines.core/Documentation~/UnifiedRayTracing/release-resources.md

@@ -0,0 +1,26 @@
+# Release your ray tracing objects
+
+You must free up the memory your ray tracing objects use after you finish with them.
+
+Dispose of the following:
+
+- Scratch buffers. Use [`GraphicsBuffer.Dispose`](xref:UnityEngine.GraphicsBuffer.Dispose()) after you've executed the final command buffer.
+- Ray tracing acceleration structures. Use [`IRayTracingAccelStruct.Dispose`](xref:UnityEngine.Rendering.UnifiedRayTracing.IRayTracingAccelStruct.Dispose()) after you've executed the final command buffer.
+- Ray tracing context. Use [`RayTracingContext.Dispose`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingContext.Dispose()) after you dispose of all its acceleration structures.
+
+**Note**: Unity automatically disposes of [`RayTracingResources`](xref:UnityEngine.Rendering.UnifiedRayTracing.RayTracingResources) and [`IRayTracingShader`](xref:UnityEngine.Rendering.UnifiedRayTracing.IRayTracingShader).
+
+For example:
+
+```C# 
+RayTracingContext rtContext = new RayTracingContext(rtResources);
+IRayTracingShader rtShader = rtContext.LoadRayTracingShader("Assets/yourShader.urtshader");
+IRayTracingAccelStruct rtAccelStruct = rtContext.CreateAccelerationStructure(new AccelerationStructureOptions());
+GraphicsBuffer rtScratchBuffer = RayTracingHelper.CreateScratchBufferForBuild(rtAccelStruct);
+
+// ... create and dispatch your ray tracing command buffers ...
+
+rtScratchBuffer.Dispose();
+rtAccelStruct.Dispose();
+rtContext.Dispose();
+```

Packages/com.unity.render-pipelines.core/Documentation~/UnifiedRayTracing/unified-ray-tracing-api.md

@@ -12,4 +12,4 @@ The `UnifiedRayTracing` API enables you to write ray tracing code that can execu
 |[Execute your ray tracing code](execute-shader.md)|How to execute your ray tracing shader.|
 |[Sample code](trace-camera-rays-full-sample.md)|Complete code example showcasing tracing rays from the scene's camera.|
 |[Unified ray tracing shader code reference](shader-code-reference.md)|API reference for the unified ray tracing shader code.|
-
+|[Release your ray tracing objects](release-resources.md)|Learn how to release your ray tracing resources.|

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

@@ -5,6 +5,7 @@ To use the API to trace rays in Unity, follow these steps:
 3. Create a shader.
 4. Build your acceleration structure.
 5. Execute your shader.
+6. Dispose of your objects.
 
 ## Create the ray tracing context
 
@@ -53,3 +54,5 @@ rtShader.Dispatch(cmd, traceScratchBuffer, threadCountX, threadCountY, threadCou
 
 For more information, refer to [Execute your ray tracing code](execute-shader.md).
 
+## Dispose of your objects
+For more information, refer to [Release your ray tracing objects](release-resources.md).

Packages/com.unity.render-pipelines.core/Editor/Tools/MaterialUpgrader/MaterialUpgrader.Utils.cs

@@ -12,6 +12,8 @@ namespace UnityEditor.Rendering
     /// </summary>
     public partial class MaterialUpgrader
     {
+        internal static string k_DialogKey = $"{nameof(UnityEditor)}.{nameof(Rendering)}.{nameof(MaterialUpgrader)}.ConfirmMaterialConversion";
+
         #region Internal API
         /// <summary>
         /// Represents an entry describing material properties
@@ -344,15 +346,15 @@ static void PerformUpgrade(List<MaterialUpgradeEntry> materialUpgrades, List<Mat
 
             bool CanPerformUpgrade()
             {
-                const string title = "Material Upgrader";
-                const string message = "This operation will overwrite existing materials in your project.\n\nPlease ensure you have a backup before proceeding.";
+                const string title = "Confirm Material Conversion";
+                const string message = "This action will modify materials and cannot be easily undone. It is strongly recommended to have a backup or use version control before continuing.";
                 const string proceed = "Proceed";
                 const string cancel = "Cancel";
 
                 if (Application.isBatchMode)
                     return true;
 
-                return EditorUtility.DisplayDialog(title, message, proceed, cancel);
+                return EditorUtility.DisplayDialog(title, message, proceed, cancel, DialogOptOutDecisionType.ForThisMachine, k_DialogKey);
             }
 
             if (CanPerformUpgrade())

Packages/com.unity.render-pipelines.core/Editor/Tools/MaterialUpgrader/MaterialUpgraderEditMenus.cs

@@ -0,0 +1,52 @@
+using System.Collections.Generic;
+using UnityEngine;
+using UnityEngine.Rendering;
+
+namespace UnityEditor.Rendering
+{
+    class MaterialUpgraderEditMenus
+    {
+        private static readonly List<MaterialUpgrader> s_Empty = new List<MaterialUpgrader>();
+
+        public static List<MaterialUpgrader> GetCurrentSRPUpgraders()
+        {
+            if (!GraphicsSettings.isScriptableRenderPipelineEnabled)
+                return s_Empty;
+
+            return MaterialUpgrader.FetchAllUpgradersForPipeline(GraphicsSettings.currentRenderPipelineAssetType);
+        }
+
+        [MenuItem("Edit/Rendering/Materials/Convert All Built-In Materials to Current SRP", true)]
+        internal static bool UpgradeMaterialsProjectValidate()
+        {
+            return GraphicsSettings.isScriptableRenderPipelineEnabled;
+        }
+
+        [MenuItem("Edit/Rendering/Materials/Convert All Built-In Materials to Current SRP", priority = CoreUtils.Priorities.editMenuPriority + 1)]
+        internal static void UpgradeMaterialsProject()
+        {
+            MaterialUpgrader.UpgradeProjectFolder(GetCurrentSRPUpgraders(), "Upgrade to SRP Material");
+        }
+
+        [MenuItem("Edit/Rendering/Materials/Convert Selected Built-In Materials to Current SRP", true)]
+        internal static bool UpgradeMaterialsSelectionValidate()
+        {
+            if (Selection.objects.Length == 0 || !GraphicsSettings.isScriptableRenderPipelineEnabled)
+                return false;
+
+            foreach (var obj in Selection.objects)
+            {
+                if (obj is not Material)
+                    return false;
+            }
+
+            return true;
+        }
+
+        [MenuItem("Edit/Rendering/Materials/Convert Selected Built-In Materials to Current SRP", priority = CoreUtils.Priorities.editMenuPriority + 2)]
+        internal static void UpgradeMaterialsSelection()
+        {
+            MaterialUpgrader.UpgradeSelection(GetCurrentSRPUpgraders(), "Upgrade to SRP Material");
+        }
+    }
+}

Packages/com.unity.render-pipelines.core/Editor/Tools/MaterialUpgrader/MaterialUpgraderEditMenus.cs.meta

@@ -332,7 +332,9 @@ static public GraphicsBuffer CreateScratchBufferForTrace(IRayTracingShader shade
         /// Resizes a scratch buffer if its size doesn't fit the requirement of <see cref="IRayTracingShader.Dispatch"/>.
         /// </summary>
         /// <remarks>
-        /// The resize is accomplished by disposing of the GraphicsBuffer and instanciating a new one at the proper size.
+        /// Unity resizes the buffer by disposing of the `GraphicsBuffer` and instantiating a new one with the proper size.
+        /// **Important:** If you reference the current <paramref name="scratchBuffer"/> in a command buffer, you must 
+        /// only call this method after you submit the command buffer. See <see cref="Graphics.ExecuteCommandBuffer"/> or <see cref="ScriptableRenderContext.ExecuteCommandBuffer"/>.
         /// </remarks>
         /// <param name="shader">The shader that will be passed to <see cref="IRayTracingShader.Dispatch"/>.</param>
         /// <param name="dispatchWidth">Number of threads in the X dimension that will be passed to <see cref="IRayTracingShader.Dispatch"/>.</param>
@@ -362,7 +364,9 @@ static public void ResizeScratchBufferForTrace(
         /// Resizes a scratch buffer if its size doesn't fit the requirement of <see cref="IRayTracingAccelStruct.Build"/>.
         /// </summary>
         /// <remarks>
-        /// The resize is accomplished by disposing of the GraphicsBuffer and instanciating a new one at the proper size.
+        /// Unity resizes the buffer by disposing of the `GraphicsBuffer` and instantiating a new one with the proper size.
+        /// **Important:** If you reference the current <paramref name="scratchBuffer"/> in a command buffer, you must 
+        /// only call this method after you submit the command buffer. See <see cref="Graphics.ExecuteCommandBuffer"/> or <see cref="ScriptableRenderContext.ExecuteCommandBuffer"/>.
         /// </remarks>
         /// <param name="accelStruct">The acceleration structure that will be passed to <see cref="IRayTracingAccelStruct.Build"/>.</param>
         /// <param name="scratchBuffer">The scratch buffer.</param>

Packages/com.unity.render-pipelines.core/Runtime/UnifiedRayTracing/RayTracingContext.cs

@@ -5,6 +5,12 @@
 
 namespace UnityEngine.Rendering.UnifiedRayTracing
 {
+    /// <summary>
+    /// Resource class that handles the serialization of UnifiedRayTracing's utility shaders in projects using a Scriptable Render Pipeline.
+    /// </summary>
+    /// <remarks>
+    /// This class is used internally by <see cref="RayTracingResources.LoadFromRenderPipelineResources"/>
+    /// </remarks>
     [Scripting.APIUpdating.MovedFrom(
         autoUpdateAPI: true,
         sourceNamespace: "UnityEngine.Rendering.UnifiedRayTracing",
@@ -13,10 +19,13 @@ namespace UnityEngine.Rendering.UnifiedRayTracing
     [Serializable]
     [SupportedOnRenderPipeline()]
     [Categorization.CategoryInfo(Name = "R: Unified Ray Tracing", Order = 1000), HideInInspector]
-    internal class RayTracingRenderPipelineResources : IRenderPipelineResources
+    public sealed class RayTracingRenderPipelineResources : IRenderPipelineResources
     {
         [SerializeField, HideInInspector] int m_Version = 1;
 
+        /// <summary>
+        /// The version number of the resources container.
+        /// </summary>
         public int version
         {
             get => m_Version;
@@ -49,54 +58,84 @@ public int version
         [SerializeField, ResourcePath("Runtime/UnifiedRayTracing/Compute/RadeonRays/kernels/scatter.compute")]
         ComputeShader m_Scatter;
 
+        /// <summary>
+        /// Compute shader for geometry pool operations.
+        /// </summary>
         public ComputeShader GeometryPoolKernels
         {
             get => m_GeometryPoolKernels;
             set => this.SetValueAndNotify(ref m_GeometryPoolKernels, value, nameof(m_GeometryPoolKernels));
         }
 
+        /// <summary>
+        /// Compute shader for buffer copy operations.
+        /// </summary>
         public ComputeShader CopyBuffer
         {
             get => m_CopyBuffer;
             set => this.SetValueAndNotify(ref m_CopyBuffer, value, nameof(m_CopyBuffer));
         }
 
+        /// <summary>
+        /// Compute shader for copying vertex position data.
+        /// </summary>
         public ComputeShader CopyPositions
         {
             get => m_CopyPositions;
             set => this.SetValueAndNotify(ref m_CopyPositions, value, nameof(m_CopyPositions));
         }
 
+        /// <summary>
+        /// Compute shader for radix sort operations.
+        /// </summary>
         public ComputeShader BitHistogram
         {
             get => m_BitHistogram;
             set => this.SetValueAndNotify(ref m_BitHistogram, value, nameof(m_BitHistogram));
         }
 
+        /// <summary>
+        /// Compute shader for prefix sum operations.
+        /// </summary>
         public ComputeShader BlockReducePart
         {
             get => m_BlockReducePart;
             set => this.SetValueAndNotify(ref m_BlockReducePart, value, nameof(m_BlockReducePart));
         }
 
+        /// <summary>
+        /// Compute shader for prefix sum operations.
+        /// </summary>
         public ComputeShader BlockScan
         {
             get => m_BlockScan;
             set => this.SetValueAndNotify(ref m_BlockScan, value, nameof(m_BlockScan));
         }
 
+        /// <summary>
+        /// Compute shader for building a BVH.
+        /// </summary>
         public ComputeShader BuildHlbvh
         {
             get => m_BuildHlbvh;
             set => this.SetValueAndNotify(ref m_BuildHlbvh, value, nameof(m_BuildHlbvh));
         }
 
+        /// <summary>
+        /// Compute shader for BVH restructuring.
+        /// </summary>
+        /// <remarks>
+        /// Used to optimize the BVH structure after initial construction.
+        /// </remarks>
         public ComputeShader RestructureBvh
         {
             get => m_RestructureBvh;
             set => this.SetValueAndNotify(ref m_RestructureBvh, value, nameof(m_RestructureBvh));
         }
 
+        /// <summary>
+        /// Compute shader for radix sort operations.
+        /// </summary>
         public ComputeShader Scatter
         {
             get => m_Scatter;
@@ -107,17 +146,62 @@ public ComputeShader Scatter
     /// <summary>
     /// Utility shaders needed by a <see cref="RayTracingContext"/> to operate.
     /// </summary>
+    /// <remarks>
+    /// This class holds compute shaders required for unified ray tracing operations,
+    /// including geometry pool management and BVH construction kernels.
+    /// </remarks>
     public class RayTracingResources
     {
-        internal ComputeShader geometryPoolKernels { get; set; }
-        internal ComputeShader copyBuffer { get; set; }
-        internal ComputeShader copyPositions { get; set; }
-        internal ComputeShader bitHistogram { get; set; }
-        internal ComputeShader blockReducePart { get; set; }
-        internal ComputeShader blockScan { get; set; }
-        internal ComputeShader buildHlbvh { get; set; }
-        internal ComputeShader restructureBvh { get; set; }
-        internal ComputeShader scatter { get; set; }
+        /// <summary>
+        /// Compute shader for geometry pool operations.
+        /// </summary>
+        public ComputeShader geometryPoolKernels { get; set; }
+
+        /// <summary>
+        /// Compute shader for buffer copy operations.
+        /// </summary>
+        public ComputeShader copyBuffer { get; set; }
+
+        /// <summary>
+        /// Compute shader for copying vertex position data.
+        /// </summary>
+        public ComputeShader copyPositions { get; set; }
+
+        /// <summary>
+        /// Compute shader for radix sort operations.
+        /// </summary>
+        public ComputeShader bitHistogram { get; set; }
+
+        /// <summary>
+        /// Compute shader for radix sort operations.
+        /// </summary>
+        public ComputeShader scatter { get; set; }
+
+        /// <summary>
+        /// Compute shader for prefix sum operations.
+        /// </summary>
+        public ComputeShader blockReducePart { get; set; }
+
+        /// <summary>
+        /// Compute shader for prefix sum operations.
+        /// </summary>
+        public ComputeShader blockScan { get; set; }
+
+        /// <summary>
+        /// Compute shader for building a BVH.
+        /// </summary>
+        public ComputeShader buildHlbvh { get; set; }
+
+        /// <summary>
+        /// Compute shader for BVH restructuring.
+        /// </summary>
+        /// <remarks>
+        /// Used to optimize the BVH structure after initial construction.
+        /// </remarks>
+        public ComputeShader restructureBvh { get; set; }
+
+
+        
 
 #if UNITY_EDITOR
         /// <summary>

Packages/com.unity.render-pipelines.core/Runtime/UnifiedRayTracing/RayTracingResources.cs

@@ -151,6 +151,7 @@ struct HitContext
 namespace UnifiedRT {
 
 #pragma warning(disable : 3557) // prevent warning when the "while (rayQuery.Proceed())" loop is unrolled
+#pragma warning(disable : 4000) // suppress FXC warnings about potentially uninitialized variables
 
 void TraceRay(DispatchInfo dispatchInfo, RayTracingAccelStruct accelStruct, uint instanceMask, Ray ray, uint rayFlags, inout UNIFIED_RT_PAYLOAD payload)
 {