filament/io.github.erkko68.filament/Renderer

Renderer

class Renderer(nativeHandle: NativePointer)

Renderer represents an operating system window and manages frame rendering and pacing.

Typically, applications create a Renderer per window. The Renderer generates drawing commands for the render thread and manages frame latency to keep it low.

A Renderer generates drawing commands from a View, which itself contains a Scene description.

Typical render loop:

while (!quit) {
    if (renderer.beginFrame(swapChain)) {
        renderer.render(view)
        renderer.endFrame()
    }
}

Frame pacing: beginFrame() manages frame pacing and returns false if the GPU is falling behind (to skip frames and reduce latency). When false is returned, either skip the frame or proceed anyway; if proceeding, you must still call endFrame().

Constructors

Renderer

constructor(nativeHandle: NativePointer)

Types

ClearOptions

class ClearOptions

ClearOptions control how the SwapChain is cleared or discarded at the beginning of a frame.

Companion

object Companion

DisplayInfo

class DisplayInfo

Display refresh-rate information for frame pacing and dynamic resolution scaling.

FrameInfo

class FrameInfo(val frameId: Int, val gpuFrameDuration: Long, val denoisedGpuFrameDuration: Long, val beginFrame: Long, val endFrame: Long, val backendBeginFrame: Long, val backendEndFrame: Long, val gpuFrameComplete: Long, val vsync: Long, val displayPresent: Long, val presentDeadline: Long, val displayPresentInterval: Long, val compositionToPresentLatency: Long, val expectedPresentLatency: Long, val frameScheduleTime: Long)

Timing information about a frame. Times are nanoseconds since the steady-clock epoch; durations are nanoseconds.

FrameRateOptions

class FrameRateOptions

Frame rate control and dynamic resolution scaling options.

Properties

clearOptions

var clearOptions: Renderer.ClearOptions

Get/set clear behavior for the SwapChain. The getter returns a snapshot — mutate it and assign back to apply.

engine

val engine: Engine

Get the Engine that created this Renderer.

frameToSkipCount

val frameToSkipCount: Int

Get the number of frames left to skip.

hasGpuFallenBehind

val hasGpuFallenBehind: Boolean

Whether GPU execution has fallen behind the CPU, to detect latency build-up when driving the presentation loop manually.

materialTime

val materialTime: Double

Get material time in seconds.

maxFrameHistorySize

val maxFrameHistorySize: Int

The maximum supported frame history size.

nativeObject

val nativeObject: NativePointer

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

userTime

val userTime: Double

Get elapsed time since resetUserTime() in seconds.

Functions

beginFrame

fun beginFrame(swapChain: SwapChain, frameTimeNanos: Long = 0): Boolean

Prepare a frame for rendering and manage frame pacing.

copyFrame

fun copyFrame(dstSwapChain: SwapChain, dstViewport: Viewport, srcViewport: Viewport, flags: Int)

Copy the rendered frame to another SwapChain at a specified viewport.

endFrame

fun endFrame()

Finish the current frame and schedule it for display.

getFrameInfoHistory

fun getFrameInfoHistory(historySize: Int = 1): List<Renderer.FrameInfo>

Returns up to historySize entries of frame timing history, most recent first. The history can be lost when beginFrame() switches SwapChain.

pauseRenderThread

fun pauseRenderThread(timeNs: Long)

Pause the render thread for a specified duration in nanoseconds.

readPixels

@PlatformGap(platforms = [FilamentPlatform.WEB], behavior = "delivers asynchronously — the pixels are copied into the buffer when the frame completes, before its callback runs, rather than on return.")

fun readPixels(xoffset: Int, yoffset: Int, width: Int, height: Int, buffer: Texture.PixelBufferDescriptor)

Read back SwapChain pixels asynchronously.

fun readPixels(renderTarget: RenderTarget, xoffset: Int, yoffset: Int, width: Int, height: Int, buffer: Texture.PixelBufferDescriptor)

Read back RenderTarget pixels asynchronously.

fun readPixels(xoffset: Int, yoffset: Int, width: Int, height: Int, address: NativePointer, sizeInBytes: Int, format: Texture.Format, type: Texture.Type, stride: Int, onDone: () -> Unit)

readPixels straight into native memory the caller owns, without a copy (e.g. a Skia bitmap's pixels). onDone runs once address holds the frame, possibly on Filament's driver thread.

render

fun render(view: View)

Render a View into this Renderer's target.

renderStandaloneView

fun renderStandaloneView(view: View)

Render a View without frame pacing.

resetUserTime

fun resetUserTime()

Reset the user time clock to zero.

setDesiredPresentationTime

fun setDesiredPresentationTime(monotonicClockNanos: Long)

Set the real desired presentation time targeted for this frame.

setDisplayInfo

fun setDisplayInfo(info: Renderer.DisplayInfo)

Sets display information for frame pacing and dynamic resolution.

setFrameRateOptions

fun setFrameRateOptions(options: Renderer.FrameRateOptions)

Sets frame rate control and dynamic resolution options.

setFrameScheduleTime

fun setFrameScheduleTime(timeSteadyClockNano: Long)

Sets the steady-clock time the frame scheduling callback was entered, so frame pacing can measure the CPU time spent before beginFrame().

setMaterialTimeEpoch

fun setMaterialTimeEpoch(timeEpochInNs: Long)

Set the epoch for material time in nanoseconds.

setPresentationTime

fun setPresentationTime(monotonicClockNanos: Long)

Set the time at which the frame must be presented.

setRenderingDeadline

fun setRenderingDeadline(monotonicClockNanos: Long)

Set the deadline by which CPU and GPU rendering must complete for the buffer to meet its target display latching window. Must be called before endFrame().

setVsyncTime

fun setVsyncTime(steadyClockTimeNano: Long)

Set the VSYNC time expressed as the duration in nanoseconds since epoch of std::chrono::steady_clock.

shouldRenderFrame

fun shouldRenderFrame(): Boolean

Check if the current frame should be rendered.

skipFrame