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:455

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

textLayerMode?

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

Defined in: core/backend.ts:520

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:440

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:541

Returns

void

drawPassThrough()?

optional drawPassThrough(name, batch, mode): void

Defined in: core/backend.ts:451

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

orderInstancedLayers()?

optional orderInstancedLayers(names): void

Defined in: core/backend.ts:478

Move the named instanced layers, in this order, after every other instanced layer (the draw order), with no GPU work — so a lane whose set of layers changed keeps the ones that persist (and their uploaded data) rather than recreating them to re-establish its order. Optional; without it the engine recreates the lane’s layers.

Parameters

names

readonly string[]

Returns

void

pickInstanced()?

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

Defined in: core/backend.ts:495

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:472

Remove an instanced primitive layer by name.

Parameters

name

string

Returns

void

removePassThroughLayer()?

optional removePassThroughLayer(name): void

Defined in: core/backend.ts:444

Remove a pass-through layer.

Parameters

name

string

Returns

void

render()

render(): void

Defined in: core/backend.ts:538

Returns

void

renderOverlays()?

optional renderOverlays(): void

Defined in: core/backend.ts:401

Repaint only the overlays set by setOverlays. Both are implemented together or not at all.

Returns

void

resize()

resize(width, height): void

Defined in: core/backend.ts:537

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:530

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

setHoverText()?

optional setHoverText(hover): void

Defined in: core/backend.ts:512

The one-label hover slot (#496), optional: show hover in full over the placed labels, or clear it (null). O(1) in the placed labels: the placed set is not re-pushed and not re-serialized. SVG writes one dedicated element; Canvas paints the chip and text over the live canvas and restores the small rectangle under them on clear (no repaint of the scene). Not called on an export-only text backend (WebGL: the HTML overlay shows the hovered label).

Parameters

hover

HoverText | null

Returns

void

setInstancedLayer()?

optional setInstancedLayer(layer): void

Defined in: core/backend.ts:461

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:388

Parameters

layers

RenderLayer[]

Returns

void

setOverlays()?

optional setOverlays(layers): void

Defined in: core/backend.ts:399

The highlight-overlay slot (#519), optional: the engine’s hover/highlight() overlays, kept apart from setLayers’ scene layers so a hover change repaints only them. A backend that has it is handed the overlays here (never in setLayers) and draws them after the scene on every render(); renderOverlays repaints only the overlays (Canvas puts back the pixels kept under the old ones and keeps the rectangle under the new; SVG rewrites one group), O(overlay drawables) instead of O(scene). toSVG() exports them after the scene layers, as WebGL’s export of its overlay layers does. WebGL leaves it unimplemented: its overlays are ordinary layers re-uploaded in place (#218) and a frame redraws everything anyway.

Parameters

layers

readonly RenderLayer[]

Returns

void

setPassThroughLayer()?

optional setPassThroughLayer(layer): void

Defined in: core/backend.ts:442

Parameters

layer

PassThroughLayer

Returns

void

setTextLayer()?

optional setTextLayer(texts): void

Defined in: core/backend.ts:504

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:531

Parameters

t

ViewTransform

Returns

void

snapshotPassThrough()?

optional snapshotPassThrough(): void

Defined in: core/backend.ts:453

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

Returns

void

styleInstancedLayer()?

optional styleInstancedLayer(name, highlight): void

Defined in: core/backend.ts:485

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:539

Returns

string

toSVG()

toSVG(): string

Defined in: core/backend.ts:540

Returns

string

updateInstancedLayer()?

optional updateInstancedLayer(layer): void

Defined in: core/backend.ts:470

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:389

Parameters

name

string

layer

RenderLayer

Returns

void

updateLayerFlags()?

optional updateLayerFlags(name, flags): void

Defined in: core/backend.ts:433

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:415

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