Renderer · interface

FrameTimer

What a frame timer has to answer, with no backend in the question.

interface FrameTimer

import type { FrameTimer } from '@driftengine/core';

In depth

GpuTimer is built on WebGLQuery and the EXT_disjoint_timer_query_webgl2 extension, which most mobile browsers do not have. WebGPU answers the same question through timestamp queries, with a different shape and a different availability story again. So the shared surface takes the question rather than either answer.

null from lastFrameMs means unmeasured, not free. Reporting a confident 0.0 is the worst number available to invent: a frame meter that reads zero where it cannot measure makes the GPU look idle exactly when somebody is trying to find out why it is not, which is the failure that cost thirteen milliseconds a frame for six weeks (AGENTS.md, 2026-08-07). An honest absence is what lets a reader distinguish "fast" from "unknown".

Properties

Name	Type	Description
`available`readonly	`boolean`	Whether this timer can measure at all on the device in front of it.
`sampling`readonly	`boolean`	Whether the frame being drawn is one of the sampled ones.

Methods

`beginFrame`

beginFrame(): boolean

Whether this frame is measured. Called once per frame, before any begin.

The brackets are on this interface rather than under it, because their names are the engine's own passes and not WebGL's. shadows, reflection and rest describe what this renderer draws, so a second backend measuring the same frame owes the same three numbers; what differs between the APIs is only how the measurement is taken.

`endFrame`

endFrame(): void

Close the frame and queue it for reading.

`begin`

begin(slot: GpuSlot): void

Open a bracket. Never two at once.

Parameter	Type	Description
`slot`	`GpuSlot`

`end`

end(): void

Close the open bracket.

`poll`

poll(): GpuSample | null

The oldest finished sample, or null. Never blocks: a diagnostic that stalls the pipeline in order to measure it is measuring itself.

`lastFrameMs`

lastFrameMs(): number | null

Milliseconds the GPU spent on the most recently resolved frame, or null.

Resolved rather than current: results arrive some frames after the work, because reading them back any sooner would stall the pipeline the timer exists to observe.

`dispose`

dispose(): void

Release whatever the timer holds.