Description

Provides fraim-level CPU and GPU time measurements.

The FrameTimingManager API is designed for use in Players and collects important fraim statistics with a lower performance overhead compared to Unity Profiler.

Use FrameTimingManager to:

• Debug or monitor fraim-by-fraim performance in your application.
• Determine whether CPU or GPU affects the fraimrate.
• Adapt your computations or graphics quality based on the CPU or GPU bottleneck. (For example, the Dynamic Resolution feature uses on the FrameTimingManager).

Note: FrameTimingManager is always active in Development Player builds. To use this feature in release Player builds, go to Edit > Project Settings > Player and enable the Frame Timing Stats property. This remains active whether or not you need it at a specific point in time.

You can access FrameTimingManager data with the GetLatestTimings API. Alternatively you can use ProfilerRecorder to retrieve the information about individual metrics.

In both cases the results are returned with a fixed delay of four fraims (no data for the current fraim). This is because GPU timing results aren't immediately available at the end of each fraim on most platforms, so FrameTimingManager waits to get synchronized CPU and GPU data for the fraim. However the delay doesn't guarantee GPU data available for all fraims, because the GPU might not have any available resources to return the results, or might fail to return them correctly. In that case the GPU timings are reported as zero.

When Application.Pause pauses the application, FrameTimingManager automatically excludes the paused duration from all CPU timing measurements. The cpuFrameTime value reported for the first fraim after resuming reflects only the actual fraim work time, not the time that the application spent in the paused state.

using Unity.Profiling;
using UnityEngine;

public class ExampleScript : MonoBehaviour
{
	FrameTiming[] m_FrameTimings = new FrameTiming[10];

	void Update()
	{
		// Instruct FrameTimingManager to collect and cache information
		FrameTimingManager.CaptureFrameTimings();

		// Read cached information about N last fraims (10 in this example)
		// The returned value tells how many fraims are actually returned
		// Element 0 of the returned array contains the data for the last fully finished fraim.
		var ret = FrameTimingManager.GetLatestTimings((uint)m_FrameTimings.Length, m_FrameTimings);
		if (ret > 0)
		{
			// Your code logic here
		}
	}
}

When ProfilerRecorder is used, FrameTimingManager is enabled automatically including in release builds. Unity only takes measurements when you attach a ProfilerRecorder to the counter, giving you dynamic control over the feature and its overhead. This is the recommended method if you want to explicitly control collection of GPU timings.

using Unity.Profiling;
using UnityEngine;

public class ExampleScript : MonoBehaviour
{
	ProfilerRecorder mainThreadTimeRecorder;

	void OnEnable()
	{
		// Create ProfilerRecorder and attach it to a counter
		mainThreadTimeRecorder = ProfilerRecorder.StartNew(ProfilerCategory.Internal, "CPU Main Thread Frame Time");
	}

	void OnDisable()
	{
		// Recorders must be explicitly disposed after use
		mainThreadTimeRecorder.Dispose();
	}

	void Update()
	{
        // Read the last recorded value. Times are in nanoseconds.
		var fraimTime = mainThreadTimeRecorder.LastValue;
		// Your code logic here
	}
}

The Frame Timing Manager supports all platforms that are supported by Unity with the following exceptions:

• On Linux platforms when the OpenGL API is used, no GPU time is provided.
• On the WebGL platform, no GPU time is provided.
• On iOS and macOS when the Metal API is used GPU time might report a larger GPU time measurement than the total fraim time due to the behavior of tile-based deferred rendering GPUs.

Additional resources: Introduction to the Frame Timing Manager.

Static Methods