ludus::platform::FramePacer¶

Class

Owner-local native frame pacer that waits for absolute monotonic targets.

Call Pace() once per frame, before the frame reads its own timestamp. The first call anchors a schedule; each later call waits until the next target and advances that target from the previous target, never from the wake time, so oversleeping one frame does not shift later frames. A late frame skips missed targets while it is within the policy's maximum lateness and re-anchors the schedule beyond it, so stalls never produce a burst of back-to-back frames.

The pacer never spins: every wait is an operating-system wait for the remaining interval. A scheduled target is at most one interval away; after a failed or limited wait started a frame early, at most two. It does not replace presentation blocking. Swapchain queue depth, vsync and GPU completion remain graphics policy, and browsers pace with presentation callbacks.

Values are allocation-free and need caller synchronization if shared. Call Reset() on lifecycle changes that should not inherit the old phase: startup, suspension and session replacement.

Declared in modules/platform/include/ludus/platform/frame_pacing.h

#include <ludus/platform/frame_pacing.h>

class ludus::platform::FramePacer final

Methods¶

Configure¶

PacingStatus ludus::platform::FramePacer::Configure(const PacingPolicy &policy) noexcept

Apply a pacing policy and drop the schedule.

Parameter	Description
`policy`	Interval within [1 ns, MAXIMUM_PACING_INTERVAL_NANOSECONDS] and any maximum lateness.

Returns

Ok, or InvalidConfiguration with the previous policy and schedule unchanged.

Related types: PacingStatus · PacingPolicy

Declared in modules/platform/include/ludus/platform/frame_pacing.h

Reset¶

void ludus::platform::FramePacer::Reset() noexcept

Drop the schedule. The next Pace() is a Baseline that starts at once.

Declared in modules/platform/include/ludus/platform/frame_pacing.h

Pace¶

PaceResult ludus::platform::FramePacer::Pace(const PacingClock &clock) noexcept

Wait for this frame's target, then advance the schedule.

Reads the clock, waits while it is before the target (rereading after every wake or interruption), and returns once the target is reached, a wait fails or the attempt limit is hit. See PaceOutcome for the schedule change in each case.

Parameter	Description
`clock`	Time source and wait primitive; both functions must be nonnull.

Returns

Diagnostics for this frame; the schedule changes as described by its Outcome.

Related types: PaceResult · PacingClock

Declared in modules/platform/include/ludus/platform/frame_pacing.h

GetPolicy¶

LUDUS_INLINE const PacingPolicy & ludus::platform::FramePacer::GetPolicy() const noexcept

Return the active policy. A default-constructed pacer has a zero interval.

Related types: PacingPolicy

Declared in modules/platform/include/ludus/platform/frame_pacing.h

IsScheduled¶

LUDUS_INLINE bool ludus::platform::FramePacer::IsScheduled() const noexcept

Return whether a schedule is anchored, so the next Pace() is not a Baseline.

Declared in modules/platform/include/ludus/platform/frame_pacing.h

GetNextTarget¶

LUDUS_INLINE foundation::time::Timestamp ludus::platform::FramePacer::GetNextTarget() const noexcept

Return the target the next Pace() waits for. Meaningful only while IsScheduled().

Related types: foundation::time::Timestamp

Declared in modules/platform/include/ludus/platform/frame_pacing.h