filament/io.github.erkko68.filament/FramePipelineEstimator

FramePipelineEstimator

Estimates the ideal frame rate (throughput) and latency (pipeline depth) from Renderer.getFrameInfoHistory, modelling the main CPU, backend and GPU stages by their mean plus Z standard deviations:

val history = renderer.getFrameInfoHistory(renderer.maxFrameHistorySize)
val workload = FramePipelineEstimator.estimateWorkload(history)
val sizing = FramePipelineEstimator.estimatePacing(history, pacingPeriod = 16_666_666)
pacer.configuration = FramePacer.Configuration(workload.idealFrameRate, sizing.latencyFrames * 16_666_666L)

Types

PacingSizing

data class PacingSizing(val latencyFrames: Int = 2, val safeDelayDuration: Long = 0)

The recommended pipeline depth in frames, and the slack in nanoseconds before CPU work must start.

TargetPercentile

enum TargetPercentile : Enum<FramePipelineEstimator.TargetPercentile>

The confidence that a frame fits the estimated budget; 1 - P is the theoretical miss rate. In practice stutters are rarer: spikes cluster, and the FramePacer's queue depth absorbs them.

Workload

data class Workload(val idealFrameDuration: Long, val idealFrameRate: Float = 60.0f)

The ideal throughput: the bottleneck stage's duration in nanoseconds, and its rate in Hz.

Functions

estimatePacing

fun estimatePacing(history: List<Renderer.FrameInfo>, pacingPeriod: Long, targetPercentile: FramePipelineEstimator.TargetPercentile = TargetPercentile.P90): FramePipelineEstimator.PacingSizing

The latency and safe delay for pacing history every pacingPeriod nanoseconds, at targetPercentile.

fun estimatePacing(history: List<Renderer.FrameInfo>, pacingPeriod: Long, zScore: Double): FramePipelineEstimator.PacingSizing

The latency and safe delay for pacing history every pacingPeriod nanoseconds, zScore deviations above the mean.

estimateWorkload

fun estimateWorkload(history: List<Renderer.FrameInfo>, targetPercentile: FramePipelineEstimator.TargetPercentile = TargetPercentile.P90): FramePipelineEstimator.Workload

The unthrottled throughput history supports at targetPercentile.

fun estimateWorkload(history: List<Renderer.FrameInfo>, zScore: Double): FramePipelineEstimator.Workload

The unthrottled throughput history supports, zScore standard deviations above the mean.

getZScore

fun getZScore(targetPercentile: FramePipelineEstimator.TargetPercentile): Double

The normal distribution Z-score of targetPercentile.