documentation · generative charts api
one shared surface — the same in 2D · CPU and 3D · GPU
Every chart in Generative Charts is a short recipe against this one API. Both renderers speak the same names — createChart, line, glow, grow, the draw* living verbs, and the cam / light / lights controls — so you write a chart once and it runs on whichever renderer the library picks. Zero dependencies; the browser is the whole runtime.
install
the library picks — the recipe doesn't change
# one package, both renderers — CPU (canvas) and GPU (WebGL)
npm install @chromatic-coherence/generative-chartsA canvas and a browser are the whole runtime — no build step, no peer dependencies. Both editions are browser-only, so guard SSR imports.
quick start
the whole shape in a dozen lines
import { createChart, v3 } from "@chromatic-coherence/generative-charts";
// renderer: "auto" (default) — GPU when the browser can, CPU when it can't
const w = createChart({ canvas, controls: true });
// lay static light — batched by colour, no z-buffer
w.line(v3(-100, 0, 0), v3(100, 0, 0), { hue: 265, alpha: 0.5 });
w.glow(v3(0, 0, 0), { hue: 46, size: 40, alpha: 0.8 });
// register life — drawn every frame (this is where live data goes)
w.grow((t, dt, world) => {
world.drawGlow(v3(Math.cos(t) * 80, 0, Math.sin(t) * 80), 210, 12, 0.9);
});
w.start();
console.log(w.mode); // "3d" or "2d" — which renderer you actually gotdesign laws
why there is no z-buffer
the surface
transcribed from the source of truth
The tables below are the full public surface — each entry is a real export of @chromatic-coherence/generative-charts; both renderers speak it.
The maths the engine speaks. V3 is a plain object — no classes, no wrappers.
V3type V3 = { x: number; y: number; z: number }the vector everything speaksv3v3(x?, y?, z?): V3construct a vector (defaults 0,0,0)add / subadd(a: V3, b: V3): V3 · sub(a: V3, b: V3): V3vector sum and differencescalescale(a: V3, s: number): V3scalar multiplydot / crossdot(a, b): number · cross(a, b): V3the productslen / normlen(a): number · norm(a): V3length and unit vector (zero-safe)TAUconst TAU = Math.PI * 2one full turnclamp / lerpclamp(v, lo, hi) · lerp(a, b, u)the two workhorseseaseInOuteaseInOut(u: number): numbercubic ease, both endsrndrnd(i: number, k: number): numberdeterministic pseudo-random in [0,1) — a fixed field that never churns on resizeOne canvas, one World. The library owns the camera, the projection, the fog, the frame loop — and WHICH renderer runs: createChart picks CPU or GPU for you.
createChartcreateChart(opts: ChartOpts): ChartWorldthe self-aware door in — picks the renderer, budgets GPU contexts, falls back per-chartChartOpts.rendererrenderer?: "auto" | "2d" | "3d" = "auto"GPU when available and under budget, CPU otherwise; "3d" prefers GPU but still lands on CPU rather than fail; "2d" forces CPUChartOpts.maxGpumaxGpu?: number = 5page-wide budget of live GPU charts — browsers cap live WebGL contexts, so charts over budget build on the CPU rendererworld.modereadonly mode: "2d" | "3d"which renderer this world actually runs oncreateWorld2d / createWorld3dcreateWorld2d(opts): World2D · createWorld3d(opts): World3Dthe direct doors — reach a specific renderer when you mustWorldOpts.canvascanvas: HTMLCanvasElementthe surface to draw onWorldOpts.maxDprmaxDpr?: number = 1.25device-pixel-ratio cap — resolution is the enemy of 60fps additive canvasWorldOpts.driftdrift?: number = 0.045auto-orbit speed, radians per secondWorldOpts.parallaxparallax?: number = 0.3mouse-parallax strengthWorldOpts.controlscontrols?: boolean = falsedrag-to-orbit + ctrl/cmd-wheel zoom (plain wheel keeps scrolling the page)WorldOpts.themetheme?: "dark" | "light" = "dark"the INK EDITION — "light" renders the same recipe on paper: lightness inverts, the light pass composites as ink (with a density lift for equal weight), fog fades toward the page. Recipes need no changes — both engines, one optionWorldOpts.cameracamera?: { target?, dist?, pitch?, yaw?, fov? }starting camera overridesStatic geometry is BATCHED: colours are quantised (hue to 15°, sat to 25, light to 12, alpha to eighths) so thousands of lines collapse into a handful of strokes.
lineline(a: V3, b: V3, { hue, sat?, light?, alpha, group? })a batched line in HSL — the wireframe workhorseglowglow(p: V3, { hue?, white?, size, alpha, group? })a sprite glow — pre-rendered radial sprites, one per 10° of hue, plus whitedustdust(p: V3, alpha: number)a twinkling grain of screen dustfadefade(name: string, target: number)fade a named group — every line and glow belongs to one; alpha eases toward the targetOpaque surfaces under the additive light — the law bends: the dark occludes; the light still commutes above it. v0.3: two beats. v0.4: a steerable light. v0.5: light is a place; bodies throw shadows. v0.6: the world reflects. v0.7: occlusion complete. v1.0: walkable. Feature-frozen — the GPU edition is the next engine.
mirrorPlanecreateWorld({ …, mirrorPlane: 0, mirrorAlpha?: 0.35 })still water — every face and living light above the plane reflects beneath it, re-shaded at its mirrored place, dimmedpickpick(sx, sy, planeY = 0): V3 | nullscreen point → the ground, through the frame's camera basis — a tap becomes a place (the walkable city runs on it)surfaceget surface(): HTMLCanvasElementthe canvas this world draws on — for scenes that wire their own inputlightsworld.lights.push({ p: V3, intensity, falloff })point lights — Lambert × inverse-square falloff + a facet specular glint toward the camera; steerable per frameshadowPlanecreateWorld({ …, shadowPlane: 0 })every face, static and living, casts onto the plane along lights[0] (or the directional) — near-black fills in the same painter sortlightworld.light = { dir: V3, ambient, diffuse, signed }steerable like cam — faces shade at render time; the default is pixel-identical to the sky shade; signed:true gives true Lambert with a dark sideoccludeLightcreateWorld({ …, occludeLight: true })static glows join the painter sort — the dark can hide them (glows only; lines and living light still ride above)faceface(a: V3, b: V3, c: V3, { hue, sat?, light?, alpha?, group? })a static opaque triangle — painter-sorted far to near each frame, filled before the light passesdrawFacedrawFace(a: V3, b: V3, c: V3, FaceOpts)an opaque triangle that LIVES — laid from a grow hook, gathered into this frame's dark pass, sorted with the static facesslope shadelight × (0.55 + 0.45 · |normal.y|)computed once at lay time — a face is lit by how much it looks at the sky; winding never mattersEverything that lives and changes is a grow hook, called every frame with the world's camera already set up.
growgrow(fn: GrowFn)register a per-frame hookGrowFntype GrowFn = (t: number, dt: number, w: World) => voidseconds since start · seconds since last frame (capped 50ms) · the worldValid inside grow hooks and settle — the per-frame basis is computed before hooks run.
camcam: { target, dist, pitch, yawBase, yawUser, fov, … }public camera state — a scene may steer it live from a hookprojectproject(p: V3): Projected | nullworld to screen — { x, y, s, z }; null behind the near planefogfog(z: number): numberdepth attenuation for a projected zW / HW: number · H: numbercanvas CSS size, live through resizeFor grow hooks: draw this frame, projection- and fog-aware, on top of the batched static world.
drawLinedrawLine(a: V3, b: V3, color: string, alpha: number, width?)one projected linedrawPathdrawPath(pts: { p: V3 }[], color, alpha, width?)a projected polyline — segments break cleanly at the near planedrawGlowdrawGlow(p: V3, hue: number | null, size, alpha)one projected glow — null hue draws the white spritedrawLabeldrawLabel(p: V3, text, color, alpha, dy?)a mono label, composited over the lightoverlayoverlay(cb: (g: CanvasRenderingContext2D, w: World) => void)raw canvas access for screen-space work (voids, vignettes) — never occluded, by designThe loop pauses itself on a hidden tab, and a one-step governor drops resolution and thins the far field if frames slip.
startstart(): voidbegin the requestAnimationFrame loopsettlesettle(t: number): voidone settled frame — the reduced-motion pathcapturePostercapturePoster(opts, build, width, height, t?): string | nullthe window's first frame as a PNG data URL, rendered off-screen with the context released — the placeholder-image pattern: paint the poster at load, build the live chart when watcheddisposedispose(releaseContext?: boolean): voidcancel the loop and remove every listener. On the 3D engine, pass true to also release the WebGL context immediately — browsers cap live contexts per page, so many-chart pages release on teardown and mount a fresh canvas to build again; leave it false to reuse the same canvasstart growing
every chart is a recipe against this API
Every chart on the Generative Charts page is a recipe against this surface — toggle 2D · CPU ↔ 3D · GPU, copy the full code with your data, and make it your own.