Struct FramePace 

pub struct FramePace {
    pub last_tick: Option<Instant>,
    last_paced: bool,
    borrow_budget: Option<(Duration, Instant)>,
    phase_budget: Option<Duration>,
    deferred_until: Option<Instant>,
    last_damage: Option<Instant>,
    rephase: bool,
    damage_spacing: Option<Duration>,
    window_end: Option<Instant>,
    windowed: bool,
    extra: Option<(f64, Instant, Duration)>,
}

A capture’s frame pacing: the last frame it rendered, and how far a pull may still bring the next one forward.

The shared frame timer fires for the earliest due capture; each capture renders on it once its own period has (nearly) passed. Fresh input may also render a frame, and so may a frame the host compositor delivers under host capture or a region the X server reports damaged: a whole period after the last one the pull renders at once, and from half a period on it brings the frame forward, spending the time it comes early by from a budget that is paid back by a pull that arrives late and holds half a period at most. Input’s budget also refills at INPUT_BORROW_REFILL; the others’ does not (TickTrigger::refills). A pointer moving at the client’s refresh rate is thus captured as it lands rather than up to a period later, and a host’s or an application’s frames are published as they arrive rather than on the next timer tick, while input at a rate the cadence cannot follow raises the output rate by no more than the refill, and frames reported faster than the cadence not at all.

After an input frame, while the input’s own spacing sits at the cadence (PACED_INPUT_MIN_FRACTION to PACED_INPUT_MAX_FRACTION of a period), the timer stands back for TIMER_GRACE_AFTER_PULL beyond a period, so such input keeps rendering its own frames whether it runs a hair faster or slower than the timer, or jitters around it: a timer that resumed exactly a period after the frame would render just ahead of a move landing a little late, which then could not pull and waited a period. When the input stops, the timer renders after the grace and carries on from there. A faster client, a slower one, and a host’s frames leave the timer its period as before.

Damage the X server reports at the cadence earns the same grace: it is an application presenting on the server’s vblank, which runs on a clock of its own (a framebuffer server’s fake vblank fires on a millisecond timer, so its frames land up to a millisecond either side of the period). Without the grace a timer tick taken just ahead of such a frame captures the one before it again, and the frame it missed is published late or never.

Fields

last_tick: Option<Instant>

Last tick this capture actually rendered.

last_paced: bool

Whether that frame was input’s, with the input pacing itself at the cadence, so the timer stands back for the next move.

borrow_budget: Option<(Duration, Instant)>

Input’s budget left when it was last spent, and when that was; a fresh capture holds the cap.

phase_budget: Option<Duration>

The budget host frames and damage pull from, which refills only from their own late frames; a fresh capture holds the cap.

deferred_until: Option<Instant>

Where the timer was held off to by a tick that rendered nothing (host capture with no fresh frame), so it neither spins nor counts against the next frame.

last_damage: Option<Instant>

The last damage frame, and the running average of the spacing between damage frames.

rephase: bool

A still tick gave the next pull a fresh capture’s budget, which that pull spends whole.

damage_spacing: Option<Duration>

window_end: Option<Instant>

Paced in windows (Self::windowed): the end of the last period a frame closed.

windowed: bool

extra: Option<(f64, Instant, Duration)>

Paced in windows, the extra frames left when one was last sent, when, and the period that owns the elapsed time since then; a fresh capture holds the cap.

Implementations

impl FramePace

pub fn windowed() -> Self

Pacing in windows, for a capture a change wakes (XShm and DRI3 on the X server’s damage reports, the compositor on a client’s commit, input or a host frame): each period is a window holding one frame. A change takes its window’s frame as it lands; a window no change took ends on the timer’s frame. A change is published at once unless a change already took its window, in which case it waits for the next window, taking it WINDOW_EARLY_FRACTION of a period before it opens: the NvFBC capture’s schedule, whose driver pushes frames the same way. Without windows a change could come forward no earlier than half a period after the last frame, and one landing just after a timer frame waited that long.

Such a change is instead sent as an extra frame where the reserve holds one (EXTRA_CAP, refilled at EXTRA_REFILL a period), from EXTRA_MIN_FRACTION of a period after the last frame, and leaves the windows as they were. Taken from the next window, it would close that window ahead of a source drawing at the cadence, whose next frame then lands in a window already taken and waits as long again: any wait sustains itself, a source a hair faster than the cadence grows it to a period, and a 60 Hz application on its own clock under a 60 fps capture waited a median 6 ms a frame and up to 15, and one keystroke during a 60 Hz animation held each of its frames 12.5 ms.

fn window_closed_by(&self, period: Duration, now: Instant) -> Instant

Where the window a frame at now falls in ends: the open window after the last one a frame closed, or a later one where whole windows went by without a tick.

fn window_tick( &mut self, trigger: TickTrigger, period: Duration, now: Instant, sent: bool, )

A tick paced in windows: a timer tick ends the open window whether it sent a frame or not, which keeps the windows on the timer’s schedule; a change’s frame closes the window it lands in, and a change not sent leaves it open. A tick that came late (a busy capture or compositor thread, an encode that ran long) still ends the window it was due for, so the next opens on schedule and the rate holds: moving the grid to the late tick gave up the time it was late by, every time, and a loaded session streamed below its rate. A change taken less than a window after the open window’s timer was due ends that window too, or a screen changing a little slower than the cadence lost a window to each encode that ran past a period. Only windows that passed whole without a tick are given up. A change sent before the next window would take it is an extra frame, which spends the reserve and leaves the windows as they were.

