Class ProfilingSampler

Wraps a ProfilerMarker and its associated ProfilerRecorder instances to provide per-frame CPU and GPU timing for a named profiling scope. Use together with ProfilingScope to bracket code you want to measure.

Inheritance

object

ProfilingSampler

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: UnityEngine.Rendering

Assembly: Unity.RenderPipelines.Core.Runtime.dll

Syntax

[IgnoredByDeepProfiler]
public class ProfilingSampler : IDisposable

Remarks

Timing properties (cpuElapsedTime, gpuElapsedTime, inlineCpuElapsedTime, and their sample-count counterparts) are only populated after enableRecording is set to true and at least one frame has elapsed. ProfilerRecorder instances are allocated lazily on the first enableRecording = true call; samplers that never enable recording hold no native resources. Recording support requires the UNITY_USE_RECORDER define (enabled by default); without it all timing properties return zero and no ProfilerRecorder is ever allocated.

Constructors

ProfilingSampler(string)

Creates a ProfilingSampler with Default under ProfilerCategory.Render. MarkerFlags.SampleGPU is added automatically because no verbosity level is set.

Declaration

public ProfilingSampler(string name)

Parameters

Type	Name	Description
string	name	Name shown in the Unity Profiler for this marker.

Properties

cpuElapsedTime

CPU elapsed time in milliseconds for command-buffer execution in the previous frame.

Declaration

public float cpuElapsedTime { get; }

Property Value

Type	Description
float

Remarks

Measures time spent replaying the command buffer on the CPU render thread. For inline (non-command-buffer) CPU time use inlineCpuElapsedTime.

cpuSampleCount

Number of times this sampler was hit via a command buffer on the CPU in the previous frame.

Declaration

public int cpuSampleCount { get; }

Property Value

Type	Description
int

enableRecording

Enables or disables ProfilerRecorder data collection for this sampler.

Declaration

public bool enableRecording { set; }

Property Value

Type	Description
bool

Remarks

Setting to true for the first time allocates the underlying ProfilerRecorder instances and starts collection; timing properties reflect the previous frame's data after at least one frame has elapsed. Setting back to false stops collection but keeps the recorders allocated for reuse. Has no effect when UNITY_USE_RECORDER is not defined.

gpuElapsedTime

GPU elapsed time in milliseconds for the previous frame.

Declaration

public float gpuElapsedTime { get; }

Property Value

Type	Description
float

Remarks

Only non-zero for user-visible markers (those created without verbosity flags), because MarkerFlags.SampleGPU is only added automatically in that case. Always returns 0 for markers created with a Verbosity* flag.

gpuSampleCount

Number of times this sampler was hit on the GPU in the previous frame.

Declaration

public int gpuSampleCount { get; }

Property Value

Type	Description
int

Remarks

Subject to the same MarkerFlags.SampleGPU condition as gpuElapsedTime.

inlineCpuElapsedTime

CPU elapsed time in milliseconds for direct (inline) Begin(CommandBuffer)/End(CommandBuffer) calls in the previous frame.

Declaration

public float inlineCpuElapsedTime { get; }

Property Value

Type	Description
float

Remarks

Reflects time recorded by Begin(CommandBuffer) and End(CommandBuffer) called directly on the calling thread, not via a command buffer. For command-buffer time use cpuElapsedTime.

inlineCpuSampleCount

Number of times this sampler was hit via direct inline calls in the previous frame.

Declaration

public int inlineCpuSampleCount { get; }

Property Value

Type	Description
int

name

Name of this sampler as it appears in the Unity Profiler.

Declaration

public string name { get; }

Property Value

Type	Description
string

Methods

Begin(CommandBuffer)

Begins the profiling block. Records both a command-buffer marker (if cmd is non-null) and an inline CPU marker.

Declaration

[Conditional("ENABLE_PROFILER")]
public void Begin(CommandBuffer cmd)

Parameters

Type	Name	Description
CommandBuffer	cmd	Command buffer to receive the GPU-visible marker. Pass `null` for CPU-only inline profiling.

Begin(CommandBuffer, Object)

Begins the profiling block with a Unity Object context associated with the sample. Records both a command-buffer marker (if cmd is non-null) and an inline CPU marker.

Declaration

[Conditional("ENABLE_PROFILER")]
public void Begin(CommandBuffer cmd, Object contextObject)

Parameters

Type	Name	Description
CommandBuffer	cmd	Command buffer to receive the GPU-visible marker. Pass `null` for CPU-only inline profiling.
Object	contextObject	Unity Object (e.g. Texture, Mesh, Material) to associate with this sample. The Profiler displays it in the sample hierarchy.

Create(string, MarkerFlags)

Creates a new ProfilingSampler under ProfilerCategory.Render with the specified MarkerFlags.

Declaration

public static ProfilingSampler Create(string name, MarkerFlags flags)

Parameters

Type	Name	Description
string	name	Name of the profiling sampler.
MarkerFlags	flags	Verbosity flags (e.g. MarkerFlags.Default, MarkerFlags.VerbosityAdvanced).

Returns

Type	Description
ProfilingSampler	A new ProfilingSampler, or `null` in non-development Player builds.

Remarks

Registers the following ProfilerMarkers:

name — The primary marker. Appears in the Profiler under ProfilerCategory.Render. Drives cpuElapsedTime, cpuSampleCount, and (when GPU sampling is active) gpuElapsedTime and gpuSampleCount. Use the primary marker name to measure CommandBuffer execution timings on the render thread.
"Inl_name" — The inline marker. Also under ProfilerCategory.Render, but without SampleGPU. Sampled directly by Begin(CommandBuffer) and End(CommandBuffer) on the calling thread. Drives inlineCpuElapsedTime and inlineCpuSampleCount.

When no verbosity bits (bits 10–12) are set in flags, MarkerFlags.SampleGPU is added to the primary marker automatically so that GPU timing is captured by default for user-visible markers. Pass any Verbosity* flag (e.g. MarkerFlags.VerbosityAdvanced) to suppress GPU recording. ProfilerRecorder instances (which hold native handles) are not allocated in the constructor; they are created lazily the first time enableRecording is set to true. Samplers that never enable recording add no native-resource overhead.

Dispose()

Releases the native ProfilerRecorder resources held by this sampler. This is a no-op if enableRecording was never set to true.

Declaration

public void Dispose()

End(CommandBuffer)

Ends the profiling block started by Begin(CommandBuffer) call.

Declaration

[Conditional("ENABLE_PROFILER")]
public void End(CommandBuffer cmd)

Parameters

Type	Name	Description
CommandBuffer	cmd	The same command buffer passed to Begin(CommandBuffer) call, or `null` if no command buffer was used.

~ProfilingSampler()

Finalizer — releases recorders when no explicit Dispose() call was made.

Declaration

protected ~ProfilingSampler()

Get<TEnum>(TEnum)

Get the sampler for the corresponding enumeration value.

Declaration

public static ProfilingSampler Get<TEnum>(TEnum marker) where TEnum : Enum

Parameters

Type	Name	Description
TEnum	marker	Enumeration value.

Returns

Type	Description
ProfilingSampler	The ProfilingSampler for the given enumeration value, or `null` in non-development Player builds.

Type Parameters

Name	Description
TEnum	Type of the enumeration.

Implements

IDisposable

Extension Methods

ReflectionUtils.GetField(object, string)

ReflectionUtils.GetFields(object)

ReflectionUtils.Invoke(object, string, params object[])

ReflectionUtils.SetField(object, string, object)

AnalyticsUtils.ToNestedColumnWithDefault<T>(T, T, bool)

AnalyticsUtils.ToNestedColumn<T>(T, T)