[COPT-3698] Add Object-context overload to ProfilingScope and CommandBuffer.BeginSample

Author: alexey-zakharov

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

@@ -161,6 +161,25 @@ public void Begin(CommandBuffer cmd)
 #endif
         }
 
+        /// <summary>
+        /// Begins the profiling block with a Unity Object context associated with the sample.
+        /// Records both a command-buffer marker (if <paramref name="cmd"/> is non-null) and an
+        /// inline CPU marker.
+        /// </summary>
+        /// <param name="cmd">Command buffer to receive the GPU-visible marker.
+        /// Pass <c>null</c> for CPU-only inline profiling.</param>
+        /// <param name="contextObject">Unity Object (e.g. Texture, Mesh, Material) to associate
+        /// with this sample. The Profiler displays it in the sample hierarchy.</param>
+        [Conditional("ENABLE_PROFILER")]
+        [MethodImpl(MethodImplOptions.AggressiveInlining | (MethodImplOptions)512)]
+        public void Begin(CommandBuffer cmd, Object contextObject)
+        {
+#if ENABLE_PROFILER
+            cmd?.BeginSample(m_Marker, contextObject);
+            m_InlineMarker.Begin(contextObject);
+#endif
+        }
+
         /// <summary>
         /// Ends the profiling block started by <see cref="Begin"/> call.
         /// </summary>
@@ -345,22 +364,32 @@ public struct ProfilingScope : IDisposable
 #if ENABLE_PROFILER
         ProfilingSampler    m_Sampler;
         CommandBuffer       m_Cmd;
-        bool                m_Disposed;
 #endif
 
         /// <summary>
         /// Creates a profiling scope without a command buffer (inline CPU profiling only).
         /// </summary>
         /// <param name="sampler">The sampler that provides the underlying marker.
         /// May be <c>null</c>; the scope is a no-op in that case.</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining | (MethodImplOptions)512)]
         public ProfilingScope(ProfilingSampler sampler)
+            : this((CommandBuffer)null, sampler)
+        {
+        }
+
+        /// <summary>
+        /// Creates an inline CPU-only profiling scope with a Unity Object context associated
+        /// with the sample. No command buffer is involved; the marker is emitted directly
+        /// on the CPU timeline.
+        /// </summary>
+        /// <param name="sampler">The sampler that provides the underlying marker.
+        /// May be <c>null</c>; the scope is a no-op in that case.</param>
+        /// <param name="contextObject">Unity Object (e.g. Texture, Mesh, Material) to associate
+        /// with this sample. The Profiler displays it in the sample hierarchy.</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining | (MethodImplOptions)512)]
+        public ProfilingScope(ProfilingSampler sampler, Object contextObject)
+            : this(null, sampler, contextObject)
         {
-#if ENABLE_PROFILER
-            m_Sampler = sampler;
-            m_Cmd = null;
-            m_Disposed = false;
-            m_Sampler?.Begin(m_Cmd);
-#endif            
         }
 
         /// <summary>
