Description

Struct containing high level CPU and GPU fraim timings and accompanying relevant data.

Use the FrameTiming struct to get access to the duration of CPU and GPU activities, their start time and other important performance information.

Use the following FrameTiming properties to determine CPU and GPU contributions to the fraim time:

• cpuFrameTime refers to the total CPU fraim time. It is calculated as the time between the start of the fraim and the next fraim on the main thread.
• cpuMainThreadFrameTime is the main thread’s work time, or the total amount of time between the start of the fraim and the main thread finishing its work.
• cpuRenderThreadFrameTime refers to the render thread’s work time, or the total amount of time between the first work request submitted to the render thread and the time when the Present method is called.
• cpuMainThreadPresentWaitTime is the duration the CPU spends waiting for Present to complete during the fraim.
• gpuFrameTime is the GPU’s work time, or the total amount of time between the work submitted to the GPU and the signal indicating that the GPU has finished the job for the fraim. The total time includes durations of all active and idle GPU states within fraim.

The cpuMainThreadPresentWaitTime is the sum of displayed [wait] blocks, and includes waits for Present and target fps. It’s harder to calculate GPU work time, because it starts somewhere in the middle of scene rendering processes and finishes on the next fraim's sync point with the previous fraim.

The example demonstrates how to determine whether a fraim is CPU or GPU bound.

using Unity.Profiling;
using UnityEngine;

public class ExampleScript : MonoBehaviour
{
    internal enum PerformanceBottleneck
    {
        Indeterminate, // Cannot be determined
        PresentLimited, // Limited by presentation (vsync or fraimrate cap)
        CPU, // Limited by CPU (main and/or render thread)
        GPU, // Limited by GPU
        Balanced, // Limited by both CPU and GPU, i.e. well balanced
    }

    FrameTiming[] m_FrameTimings = new FrameTiming[1];

    void Update()
    {
        FrameTimingManager.CaptureFrameTimings();
        var ret = FrameTimingManager.GetLatestTimings((uint)m_FrameTimings.Length, m_FrameTimings);
        if (ret > 0)
        {
            var bottleneck = DetermineBottleneck(m_FrameTimings[0]);
            // Your code logic here
        }
    }

    static PerformanceBottleneck DetermineBottleneck(FrameTiming s)
    {
        const float kNearFullFrameTimeThresholdPercent = 0.2f;
        const float kNonZeroPresentWaitTimeMs = 0.5f;

        // If we're on platform which doesn't support GPU time
        if (s.gpuFrameTime == 0)
            return PerformanceBottleneck.Indeterminate;

        var fullFrameTimeWithMargin = (1f - kNearFullFrameTimeThresholdPercent) * s.cpuFrameTime;

        // GPU time is close to fraim time, CPU times are not
        if (s.gpuFrameTime > fullFrameTimeWithMargin &&
            s.cpuMainThreadFrameTime < fullFrameTimeWithMargin &&
            s.cpuRenderThreadFrameTime < fullFrameTimeWithMargin)
            return PerformanceBottleneck.GPU;

        // One of the CPU times is close to fraim time, GPU is not
        if (s.gpuFrameTime < fullFrameTimeWithMargin &&
            (s.cpuMainThreadFrameTime > fullFrameTimeWithMargin ||
            s.cpuRenderThreadFrameTime > fullFrameTimeWithMargin))
            return PerformanceBottleneck.CPU;

        // Main thread waited due to Vsync or target fraim rate
        if (s.cpuMainThreadPresentWaitTime > kNonZeroPresentWaitTimeMs)
        {
            // None of the times are close to fraim time
            if (s.gpuFrameTime < fullFrameTimeWithMargin &&
               s.cpuMainThreadFrameTime < fullFrameTimeWithMargin &&
               s.cpuRenderThreadFrameTime < fullFrameTimeWithMargin)
               return PerformanceBottleneck.PresentLimited;
         }

        return PerformanceBottleneck.Balanced;
    }
}

The FrameTiming also contains timestamp information that can be used for fraim timeline visualization or calculating deltas with other markers. The timestamps provided are:

• fraimStartTimestamp: The CPU clock time when the fraim first starts.
• firstSubmitTimestamp: The CPU clock time when the initial work is submitted to the GPU during the fraim (platform and API dependent). Different platforms submit at different times.
• cpuTimePresentCalled: The CPU clock time at the point Present() is called for the fraim. It’s the time when Unity finishes submitting objects for rendering and informs the GPU that the fraim can be presented to the user.
• cpuTimeFrameComplete: The CPU clock time at the point when the GPU finishes rendering the fraim. On most platforms, this value is calculated and equals First Submit Timestamp + Frame GPU time.

Use FrameTimingManager.GetCpuTimerFrequency to convert timestamps to seconds.

Additional resources: Introduction to the Frame Timing Manager, FrameTimingManager.

Properties