core

The backend-agnostic scene model: a retained Scene that records vector geometry through a PathContext, flattens curves, groups rings, tessellates fills, expands strokes, and packs everything into GPU-ready buffers with per-drawable color/flag side-tables. HitIndex provides CPU hit-testing over the same data.

import { Scene } from "@mapequation/d3gl";

const scene = new Scene(0.5);
scene.group("shapes", (g) => g.drawable("a", (ctx) => { ctx.rect(0, 0, 10, 10); }));
scene.setFill("shapes", "a", "#3366cc");
const buffers = scene.buffers("shapes"); // GPU-ready typed arrays

Classes

Class	Description
HitIndex	-
PathRecorder	Records PathContext drawing calls into flattened polylines (subpaths). This is the retained-mode capture used by GPU backends: call a d3 generator into a PathRecorder once, then hand the subpaths to the tessellator.
Scene	-

Interfaces

Interface	Description
Backend	A renderer for a Scene, implemented per target (WebGL / Canvas / SVG).
DeclutterScratch	Reusable grid scratch so a per-frame caller (geo declutter runs on every zoom) allocates nothing.
DrawableOpts	-
DrawableRange	Contiguous slice a drawable occupies within a group’s shared buffers.
DrawableVector	-
DrawBatch	Generalized transient pass-through payload (built per repaint, discarded).
FillGeometry	-
GroupBufferDelta	Buffers for an appended TAIL of a group (see Scene.appendedBuffers). Same arrays as GroupBuffers but each holds only the newly-appended data; index values are group-absolute. drawableCount is the total after the append, fromDrawable the index where the new range begins. Point count = pointCenters/4.
GroupBuffers	GPU-ready typed arrays for one group. Vertices are [x, y, drawableId].
GroupBuilder	-
InstancedArrowsData	SoA for a batch of instanced triangle arrowheads (directed-link tips).
InstancedCirclesData	SoA for a batch of instanced circles (e.g. network nodes). Plain typed arrays.
InstancedHalfArrowsData	SoA for a batch of instanced half-arrow links (#104 N6) — the “map of networks” directed-link glyph: one filled shape per link, pinched to the source centre and ending in a barbed arrowhead on the target boundary, bowed around a shared centre curve (see network/half-link.ts). All world units.
InstancedLinesData	SoA for a batch of instanced lines (e.g. network links); straight, or bent via bends.
PassThroughLayer	Identifies a pass-through layer to a backend (no retained geometry).
PathContext	PathContext is the seam of d3gl: the subset of CanvasRenderingContext2D’s path API that d3 path-emitting generators (d3-geo geoPath, d3-shape, d3-chord, d3-hierarchy links) actually call. Implement this once per backend and any of those generators can render to that backend unchanged.
PointBatch	Transient, GPU/Canvas-ready point data. Owned by no one — built per repaint and discarded.
ProjectedPath	One projected path feature, ready to draw. Canvas draws natively; WebGL tessellates per frame.
RenderDelta	An incremental append for one layer: only the drawables added at/after buffers.fromDrawable. buffers are the delta GPU buffers (for WebGL), drawables the matching new vector views (for Canvas/SVG draw-on-top). Index values in buffers are group-absolute, so a backend whose buffers mirror the group appends verbatim. clipTo/sizeMode mirror the layer’s current settings.
RenderLayer	One named layer handed to a backend: GPU buffers + the vector view + optional clip.
RingGroup	One filled polygon: an outer ring plus zero or more hole rings.
StrokeGeometry	-
StrokeOptions	-
StyleTables	Just the per-drawable style tables (colors + flags) as detached typed arrays — O(drawableCount), for styles-only backend updates. Never the O(total-vertices) Scene.buffers rebuild: geometry hasn’t changed, only how it’s painted.
Subpath	A flattened subpath: a polyline plus whether it was closed.
ViewTransform	View transform applied on top of project-once geometry: scale k, translate (x, y).

Type Aliases

Type Alias	Description
DrawItem	What a PassThroughSpec yields per datum (generalizes the point-only project()).
InstancedLayer	A named GPU-instanced primitive layer — the network rendering lane (#100).
LineCap	Open-subpath end-cap style.
LineJoin	Stroke join style.

Variables

Variable	Description
DEFAULT_MITER_LIMIT	Defaults match the Canvas 2D defaults and are pinned identically on Canvas/SVG so the three backends agree. (SVG’s own default miter limit is 4, so it must be set explicitly.)
version	The d3gl package version, injected at build time from package.json.

Functions

Function	Description
declutterScratch	A fresh, empty scratch (grown lazily on first use). Hold one per engine and pass it in to reuse it.
declutterScreen	Greedy screen-space declutter. Visits glyphs in order (importance descending; omitted ⇒ index order) and keeps each unless its centre is within spacing·(rᵢ + rⱼ) of an already-kept glyph — so the drawn circles don’t overlap and the most important glyph in a cluster survives. A glyph whose centre is off-screen is always kept and never occludes others (so panning never culls what’s barely out of view). O(n) via a uniform grid sized to the largest exclusion radius, so any overlapping pair falls in the 3×3 cell neighbourhood.
expandStroke	Expand a polyline into fill triangles for a stroke of the given width.
flattenArc	Circular arc, matching CanvasRenderingContext2D.arc semantics.
flattenCubic	Cubic bezier from (x0,y0) to (x3,y3) with control points (x1,y1),(x2,y2).
flattenQuadratic	Quadratic bezier: elevate to cubic and reuse the cubic flattener.
groupRings	Group a flat list of closed rings into filled polygons with holes.
pointInRing	Ray-casting point-in-polygon test against a ring (interleaved x,y).
signedArea	Shoelace signed area of a ring (interleaved x,y). Positive for counter-clockwise winding, negative for clockwise. Magnitude is the area.
tessellateFill	Triangulate filled (closed) subpaths into triangles via earcut.