@@ -377,15 +406,29 @@ public ProfilingScope(ProfilingSampler sampler)
         public ProfilingScope(CommandBuffer cmd, ProfilingSampler sampler)
         {
 #if ENABLE_PROFILER
-            if (sampler != null)
-            {
-                m_Disposed = false;
-                sampler.Begin(cmd);
-            }
-            else
-            {
-                m_Disposed = true;
-            }
+            sampler?.Begin(cmd);
+            m_Sampler = sampler;
+            m_Cmd = cmd;
+#endif
+        }
+
+        /// <summary>
+        /// Creates a profiling scope that records markers into <paramref name="cmd"/> with a
+        /// Unity Object context associated with the sample.
+        /// </summary>
+        /// <remarks>
+        /// Do not use with a named <see cref="CommandBuffer"/>. A named command buffer inserts
+        /// its own scope marker on execution, which orphans the markers added here.
+        /// </remarks>
+        /// <param name="cmd">Command buffer to receive the GPU-visible begin/end markers.</param>
+        /// <param name="sampler">The sampler that provides the underlying marker.
+        /// May be <c>null</c>; the scope is a no-op in that case.</param>
+        /// <param name="contextObject">Unity Object (e.g. Texture, Mesh, Material) to associate
+        /// with this sample. The Profiler displays it in the sample hierarchy.</param>
+        public ProfilingScope(CommandBuffer cmd, ProfilingSampler sampler, Object contextObject)
+        {
+#if ENABLE_PROFILER
+            sampler?.Begin(cmd, contextObject);
             m_Sampler = sampler;
             m_Cmd = cmd;
 #endif
@@ -405,15 +448,7 @@ public ProfilingScope(CommandBuffer cmd, ProfilingSampler sampler)
         public ProfilingScope(BaseCommandBuffer cmd, ProfilingSampler sampler)
         {
 #if ENABLE_PROFILER
-            if (sampler != null)
-            {
-                m_Disposed = false;
-                sampler.Begin(cmd.m_WrappedCommandBuffer);
-            }
-            else
-            {
-                m_Disposed = true;
-            }
+            sampler?.Begin(cmd.m_WrappedCommandBuffer);
             m_Sampler = sampler;
             m_Cmd = cmd.m_WrappedCommandBuffer;
 #endif
@@ -425,11 +460,11 @@ public ProfilingScope(BaseCommandBuffer cmd, ProfilingSampler sampler)
         public void Dispose()
         {
 #if ENABLE_PROFILER
-            if (m_Disposed)
+            if (m_Sampler == null)
                 return;
 
-            m_Sampler?.End(m_Cmd);
-            m_Disposed = true;
+            m_Sampler.End(m_Cmd);
+            m_Sampler = null;
 #endif
         }
     }

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

@@ -198,6 +198,34 @@ public IEnumerator ProfilingScope_InlineCpuElapsedTime_IsGreaterThanZero()
             Assert.Greater(m_Sampler.inlineCpuSampleCount, 0);
         }
 
