Scene

Defined in: core/scene.ts:380

Constructors

Constructor

new Scene(tolerance?): Scene

Defined in: core/scene.ts:383

Parameters

tolerance?

number = DEFAULT_CURVE_TOLERANCE

Returns

Scene

Methods

appendedBuffers()

appendedBuffers(name, fromDrawable): GroupBufferDelta

Defined in: core/scene.ts:809

GPU-ready buffers for ONLY the drawables appended at/after fromDrawable — the tail slices as O(1) views (pointCenters assembled in O(new circles)). A backend whose buffers mirror the group 1:1 (append-only, same order) can apply this by appending: the index values are group-ABSOLUTE (no rebasing), because the new vertices sit at the same positions the group placed them. fromDrawable >= drawableCount yields an empty delta.

Parameters

name

string

fromDrawable

number

Returns

GroupBufferDelta

appendToGroup()

appendToGroup(name, build): void

Defined in: core/scene.ts:403

Append more drawables to an existing group (vs group(), which replaces it). New drawables’ integer drawableIds continue after the existing ones; a duplicate domain id (the caller’s string/number id) throws. NOTE: not atomic across a multi-drawable build — if a later drawable in the batch throws, earlier ones are already committed. Callers needing all-or-nothing (the engine append path) validate ids before calling.

Parameters

name

string

build

(g) => void

Returns

void

buffers()

buffers(name): GroupBuffers

Defined in: core/scene.ts:782

Assemble GPU-ready typed arrays for a group — O(1): every array is a live view of the typed storage, and pointCenters (the one array that has to be interleaved rather than viewed) is built once per drawable set and retained (#280), not re-assembled per call. It used to cost O(pointCount) time plus a fresh 16 B/circle allocation on every pushLayers(); like the vector view it was already retained downstream by every backend, so keeping it here shares one array instead of minting a copy per push. See GroupBuffers for the sharing contract.

Parameters

name

string

Returns

GroupBuffers

declutterIndex()

declutterIndex(name): DeclutterIndex

Defined in: core/scene.ts:624

The DeclutterIndex for a group — the transform-independent anchor grouping used by screen-space declutter. Built once and cached on the group; the per-frame caller projects ax/ay to screen and bins them, so the (string-keyed) grouping never re-runs on a zoom. Invalidated automatically when the group is rebuilt (group) or appended to (appendToGroup).

Parameters

name

string

Returns

DeclutterIndex

drawableCount()

drawableCount(name): number

Defined in: core/scene.ts:418

Number of drawables currently registered in a group.

Parameters

name

string

Returns

number

drawableOf()

drawableOf(name, id): DrawableVector | null

Defined in: core/scene.ts:752

The vector view of ONE drawable by domain id, or null when the id has no drawable (unknown, or culled at build time). O(1) lookup.

Parameters

name

string

id

string | number

Returns

DrawableVector | null

drawables()

drawables(name, from?): DrawableVector[]

Defined in: core/scene.ts:730

The vector view of a group’s drawables — a retained array, built once per drawable set and handed out by reference thereafter (#280).

This used to materialize one fresh DrawableVector (plus two colour tuples) per drawable on every call — ~0.16 µs and ~320 B each, measured at 200k — and BaseEngine.pushLayers() calls it for every layer on every push (each registerLayer, removeLayer, setClip, backend install, and both boundaries of a gesture on a hideOnInteraction map). At 1M drawables that was ~160 ms and ~320 MB of short-lived garbage per push, before any backend saw the result.

Retaining it costs no extra memory: the array is already held for the layer’s lifetime by whichever backend it was pushed to. What goes away is the per-push copy.

Freshness: DrawableVector stores style as plain data (a snapshot), so a setFill/setStroke/ setFlag/writeDeclutterFlags since the last call is re-applied in place here — reusing the same objects and the same colour tuples, so the resync allocates nothing (see syncVectorStyle). Geometry fields never change without a drawable-set change, which drops the array entirely.

Contract for callers: treat the array and its elements as read-only, and do not retain them across a drawable-set change. The one sanctioned mutation is a backend’s flags-only fast path writing flags from this Scene’s own live flags table (CanvasBackend/SvgBackend updateLayerFlags, WebGLBackend.toSVG) — that writes the value this Scene already holds, so it can only bring the view into sync, never diverge from it.

from > 0 asks for just the appended TAIL (O(new)) and always builds fresh objects: the append path hands that slice straight to the backend, which owns and grows it from there.

Parameters

name

string

from?

number = 0

Returns

DrawableVector[]

flagsView()

flagsView(name): Uint8Array

Defined in: core/scene.ts:680

A LIVE typed view of a group’s per-drawable flag bytes (bit 0 = visible): the SAME Uint8Array instance across calls — zero per-call allocation — aliasing the Scene’s typed flags storage directly (#207 made #208’s mirror the primary storage), so the flag writers (setFlag, writeDeclutterFlags) are visible through it with no double-write. Replaced only when the drawable set changes (append grows it; a group rebuild replaces it). This is what the flags-only per-frame path (#208) passes by reference to Backend.updateLayerFlags, instead of the O(9·drawableCount)-bytes styleTables snapshot. Callers must treat it as read-only and must not retain it across drawable-set changes.

Parameters

name

string

Returns

Uint8Array

group()

group(name, build): void

Defined in: core/scene.ts:386

Build (or rebuild) a named group. The callback registers drawables.

Parameters

name

string

build

(g) => void

Returns

void

range()

range(name, id): DrawableRange

Defined in: core/scene.ts:580

The contiguous buffer slice a drawable occupies.

Parameters

name

string

id

string | number

Returns

DrawableRange

remove()

remove(name): void

Defined in: core/scene.ts:393

Drop a group entirely (vs an empty re-group, which keeps a zero-drawable entry).

Parameters

name

string

Returns

void

setFill()

setFill(name, id, color): void

Defined in: core/scene.ts:596

Set a drawable’s fill color (any CSS color string). Hot-swappable.

Parameters

name

string

id

string | number

color

string

Returns

void

setFlag()

setFlag(name, id, flags): void

Defined in: core/scene.ts:611

Set a drawable’s flag byte (e.g. bit 0 = visible). Hot-swappable. Writes the typed storage directly, so any flagsView/styleTables view sees it.

Parameters

name

string

id

string | number

flags

number

Returns

void

setStroke()

setStroke(name, id, color): void

Defined in: core/scene.ts:603

Set a drawable’s stroke color (any CSS color string). Hot-swappable.

Parameters

name

string

id

string | number

color

string

Returns

void

styleTables()

styleTables(name): StyleTables

Defined in: core/scene.ts:766

The per-drawable color/flag tables (see StyleTables) as LIVE views of the group’s typed storage — O(1), zero copies (#207; previously an O(drawableCount) snapshot per call). Later setFill/setStroke/setFlag writes are visible through the views; an append makes them stale (backends always receive the drawable-set change as a setLayers/updateLayer/appendToLayer first). Consumers must not mutate or retain them across drawable-set changes.

Parameters

name

string

Returns

StyleTables

writeDeclutterFlags()

writeDeclutterFlags(name, visibleByGroup): void

Defined in: core/scene.ts:652

Apply a per-anchor-group visibility verdict (1 = keep, 0 = hide) to the flag bytes, in place — one linear pass over the cached DeclutterIndex, with no per-id Map lookups. Drawables with no anchor (groupOf = -1) always stay visible. visibleByGroup is indexed by the same group index as ax/ay. Writes the typed flags storage directly — the flagsView the per-frame path hands to backends aliases it (#208).

Parameters

name

string

visibleByGroup

Uint8Array

Returns

void