This application pacing helper is designed to schedule the rendering time of clients that submit frames to a compositor, which runs its own render loop that picks latest completed frames for that client. More...

#include <util/u_pacing.h>

Collaboration diagram for u_pacing_app:

[legend]

Static Public Member Functions
static void	u_pa_predict (struct u_pacing_app upa, uint64_t now_ns, int64_t out_frame_id, uint64_t out_wake_up_time, uint64_t out_predicted_display_time, uint64_t *out_predicted_display_period)
	Predict when the client's next rendered frame will be displayed; when the client should be woken up from sleeping; and its display period. More...

static void	u_pa_mark_point (struct u_pacing_app *upa, int64_t frame_id, enum u_timing_point point, uint64_t when_ns)
	Mark a point on the frame's lifetime. More...

static void	u_pa_mark_discarded (struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns)
	When a frame has been discarded. More...

static void	u_pa_mark_delivered (struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns, uint64_t display_time_ns)
	A frame has been delivered from the client, see `xrEndFrame`. More...

static void	u_pa_mark_gpu_done (struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns)
	A frame has been completed rendered by the GPU, this can happen after `xrEndFrame` has returned. More...

static void	u_pa_info (struct u_pacing_app *upa, uint64_t predicted_display_time_ns, uint64_t predicted_display_period_ns, uint64_t extra_ns)
	Add a new sample point from the main render loop. More...

static void	u_pa_latched (struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns, int64_t system_frame_id)
	Latch a frame for rendering for delivery to the native compositor, may be called multiple times for the same frame should the app be on a frame cadence that is lower then the native compositor. More...

static void	u_pa_retired (struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns)
	Mark a frame as completely retired, will never be latched (used by the native compositor again) as a new frame has been latched or a shutdown condition has been met. More...

static void	u_pa_destroy (struct u_pacing_app **upa_ptr)
	Destroy this u_pacing_app. More...

Data Fields
void(*	predict )(struct u_pacing_app upa, uint64_t now_ns, int64_t out_frame_id, uint64_t out_wake_up_time, uint64_t out_predicted_display_time, uint64_t *out_predicted_display_period)
	Predict when the client's next rendered frame will be displayed; when the client should be woken up from sleeping; and its display period. More...

void(*	mark_point )(struct u_pacing_app *upa, int64_t frame_id, enum u_timing_point point, uint64_t when_ns)
	Mark a point on the frame's lifetime. More...

void(*	mark_discarded )(struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns)
	When a frame has been discarded. More...

void(*	mark_delivered )(struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns, uint64_t display_time_ns)
	A frame has been delivered from the client, see `xrEndFrame`. More...

void(*	mark_gpu_done )(struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns)
	A frame has been completed rendered by the GPU, this can happen after `xrEndFrame` has returned. More...

void(*	latched )(struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns, int64_t system_frame_id)
	Latch a frame for rendering for delivery to the native compositor, may be called multiple times for the same frame should the app be on a frame cadence that is lower then the native compositor. More...

void(*	retired )(struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns)
	Mark a frame as completely retired, will never be latched (used by the native compositor again) as a new frame has been latched or a shutdown condition has been met. More...

void(*	info )(struct u_pacing_app *upa, uint64_t predicted_display_time_ns, uint64_t predicted_display_period_ns, uint64_t extra_ns)
	Add a new sample point from the main render loop. More...

void(*	destroy )(struct u_pacing_app *upa)
	Destroy this u_pacing_app. More...

Detailed Description

This application pacing helper is designed to schedule the rendering time of clients that submit frames to a compositor, which runs its own render loop that picks latest completed frames for that client.

It manages the frame pacing of an app/client, rather than the compositor itself. The frame pacing of the compositor is handled by u_pacing_compositor

Field Documentation

◆ destroy

void(* u_pacing_app::destroy) (struct u_pacing_app *upa)

Destroy this u_pacing_app.

Referenced by u_pa_destroy().

◆ info

void(* u_pacing_app::info) (struct u_pacing_app *upa, uint64_t predicted_display_time_ns, uint64_t predicted_display_period_ns, uint64_t extra_ns)

Add a new sample point from the main render loop.

This is called in the main renderer loop that tightly submits frames to the real compositor for displaying. This is only used to inform the render helper when the frame will be shown, not any timing information about the client.