+        [UnityTest]
+        public IEnumerator ProfilingScopeWithObject_InlineCpu_IsCapturedByRecorder()
+        {
+            m_Sampler.enableRecording = true;
+
+            var texture = new Texture2D(1, 1) { name = "TestTexture" };
+            for (int i = 0; i < 2; i++)
+            {
+                using (new ProfilingScope(m_Sampler, texture))
+                { }
+                yield return null;
+            }
+            UnityEngine.Object.DestroyImmediate(texture);
+
+            Assert.Greater(m_Sampler.inlineCpuElapsedTime, 0.0f);
+            Assert.Greater(m_Sampler.inlineCpuSampleCount, 0);
+        }
+
+        [Test]
+        public void ProfilingScopeWithNullObject_InlineCpu_DoesNotCrash()
+        {
+            Assert.DoesNotThrow(() =>
+            {
+                using (new ProfilingScope(m_Sampler, null))
+                { }
+            });
+        }
+
         [Test]
         public void Dispose_DoesNotThrow()
         {

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

@@ -0,0 +1,143 @@
+using System.Collections;
+using NUnit.Framework;
+using Unity.Profiling;
+using UnityEngine;
+using UnityEngine.Rendering;
+using UnityEngine.TestTools;
+
+namespace UnityEngine.Rendering.Tests
+{
+    class ProfilingSamplerWithCommandBufferTests
+    {
+        const int kWarmupFrames = 4 /*ProfilerRecorder.GPU_RESULTS_DELAY_FRAMES*/;
+        const int kSampledFrames = 2;
+
+        Texture2D m_Texture;
+
+        [OneTimeSetUp]
+        public void SetUp()
+        {
+            m_Texture = new Texture2D(1, 1) { name = "TestTexture" };
+        }
+
+        [OneTimeTearDown]
+        public void TearDown()
+        {
+            UnityEngine.Object.DestroyImmediate(m_Texture);
+        }
+
+        [UnityTest]
+        public IEnumerator CommandBufferBeginSample_IsCapturedByProfilerRecorder()
+        {
+            var sampler = new ProfilingSampler(nameof(CommandBufferBeginSample_IsCapturedByProfilerRecorder));
+            using var recorder = ProfilerRecorder.StartNew(ProfilerCategory.Render, sampler.name);
+
+            var commandBuffer = new CommandBuffer();
+            using (new ProfilingScope(commandBuffer, sampler))
+            { }
+
+            yield return ExecuteCommandBufferForFrames(commandBuffer, kWarmupFrames, kSampledFrames);
+
+            commandBuffer.Dispose();
+            Assert.AreEqual(1, recorder.Count);
+            Assert.Greater(recorder.GetSample(0).Count, 0);
+        }
+
+        [UnityTest]
+        public IEnumerator CommandBufferBeginSampleWithObject_IsCapturedByProfilerRecorder()
+        {
+            var sampler = new ProfilingSampler(nameof(CommandBufferBeginSampleWithObject_IsCapturedByProfilerRecorder));
+            using var recorder = ProfilerRecorder.StartNew(ProfilerCategory.Render, sampler.name);
+
+            var commandBuffer = new CommandBuffer();
+            using (new ProfilingScope(commandBuffer, sampler, m_Texture))
+            { }
+
+            yield return ExecuteCommandBufferForFrames(commandBuffer, kWarmupFrames, kSampledFrames);
+
+            commandBuffer.Dispose();
+            Assert.AreEqual(1, recorder.Count);
+            Assert.Greater(recorder.GetSample(0).Count, 0);
+        }
+
+        [Test]
+        public void CommandBufferBeginSampleWithNullObject_DoesNotCrash()
+        {
+            var sampler = new ProfilingSampler(nameof(CommandBufferBeginSampleWithNullObject_DoesNotCrash));
+            var commandBuffer = new CommandBuffer();
+            Assert.DoesNotThrow(() =>
+            {
+                using (new ProfilingScope(commandBuffer, sampler, null))
+                { }
+                Graphics.ExecuteCommandBuffer(commandBuffer);
+            });
+            commandBuffer.Dispose();
+        }
+
+        [UnityTest]
+        [UnityPlatform(include = new[]
+        {
+            RuntimePlatform.WindowsPlayer,
+            RuntimePlatform.WindowsEditor,
+            RuntimePlatform.Android,
+            RuntimePlatform.PS5,
+            RuntimePlatform.Switch,
+            RuntimePlatform.XboxOne
+        })]
+        public IEnumerator CommandBufferBeginSampleWithObject_GpuSamples_ReturnsNonZeroCount()
+        {
+            var sampler = new ProfilingSampler(nameof(CommandBufferBeginSampleWithObject_GpuSamples_ReturnsNonZeroCount));
+            using var recorder = ProfilerRecorder.StartNew(ProfilerCategory.Render, sampler.name, 1, ProfilerRecorderOptions.GpuRecorder | ProfilerRecorderOptions.Default);
+
+            var commandBuffer = new CommandBuffer();
+            using (new ProfilingScope(commandBuffer, sampler, m_Texture))
+            { }
+
+            yield return ExecuteCommandBufferForFrames(commandBuffer, kWarmupFrames, kSampledFrames);
+
+            commandBuffer.Dispose();
+            Assert.AreEqual(1, recorder.Count);
+            Assert.Greater(recorder.GetSample(0).Count, 0);
+        }
+
+        [UnityTest]
+        [UnityPlatform(include = new[]
+        {
+            RuntimePlatform.WindowsPlayer,
+            RuntimePlatform.WindowsEditor,
+            RuntimePlatform.Android,
+            RuntimePlatform.PS5,
+            RuntimePlatform.Switch,
+            RuntimePlatform.XboxOne
+        })]
+        public IEnumerator CommandBufferBeginSample_GpuSamples_ReturnsNonZeroCount()
+        {
+            var sampler = new ProfilingSampler(nameof(CommandBufferBeginSample_GpuSamples_ReturnsNonZeroCount));
+            using var recorder = ProfilerRecorder.StartNew(ProfilerCategory.Render, sampler.name, 1, ProfilerRecorderOptions.GpuRecorder | ProfilerRecorderOptions.Default);
+
+            var commandBuffer = new CommandBuffer();
+            using (new ProfilingScope(commandBuffer, sampler))
+            { }
+
+            yield return ExecuteCommandBufferForFrames(commandBuffer, kWarmupFrames, kSampledFrames);
+
+            commandBuffer.Dispose();
+            Assert.AreEqual(1, recorder.Count);
+            Assert.Greater(recorder.GetSample(0).Count, 0);
+        }
+
+        static IEnumerator ExecuteCommandBufferForFrames(CommandBuffer commandBuffer, int warmupFrames, int sampledFrames)
+        {
+            for (int i = 0; i < warmupFrames; i++)
+            {
+                Graphics.ExecuteCommandBuffer(commandBuffer);
+                yield return null;
+            }
+            for (int i = 0; i < sampledFrames; i++)
+            {
+                Graphics.ExecuteCommandBuffer(commandBuffer);
+                yield return null;
+            }
+        }
+    }
+}

Packages/com.unity.render-pipelines.core/Tests/Runtime/Debugging/ProfilingSamplerWithCommandBufferTests.cs.meta

@@ -490,7 +490,7 @@ private void DisposeAdditionalCameraData()
 
             public CameraRenderingScope(ScriptableRenderContext context, Camera camera)
             {
-                using (new ProfilingScope(beginCameraRenderingSampler))
+                using (new ProfilingScope(beginCameraRenderingSampler, camera))
                 {
                     m_Context = context;
                     m_Camera = camera;
@@ -501,7 +501,7 @@ public CameraRenderingScope(ScriptableRenderContext context, Camera camera)
 
             public void Dispose()
             {
-                using (new ProfilingScope(endCameraRenderingSampler))
+                using (new ProfilingScope(endCameraRenderingSampler, m_Camera))
                 {
                     EndCameraRendering(m_Context, m_Camera);
                 }
@@ -898,9 +898,9 @@ static void RenderSingleCamera(ScriptableRenderContext context, UniversalCameraD
             CommandBuffer cmdScope = cameraData.xr.enabled ? null : cmd;
 
             var cameraMetadata = CameraMetadataCache.GetCached(camera);
-            using (new ProfilingScope(cmdScope, cameraMetadata.sampler)) // Enqueues a "BeginSample" command into the CommandBuffer cmd
+            using (new ProfilingScope(cmdScope, cameraMetadata.sampler, camera)) // Enqueues a "BeginSample" command into the CommandBuffer cmd
             {
-                using (new ProfilingScope(Profiling.Pipeline.Renderer.setupCullingParameters))
+                using (new ProfilingScope(Profiling.Pipeline.Renderer.setupCullingParameters, camera))
                 {
                     var legacyCameraData = new CameraData(frameData);
 
@@ -978,7 +978,7 @@ static void RenderSingleCamera(ScriptableRenderContext context, UniversalCameraD
                 UniversalShadowData shadowData;
                 CullContextData cullData;
 
-                using (new ProfilingScope(Profiling.Pipeline.initializeRenderingData))
+                using (new ProfilingScope(Profiling.Pipeline.initializeRenderingData, camera))
                 {
                     CreateUniversalResourceData(frameData);
                     lightData = CreateLightData(frameData, asset, data.cullResults.visibleLights, renderingMode);
@@ -1006,7 +1006,7 @@ static void RenderSingleCamera(ScriptableRenderContext context, UniversalCameraD
             context.ExecuteCommandBuffer(cmd); // Sends to ScriptableRenderContext all the commands enqueued since cmd.Clear, i.e the "EndSample" command
             CommandBufferPool.Release(cmd);
 
-            using (new ProfilingScope(Profiling.Pipeline.Context.submit))
+            using (new ProfilingScope(Profiling.Pipeline.Context.submit, cameraData.camera))
             {
                 context.Submit(); // Actually execute the commands that we previously sent to the ScriptableRenderContext context
             }
@@ -1037,7 +1037,7 @@ private static void CreateShadowAtlasAndCullShadowCasters(UniversalLightData lig
         /// <param name="isLastBaseCamera">True if this is the last base camera.</param>
         static void RenderCameraStack(ScriptableRenderContext context, Camera baseCamera, bool isLastBaseCamera)
         {
-            using var profScope = new ProfilingScope(ProfilingSampler.Get(URPProfileId.RenderCameraStack));
+            using var profScope = new ProfilingScope(ProfilingSampler.Get(URPProfileId.RenderCameraStack), baseCamera);
 
             baseCamera.TryGetComponent<UniversalAdditionalCameraData>(out var baseCameraAdditionalData);