RefreshFrameSource

Where an Environment's Refresh frames come from: the frames its platform draws, each with its time. Core builds the Clock from it (Clock.layer), and a binding's flush of a write made outside an animation's tick asks it for a frame too, so both run on the same frames and no binding asks the platform itself. @wardic/dom provides its platform's; a native or a canvas Environment provides its own pair.

import * as RefreshFrameSource from "@wardic/core/RefreshFrameSource"

const source = RefreshFrameSource.layer({
  requestFrame: (callback) => platform.nextFrame(callback),
  cancelFrame: (handle) => platform.cancelFrame(handle),
})

Classes

RefreshFrameSource

The Environment's Refresh frame source.

Extends

Context.Service<RefreshFrameSource, Shape<unknown>>

Interfaces

Shape

A Refresh frame source. Handle is whatever requestFrame gives; the service's is unknown. Every source keeps three rules:

It calls back later, never inside requestFrame itself. The Clock asks for each next frame from inside the current one's callback and doesn't yield in between, so a source that answered at once would spin.
A frame's callbacks run in the order they were asked for. A binding's flush asks for a frame of its own only for a write made outside a tick: asked for before the Clock's next frame, as a drag's move is, it runs first, on every Environment.
A callback asked for while a frame's callbacks run waits for the next frame.

Core calls requestFrame and cancelFrame detached, never as source.requestFrame(cb), so a source doesn't rely on this.

Type Parameters

Handle

Handle = unknown

Properties

cancelFrame

readonly cancelFrame: (handle) => void;

Withdraws a call asked for and not yet made.

Parameters

handle

Handle

Returns

void

now?

readonly now?: () => number;

The Environment's steady clock, in ms on the same timebase as the frames' times. The Clock reads it to time a frame whose time repeats the one before, as some platforms' do right after an input. Defaults to performance.now().

Returns

number

requestFrame

readonly requestFrame: (callback) => Handle;

Asks for one call of callback at the next frame, with the frame's time in ms.

function layer(source): Layer<RefreshFrameSource>;

A Layer that provides source as the Environment's Refresh frame source.

RefreshFrameSource

Classes