Backend

A renderer for a Scene, implemented per target (WebGL / Canvas / SVG).

Properties

stylesNeedDrawables?

readonly optional stylesNeedDrawables?: boolean

Whether updateLayerStyles actually renders from its drawables argument (Canvas and SVG repaint from the vector view) vs. only stashing it for export (WebGL draws from the GPU flag/color tables). When false, the engine may omit drawables on hot paths. Absent ⇒ treated as true (safe default: always pass the vector view).

supportsPassThrough?

readonly optional supportsPassThrough?: boolean

Defined in: core/backend.ts:340

True if this backend supports pass-through (canvas/webgl yes, svg no).

textLayerMode?

readonly optional textLayerMode?: "live" | "export-only"

Defined in: core/backend.ts:391

How setTextLayer text is rendered (#219). "live" (default when absent): the backend draws the set on screen (SVG <text> / Canvas fillText), so the engine routes labels away from the HTML overlay and re-pushes them each setTransform. "export-only" (WebGL): the backend only retains the set for toPNG()/toSVG() — the engine must keep its own live label rendering (the HTML overlay) and needs to push the set only when exporting, NOT per transform (zero per-frame cost).

Methods

appendToLayer()?

optional appendToLayer(delta): void

Defined in: core/backend.ts:325

Append-only fast path (optional). Same observable result as a full re-upload, but the backend uploads/draws only the appended tail (delta) — O(new) instead of O(total). Backends that don’t implement it are driven via updateLayer (full re-upload); the engine still calls updateLayer for non-append changes.

Parameters

delta

RenderDelta

Returns

void

destroy()

destroy(): void

Defined in: core/backend.ts:412

Returns

void

drawPassThrough()?

optional drawPassThrough(name, batch, mode): void

Defined in: core/backend.ts:336

Draw a batch into the layer’s accumulation buffer. mode: "replace-first" clears the layer’s buffer first (start of a full repaint), "replace-rest" continues a chunked full repaint without clearing, "append" draws on top (incremental).

Parameters

name

string

batch

DrawBatch

mode

"replace-first" | "replace-rest" | "append"

Returns

void

pickInstanced()?

optional pickInstanced(x, y, exact): number | undefined

Defined in: core/backend.ts:374

GPU-readback pick (#141): resolve a screen point (CSS px) to the topmost pickable instanced link instance by reading its id-encoded colour from an offscreen pick FBO. Returns the decoded instance index (gl_InstanceID within the pickable link layers, which the network emits in edge order), -1 for background (no link), or undefined when unsupported or no pickable layer is registered. exact: false (hover) uses double-buffered async PBO readback — returns the previous pointer position’s result with no GPU pipeline stall; exact: true (click) reads synchronously at (x, y). WebGL-only; other backends omit it (network instanced rendering is WebGL-only).

Parameters

x

number

y

number

exact

boolean

Returns

number | undefined

removeInstancedLayer()?

optional removeInstancedLayer(name): void

Defined in: core/backend.ts:357

Remove an instanced primitive layer by name.

Parameters

name

string

Returns

void

removePassThroughLayer()?

optional removePassThroughLayer(name): void

Defined in: core/backend.ts:329

Remove a pass-through layer.

Parameters

name

string

Returns

void

render()

render(): void

Defined in: core/backend.ts:409

Returns

void

resize()

resize(width, height): void

Defined in: core/backend.ts:408

Resize the rendering surface to a new CSS size (px). Re-reads the device pixel ratio and reconciles the backing buffer / framebuffers; the engine re-pushes layers and re-renders afterwards. A no-op when the size is unchanged.

Parameters

width

number

height

number

Returns

void

setExportLayers()?

optional setExportLayers(layers): void

Defined in: core/backend.ts:401

Export-only vector stash for content this backend draws outside the retained Scene (#200) — the GPU-instanced lanes (network glyphs/links, decluttered plot points). Implemented by the WebGL backend only: the layers are never rendered (the GPU already drew them), they are appended after the retained layers in toSVG so the export shows the same view the screen does. The engine pushes them at export time alone — like the setTextLayer stash, this costs nothing per frame. Replaces the whole set; pass [] to clear. Absent on Canvas/SVG, which have no instanced lanes (those backends draw the same content as retained Scene layers, already in their export).

Parameters

layers

readonly VectorLayer[]

Returns

void

setInstancedLayer()?

optional setInstancedLayer(layer): void

Defined in: core/backend.ts:346

Register/replace a GPU-instanced primitive layer (the network rendering lane). Optional — only the WebGL backend implements it; other backends omit it, so network instanced rendering is WebGL-only (small-N / export go through the PathContext emitter).

Parameters

layer

InstancedLayer

Returns

void

setLayers()

setLayers(layers): void

Defined in: core/backend.ts:285

Parameters

layers

RenderLayer[]

Returns

void

setPassThroughLayer()?

optional setPassThroughLayer(layer): void

Defined in: core/backend.ts:327

Parameters

layer

PassThroughLayer

Returns

void

setTextLayer()?

optional setTextLayer(texts): void

Defined in: core/backend.ts:383

Set the screen-space text labels to draw on top of the scene (#105 N7b-2). Optional — the SVG (<text>) and Canvas (fillText) backends implement it and render the set live, so the engine routes labels here (instead of the HTML overlay) and they appear in toSVG()/toPNG(). The WebGL backend implements it as an export-only stash (see textLayerMode): the set is retained for toPNG()/toSVG() but never drawn to screen — the engine keeps the HTML overlay live and pushes the placed set only at export time (#219). Replaces the whole set; pass [] to clear.

Parameters

texts

readonly TextData[]

Returns

void

setTransform()

setTransform(t): void

Defined in: core/backend.ts:402

Parameters

t

ViewTransform

Returns

void

snapshotPassThrough()?

optional snapshotPassThrough(): void

Defined in: core/backend.ts:338

Snapshot current accumulation for snapshot-pan (called on interaction start).

Returns

void

styleInstancedLayer()?

optional styleInstancedLayer(name, highlight): void

Defined in: core/backend.ts:364

Shader-driven selection/hover styling for an instanced layer (#162) — applies the highlight WITHOUT rebuilding geometry, so a hover is just a uniform change (no CPU rebuild, no GPU re-upload) even on a full-graph (LOD-off) draw. Sets the given uniforms; when selected is present, updates only that per-instance flag buffer. No-op when the layer/backend doesn’t support it. WebGL-only.

Parameters

name

string

highlight

InstancedHighlight

Returns

void

toPNG()

toPNG(): string

Defined in: core/backend.ts:410

Returns

string

toSVG()

toSVG(): string

Defined in: core/backend.ts:411

Returns

string

updateInstancedLayer()?

optional updateInstancedLayer(layer): void

Defined in: core/backend.ts:355

Update an instanced layer in place when the primitive supports it, or fall back to destroy+recreate otherwise. Optional — only the WebGL backend implements it; when absent, emitInstancedLane falls back to setInstancedLayer. All four primitive types (circles/lines/arrows/half-arrows) now support in-place update() — falling back to recreate only when a structural property changes (e.g. samples or half flag on arrows/lines) or the primitive type itself changes.

Parameters

layer

InstancedLayer

Returns

void

updateLayer()

updateLayer(name, layer): void

Defined in: core/backend.ts:286

Parameters

name

string

layer

RenderLayer

Returns

void

updateLayerFlags()?

optional updateLayerFlags(name, flags): void

Defined in: core/backend.ts:318

Flags-only fast path (optional): ONLY the per-drawable visibility flags changed — colours and geometry did not (the per-frame declutter show/hide, #208). flags is a LIVE view of the Scene’s persistent flags table (one byte per drawable, drawableId- indexed, bit 0 = visible), passed by REFERENCE: the caller allocates and copies nothing per frame, and the view’s contents stay current until the layer’s drawable set changes — which always reaches the backend as a setLayers/updateLayer/ appendToLayer call first. Backends must not mutate it. Backends without this method are driven through the updateLayerStyles path (full tables).

Parameters

name

string

flags

Uint8Array

Returns

void

updateLayerStyles()?

optional updateLayerStyles(name, tables, drawables?): void

Defined in: core/backend.ts:300

Styles-only fast path (optional): the per-drawable color/flag tables changed but geometry did not (recolor / dim / show-hide). drawables is the refreshed vector view (same drawables, same order) so vector-reading consumers (Canvas redraw, SVG serialize, toSVG export) stay in sync with the raster output. Backends without it are driven through updateLayer (full re-upload).

drawables may be omitted (undefined): the caller does this on a backend that doesn’t render from the vector view (see stylesNeedDrawables) to skip an O(n) rebuild on a hot path (e.g. per-frame declutter). Such a backend must keep its previously-stored vector view; consumers that read it (e.g. toSVG) may then lag the tables until the next update that does pass drawables.

Parameters

name

string

tables

StyleTables

drawables?

DrawableVector[]

Returns

void