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

Internal/master

Packages/com.unity.render-pipelines.core/Documentation~/srp-callbacks-reference.md

@@ -1,12 +1,12 @@
-# Scriptable Render Pipeline callbacks reference
-
-When working with SRP, use these to make Unity call your C# code at specific times.
-
-* [RenderPipeline.Render](xref:UnityEngine.Rendering.RenderPipeline.Render(UnityEngine.Rendering.ScriptableRenderContext,UnityEngine.Camera[])) is the main entry point to the SRP. Unity calls this method automatically. If you are writing a custom render pipeline, this is where you begin to write your code.
-* The [RenderPipelineManager](xref:UnityEngine.Rendering.RenderPipelineManager) class has the following events that you can subscribe to, so that you can execute custom code at specific points in the render loop:
-    * [beginFrameRendering](xref:UnityEngine.Rendering.RenderPipeline.BeginFrameRendering(UnityEngine.Rendering.ScriptableRenderContext,UnityEngine.Camera[])) - **Note:** This can generate garbage. Use `beginContextRendering` instead.
-    * [endFrameRendering](xref:UnityEngine.Rendering.RenderPipeline.EndFrameRendering(UnityEngine.Rendering.ScriptableRenderContext,UnityEngine.Camera[])) - **Note:** This can generate garbage. Use `endContextRendering` instead.
-    * [beginContextRendering](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Rendering.RenderPipelineManager-beginContextRendering.html)
-    * [endContextRendering](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Rendering.RenderPipelineManager-endContextRendering.html)
-    * [beginCameraRendering](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Rendering.RenderPipelineManager-beginCameraRendering.html)
-    * [endCameraRendering](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Rendering.RenderPipelineManager-endCameraRendering.html)
+# Use Scriptable Render Pipeline callbacks
+
+To make Unity call your C# code at specific times, use the following APIs.
+
+To write your custom render pipeline code, use the [RenderPipeline.Render](https://docs.unity3d.com/6000.1/Documentation/ScriptReference/Rendering.RenderPipeline.Render.html) API. This method is the main entry point to the SRP, and Unity calls it automatically.
+
+To execute custom code at specific points in the render loop, subscribe to the following events in the [RenderPipelineManager](xref:UnityEngine.Rendering.RenderPipelineManager) class:
+
+* [beginContextRendering](https://docs.unity3d.com/6000.1/Documentation/ScriptReference/Rendering.RenderPipelineManager-beginContextRendering.html)
+* [endContextRendering](https://docs.unity3d.com/6000.1/Documentation/ScriptReference/Rendering.RenderPipelineManager-endContextRendering.html)
+* [beginCameraRendering](https://docs.unity3d.com/6000.1/Documentation/ScriptReference/Rendering.RenderPipelineManager-beginCameraRendering.html)
+* [endCameraRendering](https://docs.unity3d.com/6000.1/Documentation/ScriptReference/Rendering.RenderPipelineManager-endCameraRendering.html)

Packages/com.unity.render-pipelines.core/Documentation~/srp-creating-render-pipeline-asset-and-render-pipeline-instance.md

@@ -109,7 +109,7 @@ The following example shows how to create a `RenderPipelineAsset` script that de
             renderPipelineAsset = asset;
         }
     
-        protected override void Render(ScriptableRenderContext context, Camera[] cameras) {
+        protected override void Render(ScriptableRenderContext context, List<Camera> cameras) {
             // This is an example of using the data from the Render Pipeline Asset.
             Debug.Log(renderPipelineAsset.exampleString);
             

Packages/com.unity.render-pipelines.core/Documentation~/srp-creating-simple-render-loop.md

@@ -120,7 +120,7 @@ To clear the render target in the Scriptable Render Pipeline, you do the followi
 2. Add the `CommandBuffer` to the queue of commands on the `ScriptableRenderContext`; to do this, call [ScriptableRenderContext.ExecuteCommandBuffer](xref:UnityEngine.Rendering.ScriptableRenderContext.ExecuteCommandBuffer(UnityEngine.Rendering.CommandBuffer)).
 3. Instruct the graphics API to perform the queue of commands on the `ScriptableRenderContext`; to do this, call  [ScriptableRenderContext.Submit](xref:UnityEngine.Rendering.ScriptableRenderContext.Submit).
 
-As with all Scriptable Render Pipeline operations, you use the [RenderPipeline.Render](xref:UnityEngine.Rendering.RenderPipeline.Render(UnityEngine.Rendering.ScriptableRenderContext,UnityEngine.Camera[])) method as the entry point for this code. This example code demonstrates how to do this:
+As with all Scriptable Render Pipeline operations, you use the [RenderPipeline.Render](https://docs.unity3d.com/6000.1/Documentation/ScriptReference/Rendering.RenderPipeline.Render.html) method as the entry point for this code. This example code demonstrates how to do this:
 
 ```lang-csharp
 /* 

Packages/com.unity.render-pipelines.core/Documentation~/srp-using-scriptable-render-context.md

@@ -32,7 +32,7 @@ public class ExampleRenderPipeline : RenderPipeline
         public ExampleRenderPipeline() {
         }
 
-    protected override void Render(ScriptableRenderContext context, Camera[] cameras) {
+    protected override void Render(ScriptableRenderContext context, List<Camera> cameras) {
         // Create and schedule a command to clear the current render target
         var cmd = new CommandBuffer();
         cmd.ClearRenderTarget(true, true, Color.red);

Packages/com.unity.render-pipelines.core/Editor/Lighting/ProbeVolume/ProbeVolumeLightingTab.cs

@@ -1015,7 +1015,7 @@ internal bool PrepareAPVBake()
             if (AdaptiveProbeVolumes.partialBakeSceneList.Count == activeSet.sceneGUIDs.Count)
                 AdaptiveProbeVolumes.partialBakeSceneList = null;
 
-            if (ProbeReferenceVolume.instance.supportLightingScenarios && !activeSet.m_LightingScenarios.Contains(activeSet.lightingScenario))
+            if (ProbeReferenceVolume.instance.supportLightingScenarios && !activeSet.m_LightingScenarios.Contains(activeSet.lightingScenario) && activeSet.m_LightingScenarios.Count > 0)
                 activeSet.SetActiveScenario(activeSet.m_LightingScenarios[0], false);
 
             // Layout has changed and is incompatible.

Packages/com.unity.render-pipelines.core/Editor/Material/.buginfo

@@ -1 +1 @@
-area: Material
+area: Materials

Packages/com.unity.render-pipelines.core/Editor/ShaderGenerator/.buginfo

@@ -1 +1 @@
-area: Material
+area: Materials

Packages/com.unity.render-pipelines.core/Editor/Volume/VolumeParameterDrawer.cs

@@ -35,7 +35,7 @@ public VolumeParameterDrawerAttribute(Type parameterType)
     /// parameter this drawer is for.
     /// </summary>
     /// <remarks>
-    /// If you do not provide a custom editor for a <see cref="VolumeParameter"/>, Unity uses the buil-in property drawers to draw the
+    /// If you do not provide a custom editor for a <see cref="VolumeParameter"/>, Unity uses the built-in property drawers to draw the
     /// property as-is.
     /// </remarks>
     /// <example>

Packages/com.unity.render-pipelines.core/Runtime/Common/ReloadAttribute.cs

@@ -3,11 +3,52 @@
 namespace UnityEngine.Rendering
 {
     /// <summary>
-    /// Attribute specifying information to reload with <see cref="ResourceReloader"/>. This is only
-    /// used in the editor and doesn't have any effect at runtime.
+    /// The <see cref="ReloadAttribute"/> attribute specifies paths for loading or reloading resources and has no direct action.
+    /// Used with the <see cref="ResourceReloader"/> to define where to load data for null fields.
     /// </summary>
+    /// <remarks>
+    /// This attribute is designed for use in the Unity Editor and has no effect at runtime.
+    /// 
+    /// <see cref="IRenderPipelineResources"/> have their own attribute <see cref="ResourcePathAttribute"/> to do this.
+    /// When using them, resource reloading is handled automatically by the engine and does not require calling ResourceReloader.
+    /// 
+    /// While ResourceReloader was originally created for handling Scriptable Render Pipeline (SRP) resources, it has been replaced by <see cref="IRenderPipelineResources"/>.
+    /// The <see cref="ResourceReloader"/>, <see cref="ResourceReloader"/> and <see cref="ReloadGroupAttribute"/> remain available for for user-defined assets.
+    /// </remarks>
     /// <seealso cref="ResourceReloader"/>
     /// <seealso cref="ReloadGroupAttribute"/>
+    /// <example>
+    /// <para> This shows how to use the attribute in the expected scenario. This is particularly useful for content creators.
+    /// Adding a new field to a class that defines an asset results in null values for existing instances missing the field in their serialized data. Therefore, when a new field is added, a system for reloading null values may be necessary. </para>
+    /// <code>
+    ///using UnityEngine;
+    ///using UnityEditor;
+    ///
+    ///public class MyResourcesAsset : ScriptableObject
+    ///{
+    ///    [Reload("Shaders/Blit.shader")]
+    ///    public Shader blit;
+    ///    
+    ///    // Added in version 2
+    ///    [Reload("Shaders/betterBlit.shader")]
+    ///    public Shader betterBlit;
+    ///}
+    ///
+    ///public static class MyResourceHandler
+    ///{
+    ///    public static MyResourcesAsset GetAndReload()
+    ///    {
+    ///        var resources = AssetDatabase.LoadAssetAtPath&lt;MyResourcesAsset&gt;("MyResources.asset");
+    ///
+    ///        // Ensure that update of the data layout of MyResourcesAsset
+    ///        // will not result in null value for asset already existing.
+    ///        // (e.g.: added betterBlit in the case above)
+    ///        ResourceReloader.ReloadAllNullIn(resources, "Packages/com.my-custom-package/");
+    ///        return resources;
+    ///    }
+    ///}
+    /// </code>
+    /// </example>
     [AttributeUsage(AttributeTargets.Field)]
     public sealed class ReloadAttribute : Attribute
     {
@@ -52,6 +93,23 @@ public enum Package
         /// </summary>
         /// <param name="paths">Search paths</param>
         /// <param name="package">The lookup method</param>
+        /// <example>
+        /// <para> This example demonstrates how to handle arrays with different resource paths. </para>
+        /// <code>
+        ///using UnityEngine;
+        ///
+        ///public class MyResourcesAsset : ScriptableObject
+        ///{
+        ///    [ResourcePaths(new[]
+        ///    {
+        ///        "Texture/FilmGrain/Thin.png",
+        ///        "Texture/FilmGrain/Medium.png",
+        ///        "Texture/FilmGrain/Large.png",
+        ///    })]
+        ///    public Texture[] filmGrains;
+        ///}
+        /// </code>
+        /// </example>
         public ReloadAttribute(string[] paths, Package package = Package.Root)
         {
 #if UNITY_EDITOR
@@ -65,6 +123,18 @@ public ReloadAttribute(string[] paths, Package package = Package.Root)
         /// </summary>
         /// <param name="path">Search path</param>
         /// <param name="package">The lookup method</param>
+        /// <example>
+        /// <para> This example shows how to directly specify the path of an asset. </para>
+        /// <code>
+        ///using UnityEngine;
+        ///
+        ///public class MyResourcesAsset : ScriptableObject
+        ///{
+        ///    [Reload("Shaders/Blit.shader")]
+        ///    public Shader blit;
+        ///}
+        /// </code>
+        /// </example>
         public ReloadAttribute(string path, Package package = Package.Root)
             : this(new[] { path }, package)
         { }
@@ -77,6 +147,22 @@ public ReloadAttribute(string path, Package package = Package.Root)
         /// <param name="rangeMin">The array start index (inclusive)</param>
         /// <param name="rangeMax">The array end index (exclusive)</param>
         /// <param name="package">The lookup method</param>
+        /// <example>
+        /// <para> This example demonstrates handling arrays with resource paths that share a common format, differing only by an index. </para>
+        /// <code>
+        ///using UnityEngine;
+        ///
+        ///public class MyResourcesAsset : ScriptableObject
+        ///{
+        ///    // The following will seek for resources:
+        ///    //  - Texture/FilmGrain/Thin1.png
+        ///    //  - Texture/FilmGrain/Thin2.png
+        ///    //  - Texture/FilmGrain/Thin3.png
+        ///    [ResourcePaths("Texture/FilmGrain/Thin{0}.png", 1, 4)]
+        ///    public Texture[] thinGrains;
+        ///}
+        /// </code>
+        /// </example>
         public ReloadAttribute(string pathFormat, int rangeMin, int rangeMax,
             Package package = Package.Root)
         {

Packages/com.unity.render-pipelines.core/Runtime/Common/ReloadGroupAttribute.cs

@@ -1,14 +1,57 @@
 using System;
+using UnityEditor;
+using static UnityEngine.Rendering.DebugUI.Table;
 
 namespace UnityEngine.Rendering
 {
     /// <summary>
-    /// Attribute specifying that it contains element that should be reloaded.
-    /// If the instance of the class is null, the system will try to recreate
-    /// it with the default constructor.
-    /// Be sure classes using it have default constructor!
+    /// Attribute specifying that fields of this type should be inspected in depth by the <see cref="ResourceReloader"/>. 
+    /// If the associated class instance is null, the system attempts to recreate it using its default constructor.
     /// </summary>
+    /// <remarks>
+    /// Make sure classes using it have a default constructor!
+    /// </remarks>
+    /// <seealso cref="ResourceReloader"/>
     /// <seealso cref="ReloadAttribute"/>
+    /// <example>
+    /// <para> This shows how to use the attribute in the expected scenario. This is particularly useful for content creators.
+    /// Adding a new field to a class that defines an asset results in null values for existing instances missing the field in their serialized data. Therefore, when a new field is added, a system for reloading null values may be necessary. </para>
+    /// <code>
+    ///using UnityEngine;
+    ///using UnityEditor;
+    ///
+    ///[ReloadGroup]
+    ///public class MyShaders
+    ///{
+    ///    [Reload("Shaders/Blit.shader")]
+    ///    public Shader blit;
+    ///}
+    ///
+    ///public class MyResourcesAsset : ScriptableObject
+    ///{
+    ///    // Object used for contextualizing would resolve to be null in already existing
+    ///    // instance of MyResourcesAsset that already exists.
+    ///    public MyShaders shaders;
+    ///
+    ///    [Reload("Textures/BayerMatrix.png")]
+    ///    public Texture2D bayerMatrixTex;
+    ///}
+    ///
+    ///public static class MyResourceHandler
+    ///{
+    ///    public static MyResourcesAsset GetAndReload()
+    ///    {
+    ///        var resources = AssetDatabase.LoadAssetAtPath&lt;MyResourcesAsset&gt;("MyResources.asset");
+    ///
+    ///        // Ensure that update of the data layout of MyResourcesAsset
+    ///        // will not result in null value for asset already existing.
+    ///        // (e.g.: adding new field in MyResourcesAsset or MyShaders classes)
+    ///        ResourceReloader.ReloadAllNullIn(resources, "Packages/com.my-custom-package/");
+    ///        return resources;
+    ///    }
+    ///}
+    /// </code>
+    /// </example>
     [AttributeUsage(AttributeTargets.Class)]
     public sealed class ReloadGroupAttribute : Attribute
     { }

Packages/com.unity.render-pipelines.core/Runtime/Debugging/DebugManager.cs

@@ -11,20 +11,70 @@ namespace UnityEngine.Rendering
     using UnityObject = UnityEngine.Object;
 
     /// <summary>
-    /// IDebugData interface.
+    /// Implementing this interface enables integration with Unity's Rendering debugger, providing a way to manage and control the state of debug data.
     /// </summary>
+    ///
+    /// <remarks>
+    /// Use the `IDebugData` interface to register custom debug data. You can reset the data when necessary, which makes it suitable for debugging scenarios
+    /// where you need to clear or reset specific data. For example, when the application state changes or during gameplay session resets, 
+    /// or when the **Reset** button is selected in the **Rendering Debugger** window in the Editor or at runtime.
+    /// </remarks>
+    ///
+    /// <example>
+    /// <code>
+    /// public class MyDebugData : IDebugData
+    /// {
+    ///     private int _value;
+    ///
+    ///     /// Constructor of the debug data that will receive the reset callback
+    ///     public MyDebugData()
+    ///     {
+    ///         _value = 0;
+    ///     }
+    ///
+    ///     public Action GetReset()
+    ///     {
+    ///         /// Specify the callback when the reset operation is being called.
+    ///         return () => _value = 0; // Resets the value to 0
+    ///     }
+    /// }
+    /// </code>
+    /// </example>
     public interface IDebugData
     {
-        /// <summary>Get the reset callback for this DebugData</summary>
+        /// <summary>Provides the reset callback for resetting the debug data.</summary>
         /// <returns>The reset callback</returns>
         Action GetReset();
-        //Action GetLoad();
-        //Action GetSave();
     }
 
     /// <summary>
-    /// Manager class for the Debug Window.
+    /// The <see cref="DebugManager"/> class provides a centralized manager for handling Unity's Rendering debugger.
     /// </summary>
+    /// <remarks>
+    /// The DebugManager allows you to register, unregister, and manipulate debug data, panels, and widgets for runtime or editor debugging.
+    /// - Register and manage debug panels and widgets.
+    /// - Refresh and reset the debug UI based on runtime changes.
+    /// - Provides a global instance for easy access from anywhere in the codebase.
+    /// </remarks>
+    ///
+    /// <example>
+    /// <code>
+    /// {
+    ///     /// Create a list to store the new DebugUI widgets
+    ///     /// by creating different DebugUI.Values that display a label with a value.
+    ///     var list = new System.Collections.Generic.List&lt;DebugUI.Widget&gt;
+    ///     {
+    ///         new DebugUI.Value { displayName = "Lighting Intensity", getter = () => 1.0f, setter = value => Debug.Log($"Lighting Intensity set to {value}") },
+    ///         new DebugUI.Value { displayName = "Light Color", getter = () => Color.white, setter = value => Debug.Log($"Light Color set to {value}") }
+    ///     };
+    ///     var items = list.ToArray();
+    ///     
+    ///     /// Obtain the panel from the DebugManager instance, and add the Widgets that we want to display there.
+    ///     var panel = DebugManager.instance.GetPanel("Lighting", true);
+    ///     panel.children.AddRange(items);
+    /// }
+    /// </code>
+    /// </example>
     public sealed partial class DebugManager
     {
         static readonly Lazy<DebugManager> s_Instance = new Lazy<DebugManager>(() => new DebugManager());