When this is called doesn't matter that much, as the render timing will need to be able to predict one or more frames into the future anyways. But preferably as soon as the main loop wakes up from wait frame.

Parameters

upa	Self pointer
predicted_display_time_ns	Predicted display time for this sample.
predicted_display_period_ns	Predicted display period for this sample.
extra_ns	Time between display and when this sample was created, that is when the main loop was woken up by the main compositor.

Referenced by u_pa_info().

◆ latched

void(* u_pacing_app::latched) (struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns, int64_t system_frame_id)

Latch a frame for rendering for delivery to the native compositor, may be called multiple times for the same frame should the app be on a frame cadence that is lower then the native compositor.

Parameters

	upa	App pacer struct.
[in]	frame_id	The frame ID of the latched frame.
[in]	when_ns	Time when the latching happened.
[in]	system_frame_id	The ID of the system frame that is latching the app's frame.

Referenced by u_pa_latched().

◆ mark_delivered

void(* u_pacing_app::mark_delivered) (struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns, uint64_t display_time_ns)

A frame has been delivered from the client, see xrEndFrame.

The GPU might still be rendering the work.

Parameters

	upa	Render timing helper.
[in]	frame_id	The frame ID to mark as delivered.
[in]	when_ns	The time when it was delivered, nominally from os_monotonic_get_ns
[in]	display_time_ns	The time the frame is to be displayed.

Referenced by u_pa_mark_delivered().

◆ mark_discarded

void(* u_pacing_app::mark_discarded) (struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns)

When a frame has been discarded.

Parameters

	upa	Render timing helper.
[in]	frame_id	The frame ID to mark as discarded.
[in]	when_ns	The time when it was discarded, nominally from os_monotonic_get_ns

Referenced by u_pa_mark_discarded().

◆ mark_gpu_done

void(* u_pacing_app::mark_gpu_done) (struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns)

A frame has been completed rendered by the GPU, this can happen after xrEndFrame has returned.

Parameters

	upa	Render timing helper.
[in]	frame_id	The frame ID to mark as delivered.
[in]	when_ns	The time when it the gpu was finished, nominally from os_monotonic_get_ns

Referenced by u_pa_mark_gpu_done().

◆ mark_point

void(* u_pacing_app::mark_point) (struct u_pacing_app *upa, int64_t frame_id, enum u_timing_point point, uint64_t when_ns)

Mark a point on the frame's lifetime.

Parameters

	upa	Render timing helper.
[in]	frame_id	The frame ID to record for.
[in]	point	The point/event to record
[in]	when_ns	The timestamp

See also: Frame Pacing/Timing.

Referenced by u_pa_mark_point().

◆ predict

void(* u_pacing_app::predict) (struct u_pacing_app *upa, uint64_t now_ns, int64_t *out_frame_id, uint64_t *out_wake_up_time, uint64_t *out_predicted_display_time, uint64_t *out_predicted_display_period)

Predict when the client's next rendered frame will be displayed; when the client should be woken up from sleeping; and its display period.

This is called from xrWaitFrame, but it does not do any waiting, the caller should wait till out_wake_up_time.

Parameters

	upa	Render timing helper.
[in]	now_ns	The current timestamp in nanoseconds, nominally from os_monotonic_get_ns
[out]	out_frame_id	Frame ID of this predicted frame.
[out]	out_wake_up_time	When the client should be woken up.
[out]	out_predicted_display_time	Predicted display time.
[out]	out_predicted_display_period	Predicted display period.

Referenced by u_pa_predict().

◆ retired

void(* u_pacing_app::retired) (struct u_pacing_app *upa, int64_t frame_id, uint64_t when_ns)

Mark a frame as completely retired, will never be latched (used by the native compositor again) as a new frame has been latched or a shutdown condition has been met.

Parameters

	upa	App pacer struct.
[in]	frame_id	The frame ID of the latched frame.
[in]	when_ns	Time when the latching happened.

Referenced by u_pa_retired().

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

auxiliary/util/u_pacing.h

Static Public Member Functions

Data Fields

Detailed Description

Field Documentation

◆ destroy

◆ info

◆ latched

◆ mark_delivered

◆ mark_discarded

◆ mark_gpu_done

◆ mark_point

◆ predict

◆ retired