filament/io.github.erkko68.filament/FramePacer

FramePacer

class FramePacer(nativeHandle: NativePointer)

Coordinates frame scheduling and presentation timestamps: a filter between the platform's VSYNC callbacks (such as Android's Choreographer) and Renderer.setPresentationTime.

Created with Builder and destroyed with Engine.destroy. All times are steady-clock nanoseconds (CLOCK_MONOTONIC on Android, which System.nanoTime() reads there). In each VSYNC callback:

if (pacer.setupFrame(tick) != FramePacer.FrameStatus.ACCEPTED) return // yield to keep the cadence
if (pacer.hasGpuFallenBehind(renderer)) { renderer.skipFrame(tick.baseTime); return }
pacer.applyPresentationTime(renderer)
if (renderer.beginFrame(swapChain)) { renderer.render(view); renderer.endFrame() }

Constructors

FramePacer

constructor(nativeHandle: NativePointer)

Types

Builder

class Builder

Configuration

data class Configuration(val targetFrameRate: Float = 60.0f, val latency: Long)

Pacing targets.

FrameStatus

enum FrameStatus : Enum<FramePacer.FrameStatus>

HardwareTimeline

data class HardwareTimeline(val expectedPresentationTime: Long, val deadline: Long)

One expected hardware presentation timeline.

PacingStatus

enum PacingStatus : Enum<FramePacer.PacingStatus>

VsyncTick

data class VsyncTick(val baseTime: Long, val vsyncPeriod: Long, val frameScheduleTime: Long? = null, val timelines: List<FramePacer.HardwareTimeline> = emptyList())

VSYNC telemetry from the platform compositor.

Properties

configuration

var configuration: FramePacer.Configuration

The active pacing targets; setting it rescales subsequent frames (e.g. for thermal mitigation).

effectiveLatency

val effectiveLatency: Long

The target presentation time minus the frame's base time, in nanoseconds.

expectedPresentationTime

val expectedPresentationTime: Long

The presentation time computed by the last setupFrame, for judder-free animation.

isExactFrameRateAchieved

val isExactFrameRateAchieved: Boolean

Whether selectedFrameRate is an exact integer fraction of the display refresh rate (false for 45 FPS on 60Hz).

nativeObject

val nativeObject: NativePointer

The native object, for interop with code calling the Fila* C API directly. Read-only: this wrapper owns it.

pacingStatus

val pacingStatus: FramePacer.PacingStatus

The pipeline's flow control status.

renderingDeadline

val renderingDeadline: Long

The time by which the last setupFrame's frame must finish rendering to make its presentation.

selectedFrameRate

val selectedFrameRate: Float

The pacing frame rate in use: the target, matched to the display's cadence and clamped to its refresh rate.

Functions

applyPresentationTime

fun applyPresentationTime(renderer: Renderer)

Sets the computed presentation time, desired presentation time and rendering deadline on renderer; call before endFrame.

hasGpuFallenBehind

fun hasGpuFallenBehind(renderer: Renderer): Boolean

Whether the GPU has fallen behind; if so, the state setupFrame advanced is rolled back and the frame should be skipped with Renderer.skipFrame, without applyPresentationTime or Renderer.beginFrame.

resetPacing

fun resetPacing()

Drops the relative pacing state and re-anchors to the target latency on the next frame.

setupExtraFrame

fun setupExtraFrame(): Boolean

Targets one more presentation frame without advancing the cadence, to recover queue depth when pacingStatus is PacingStatus.DISPLAY_STARVING; follow it with applyPresentationTime and a frame. Returns false, doing nothing, when the pipeline is already at its target latency.

setupFrame

fun setupFrame(tick: FramePacer.VsyncTick): FramePacer.FrameStatus

Evaluates the pacing state for the upcoming frame; call it first thing in the VSYNC callback.