pulp::view::HostFramePump Class Reference

Converts a host's monotonic presentation timestamps into per-frame deltas. More...

#include <host_frame_pump.hpp>

Public Member Functions
float	measure (double now_seconds)
	Measure the delta for the frame presented at now_seconds (monotonic, seconds).
void	suspend ()
	Tell the pump the host is about to stop pumping frames (idle at 0 fps, display link stopped, view detached).
void	note_frame_skipped ()
	Tell the pump the host had a vsync it deliberately did NOT turn into a frame (nothing dirty, nothing animating, no idle callback — see should_dispatch_host_frame).
void	set_nominal_dt (float dt)
	Nominal frame interval used for the first frame and for resumes.
float	nominal_dt () const
void	set_wake_threshold (float seconds)
	Gap above which a frame is treated as a resume rather than a slow frame.
float	wake_threshold () const
bool	suspended () const
	True while the next measure() would be a resume (before the first frame, after suspend(), or with a note_frame_skipped() still pending).
std::uint64_t	resumes () const
	Number of resumes so far, first frame included. Observability + tests.
double	last_timestamp () const
	Timestamp of the last measured frame (undefined while suspended()).
void	reset ()

Static Public Attributes
static constexpr float	kDefaultNominalDt = 1.0f / 60.0f
static constexpr float	kDefaultWakeThreshold = 0.25f

Detailed Description

Converts a host's monotonic presentation timestamps into per-frame deltas.

Owned by the host, ticked on the UI thread. Prefer the vsync source's OWN timestamp (CVTimeStamp::hostTime, CADisplayLink.targetTimestamp) over a fresh wall-clock read: it is the time the frame will actually be presented, and it stays correct even when the callback is delivered late.

Member Function Documentation

last_timestamp()

double pulp::view::HostFramePump::last_timestamp ( ) const

inline

Timestamp of the last measured frame (undefined while suspended()).

measure()

float pulp::view::HostFramePump::measure

(

double

now_seconds

)

Measure the delta for the frame presented at now_seconds (monotonic, seconds).

Returns, in order of precedence:

• nominal_dt() on the first frame and on any resume — a suspend(), a pending note_frame_skipped(), or a gap over wake_threshold() (see class docs),
• 0 for a non-advancing timestamp (duplicate / coalesced callback, or a source that went backwards — never rewind the clock),
• otherwise the RAW measured delta, dropped frames included.

nominal_dt()

float pulp::view::HostFramePump::nominal_dt ( ) const

inline

note_frame_skipped()

void pulp::view::HostFramePump::note_frame_skipped ( )

inline

Tell the pump the host had a vsync it deliberately did NOT turn into a frame (nothing dirty, nothing animating, no idle callback — see should_dispatch_host_frame).

The pump did not measure that vsync, so the wall-clock gap it opens is idle time, not animation time: the next measure() is a resume regardless of how short the gap was.

Callable from the vsync source's own thread (touches one atomic); cleared by the next measure() on the UI thread.

reset()

void pulp::view::HostFramePump::reset

(

)

resumes()

std::uint64_t pulp::view::HostFramePump::resumes ( ) const

inline

Number of resumes so far, first frame included. Observability + tests.

set_nominal_dt()

void pulp::view::HostFramePump::set_nominal_dt

(

float

dt

)

Nominal frame interval used for the first frame and for resumes.

Hosts that know their refresh period (CVDisplayLinkGetNominalOutputVideoRefreshPeriod, CADisplayLink.duration) should set it; the default assumes 60 Hz.

set_wake_threshold()

void pulp::view::HostFramePump::set_wake_threshold

(

float

seconds

)

Gap above which a frame is treated as a resume rather than a slow frame.

suspend()

void pulp::view::HostFramePump::suspend

(

)

Tell the pump the host is about to stop pumping frames (idle at 0 fps, display link stopped, view detached).

The next measure() is a resume regardless of the elapsed gap. Optional — the wake threshold catches an unannounced idle too — but explicit is exact.

suspended()

bool pulp::view::HostFramePump::suspended ( ) const

inline

True while the next measure() would be a resume (before the first frame, after suspend(), or with a note_frame_skipped() still pending).

wake_threshold()

float pulp::view::HostFramePump::wake_threshold ( ) const

inline

Member Data Documentation

kDefaultNominalDt

float pulp::view::HostFramePump::kDefaultNominalDt = 1.0f / 60.0f

staticconstexpr

kDefaultWakeThreshold

float pulp::view::HostFramePump::kDefaultWakeThreshold = 0.25f

staticconstexpr

---

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

• /home/runner/work/pulp/pulp/core/view/include/pulp/view/host_frame_pump.hpp