gpu_acquire_diagnostics.hpp File Reference

What a window host records about a swapchain acquire, so a trace can say why gpu_acquire waited. More...

#include <string_view>

Go to the source code of this file.

Classes
struct	pulp::view::GpuAcquireDiagnostics

Namespaces
namespace	pulp
namespace	pulp::view
	Hover-cursor tracking for platform window hosts.

Functions
GpuAcquireDiagnostics	pulp::view::gpu_acquire_diagnostics (double now_s, double vsync_target_s, double refresh_period_s, int frames_in_flight) noexcept
	Build the record for one acquire.
bool	pulp::view::gpu_timing_requested (const char *env_value) noexcept
	Whether an environment value asks for GPU timing: "1", "true", "yes" or "on", case-insensitively.

Variables
constexpr std::string_view	pulp::view::kGpuTimingEnvVar = "PULP_GPU_TIMING"
	The environment variable a standalone GPU window reads to enable GPU render timing.

Detailed Description

What a window host records about a swapchain acquire, so a trace can say why gpu_acquire waited.

Acquire blocks when every drawable is held: on Metal, nextDrawable waits for one of the layer's drawables (three by default) to come back from the compositor. That happens for two different reasons, and they need opposite fixes:

• the CPU presented frames faster than the display consumed them (two frames landing in one refresh interval fill the queue), which shows as a frame that started early or on time relative to its display-link target with few frames still on the GPU;
• the GPU is behind (a frame's GPU work outruns the refresh interval), which shows as two or more frames still executing on the GPU.

The host fills this in immediately before acquiring and attaches it to the gpu_acquire trace span. Nothing reads it to make a decision.