pulp::inspect::ControlGpuHealthProvider::FrameObservation Struct Reference

#include <control_gpu_health_provider.hpp>

Public Attributes
std::string	lifecycle_id
	Unique product editor lifecycle identity.
std::optional< CacheState >	observed_cache_state
CacheProvenance	cache_provenance = CacheProvenance::unknown
	Producer-observed cache boundary.
AdapterIdentity	adapter
bool	capture_valid = false
bool	content_floor_passed = false
bool	gpu_submission_observed = false
	Set only by a host producer with direct submission evidence.
bool	native_present_observed = false
	Set only by a native lifecycle producer after the frame became visible.
std::optional< std::chrono::steady_clock::time_point >	native_presented_at
	Timestamp supplied by the trusted native compositor/presentation producer.
std::optional< double >	interaction_hitch_ms
std::optional< double >	shader_compile_ms
std::optional< double >	upload_ms
std::optional< double >	hidden_frame_ms
std::optional< double >	present_ms
std::optional< std::string >	trace_evidence_id
	Must exactly match Config::trace_evidence_id, the identity emitted by the provider spans for this campaign.
std::vector< std::string >	missing_trace_categories
	Required categories that the exact same-instance trace could not prove for this observation.
std::uint64_t	non_transparent_pixel_count = 0
std::uint64_t	distinct_color_count = 0
std::string	observed_signature_sha256
std::optional< std::string >	observed_source_signature_sha256
	Optional trace bindings supplied by a producer that can correlate the frame with exact source and shader identities.
std::optional< std::string >	observed_shader_signature_sha256
std::chrono::steady_clock::time_point	observed_at

Member Data Documentation

adapter

AdapterIdentity pulp::inspect::ControlGpuHealthProvider::FrameObservation::adapter

cache_provenance

CacheProvenance pulp::inspect::ControlGpuHealthProvider::FrameObservation::cache_provenance = CacheProvenance::unknown

Producer-observed cache boundary.

The provider never derives this from elapsed time or the requested cold/warm label.

capture_valid

bool pulp::inspect::ControlGpuHealthProvider::FrameObservation::capture_valid = false

content_floor_passed

bool pulp::inspect::ControlGpuHealthProvider::FrameObservation::content_floor_passed = false

distinct_color_count

std::uint64_t pulp::inspect::ControlGpuHealthProvider::FrameObservation::distinct_color_count = 0

gpu_submission_observed

bool pulp::inspect::ControlGpuHealthProvider::FrameObservation::gpu_submission_observed = false

Set only by a host producer with direct submission evidence.

A screenshot or available adapter does not prove GPU submission.

hidden_frame_ms

std::optional<double> pulp::inspect::ControlGpuHealthProvider::FrameObservation::hidden_frame_ms

interaction_hitch_ms

std::optional<double> pulp::inspect::ControlGpuHealthProvider::FrameObservation::interaction_hitch_ms

lifecycle_id

std::string pulp::inspect::ControlGpuHealthProvider::FrameObservation::lifecycle_id

Unique product editor lifecycle identity.

Positive campaign trials require a fresh bounded value so repeated polls cannot masquerade as independent cold/warm editor opens.

missing_trace_categories

std::vector<std::string> pulp::inspect::ControlGpuHealthProvider::FrameObservation::missing_trace_categories

Required categories that the exact same-instance trace could not prove for this observation.

These are instrumentation coverage gaps, not dropped events. Empty is meaningful only with a trace evidence id.

native_present_observed

bool pulp::inspect::ControlGpuHealthProvider::FrameObservation::native_present_observed = false

Set only by a native lifecycle producer after the frame became visible.

A back-buffer capture proves only that the host rendered those pixels; it observes nothing about display, so it can never stand in for this flag.

native_presented_at

std::optional<std::chrono::steady_clock::time_point> pulp::inspect::ControlGpuHealthProvider::FrameObservation::native_presented_at

Timestamp supplied by the trusted native compositor/presentation producer.

A capture/readback completion timestamp cannot substitute for this endpoint.

Returning from a present CALL is not presentation either, and the two available macOS candidates miss in OPPOSITE directions. GpuSurface::end_frame() only hands the drawable to the compositor and waits for nothing, so returning from it precedes display by up to a refresh interval and UNDER-reports first-visible latency – the direction that turns a budget miss into a pass.

Back-buffer capture completion is the opposite error, not a tighter version of the same one. The timestamp is taken AFTER capture_back_buffer_png() returns, so it is that present-call return PLUS PNG encode time; and the readback inside it blocks on a synchronising submit, spinning until the GPU signals, BETWEEN submit and present – delaying the very present it claims to measure. Capture completion therefore OVER-reports first-visible latency, so it risks failing a frame that met its budget. Only a producer that observes actual display – a presented-drawable callback carrying the instant the frame reached the screen – may write here. No such producer exists on any Pulp backend today, which is why native_present_timing stays in missing_trace_categories.

non_transparent_pixel_count

std::uint64_t pulp::inspect::ControlGpuHealthProvider::FrameObservation::non_transparent_pixel_count = 0

observed_at

std::chrono::steady_clock::time_point pulp::inspect::ControlGpuHealthProvider::FrameObservation::observed_at

observed_cache_state

std::optional<CacheState> pulp::inspect::ControlGpuHealthProvider::FrameObservation::observed_cache_state

observed_shader_signature_sha256

std::optional<std::string> pulp::inspect::ControlGpuHealthProvider::FrameObservation::observed_shader_signature_sha256

observed_signature_sha256

std::string pulp::inspect::ControlGpuHealthProvider::FrameObservation::observed_signature_sha256

observed_source_signature_sha256

std::optional<std::string> pulp::inspect::ControlGpuHealthProvider::FrameObservation::observed_source_signature_sha256

Optional trace bindings supplied by a producer that can correlate the frame with exact source and shader identities.

present_ms

std::optional<double> pulp::inspect::ControlGpuHealthProvider::FrameObservation::present_ms

shader_compile_ms

std::optional<double> pulp::inspect::ControlGpuHealthProvider::FrameObservation::shader_compile_ms

trace_evidence_id

std::optional<std::string> pulp::inspect::ControlGpuHealthProvider::FrameObservation::trace_evidence_id

Must exactly match Config::trace_evidence_id, the identity emitted by the provider spans for this campaign.

A frame-local identity cannot establish correlation on its own.

upload_ms

std::optional<double> pulp::inspect::ControlGpuHealthProvider::FrameObservation::upload_ms

---

The documentation for this struct was generated from the following file:

• /home/runner/work/pulp/pulp/inspect/include/pulp/inspect/control_gpu_health_provider.hpp