pub fn due(&self, trigger: TickTrigger, period: Duration, now: Instant) -> bool

Whether a capture rendering every period is due a frame at now, given what asks. Paced in windows, a change is due once its window is open and the timer at the open window’s end, give or take the timer’s own lateness.

pub fn input_paced(interval: Option<Duration>, period: Duration) -> bool

Whether input spaced interval apart paces itself at the cadence of period.

pub fn ticked( &mut self, trigger: TickTrigger, period: Duration, now: Instant, input_paced: bool, )

Record the frame rendered at now. A pull ahead of the period spends the budget by what it came early; one behind the period pays back what it came late. A timer tick within half a period of when it was due counts as on time, so a timer that wakes a little late, as one does under load, keeps the rate instead of losing what it was late by every frame. input_paced says whether the input driving the capture paces itself at the cadence (Self::input_paced), which is what lets the timer stand back after an input frame.

fn damage_paced(&mut self, period: Duration, now: Instant) -> bool

Fold a damage frame at now into the spacing of damage frames, and say whether that spacing sits at the cadence of period.

fn timer_wait(&self, period: Duration) -> Duration

How long after the last frame the timer’s own tick renders again.

pub fn still(&self, period: Duration, now: Instant) -> bool

Whether the screen stands still at now: no change reported for STILL_PERIODS periods, longer than the timer waits after a change’s frame, so a screen that keeps changing never does.

pub fn stood_still(&mut self)

Give the next change the pull a fresh capture has, for a tick that found the screen still (Self::still): it moves the cadence onto the change and leaves nothing to borrow, so the frame after it waits a whole period.

pub fn record_tick( &mut self, trigger: TickTrigger, period: Duration, now: Instant, sent: bool, )

Record a tick of a capture the Damage extension wakes (the X11 paths), once it is known whether it sent a frame. Paced in windows (Self::windowed), a timer tick ends the open window and a change’s frame closes the one it lands in. Otherwise a sent frame counts (Self::ticked), one that published nothing holds the timer off a period (Self::defer), and a sent timer’s tick that finds the screen still gives the change after it a fresh capture’s pull (Self::stood_still): where every tick is sent (streaming mode, XShm), the changes before it spent the budget, which a still screen’s frames, never late, do not pay back, and each change would wait for the next tick. A tick that sent nothing spent nothing, and the budget refills alone.

pub fn defer(&mut self, until: Instant)

Hold the timer off this capture until until without a frame counting: a tick that published nothing must neither spin the timer nor move the cadence a fresh frame is measured against.

pub fn since_last_tick(&self, now: Instant) -> Option<Duration>

Time since this capture last rendered, if it has.

fn budget( &self, trigger: TickTrigger, period: Duration, now: Instant, ) -> Duration

How far a pull by trigger may bring the next frame forward at now.

pub fn pull_at( &self, trigger: TickTrigger, period: Duration, now: Instant, ) -> Instant

The earliest trigger, one that pulls forward, may render: a whole period after the last frame, less what its budget still allows it to borrow. A caller that waits until then need not test due again, since a budget only grows with time.

fn window_pull(&self, period: Duration, now: Instant) -> Instant

Paced in windows, when a change may take the window after the one the last frame closed: from WINDOW_EARLY_FRACTION of a period before it opens.

fn rebase_extra(&mut self, period: Duration, now: Instant)

Settle the reserve at its old cadence before moving its checkpoint to a changed period. The first mutating tick to observe the new period is the rebase anchor: pull_at and next_wake are immutable queries, so until that tick they keep accounting at the old period. Whole and fractional old periods are both retained in the reserve rather than reset or reinterpreted at the new cadence.

fn extra_refill(left: f64, at: Instant, period: Duration, now: Instant) -> f64

fn extra_frames(&self, now: Instant) -> f64

The extra frames a capture paced in windows may send at now.

pub fn next_due(&self, period: Duration, now: Instant) -> Instant

When the timer is next due for this capture: a period after the last frame, and the grace beyond that after an input frame the input paced.

pub fn window_opened(&self, period: Duration, now: Instant) -> Option<Instant>

Paced in windows, when the window now falls in opened: the boundary a display’s vblank would fall on. None before the first frame.

pub fn next_wake( &self, period: Duration, now: Instant, change_pending: bool, ) -> Instant

When a frame timer armed at now next has to fire for this capture. It wakes for a window still to open whether or not a change waits on it yet: a change landing later has nothing else to wake it, since a client that draws on frame callbacks goes quiet after its commit. A window already open takes a change as it lands, so only a change that could not be rendered keeps the timer close. It never sleeps past the next boundary unless a tick deferred it (Self::defer): a boundary is where the clients’ frame callbacks go out, and a wake for something else landing after a change’s pull would otherwise sleep to the end of the next window, costing a client that draws on those callbacks a frame.

Trait Implementations

impl Debug for FramePace

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for FramePace

fn default() -> FramePace

Returns the “default value” for a type.