//filament-android/com.google.android.filament.android/FramePacer

FramePacer

[main]
open class FramePacer

Coordinates frame scheduling and presentation timestamps across multi-threaded rendering architectures.

The FramePacer decouples the CPU rendering loop from fluctuating hardware display cadences, acting as a deterministic filter between incoming platform VSYNC events (such as Android's Choreographer) and native buffer presentation submissions (via setPresentationTime).

Types

Name	Summary
Builder	[main]
open class Builder
Constructs a new FramePacer instance.
Configuration	[main]
open class Configuration
FrameStatus	[main]
enum FrameStatus
PacingStatus	[main]
enum PacingStatus

Functions

Name	Summary
applyPresentationTime	[main]
open fun applyPresentationTime(renderer: Renderer)
Applies the computed Latency Offset timestamp directly onto the rendering command stream.
clearNativeObject	[main]
open fun clearNativeObject()
configure	[main]
open fun configure(config: FramePacer.Configuration)
Dynamically updates the active pacing targets mid-flight (e.g., for thermal or power mitigation).
[main]
open fun configure(targetFrameRate: Float, latencyNanos: Long)
destroy	[main]
open fun destroy(engine: Engine)
Destroys this FramePacer instance and frees all associated native resources.
getEffectiveLatencyNanos	[main]
open fun getEffectiveLatencyNanos(): Long
Returns the effective target latency in nanoseconds.
getExpectedPresentationTimeNanos	[main]
open fun getExpectedPresentationTimeNanos(): Long
Returns the target presentation timestamp computed during the most recent call to setupFrame().
getNativeObject	[main]
open fun getNativeObject(): Long
getPacingStatus	[main]
open fun getPacingStatus(): FramePacer.PacingStatus
Returns the current flow control status of the pacing pipeline.
getRenderingDeadlineNanos	[main]
open fun getRenderingDeadlineNanos(): Long
Returns the target rendering deadline timestamp computed during the most recent call to setupFrame().
getSelectedFrameRate	[main]
open fun getSelectedFrameRate(): Float
Returns the actual pacing frame rate selected during the active frame pacing cycle.
hasGpuFallenBehind	[main]
open fun hasGpuFallenBehind(renderer: Renderer): Boolean
Checks if the GPU rendering pipeline has fallen behind the CPU submission rate.
isExactFrameRateAchieved	[main]
open fun isExactFrameRateAchieved(): Boolean
Returns whether the selected pacing frame rate is achieved exactly by the display hardware.
resetPacing	[main]
open fun resetPacing()
Forces the FramePacer to abandon its relative pacing state and rigidly re-anchor to the configured target latency on the next frame.
setupExtraFrame	[main]
open fun setupExtraFrame(): Boolean
Advances the internal pacing pipeline to target an extra presentation frame in the future, without advancing the ideal cadence clock (mExpectedBaseTime).
setupFrame	[main]
open fun setupFrame(frameTimeNanos: Long): FramePacer.FrameStatus
open fun setupFrame(frameTimeNanos: Long, vsyncPeriodNanos: Long): FramePacer.FrameStatus
Prepares and evaluates the frame pacing state for the upcoming frame cycle.
[main]
open fun setupFrame(frameData: FrameData, vsyncPeriodNanos: Long): FramePacer.FrameStatus
Prepares and evaluates the frame pacing state for the upcoming frame cycle using Android 13+ FrameData.