@chromatic-coherence/generative-engine 1.0.0

package/dist/world.d.ts

@@ -0,0 +1,263 @@
+import { V3, M4, TransformSpec } from "./math.js";
+import { Mesh } from "./geometry.js";
+export type LineOpts = {
+    hue: number;
+    sat?: number;
+    light?: number;
+    alpha: number;
+    group?: string;
+};
+export type GlowOpts = {
+    hue?: number;
+    white?: boolean;
+    size: number;
+    alpha: number;
+    group?: string;
+};
+export type FaceOpts = {
+    hue: number;
+    sat?: number;
+    light?: number;
+    alpha?: number;
+    group?: string;
+    /** per-face material gloss 0..1 (drives GGX roughness + specular): skin ~0.5, cloth ~0.05 */
+    gloss?: number;
+    /** per-face perfusion 0..1: blood near the surface (ruddiness, subsurface bleed, pulse) */
+    blood?: number;
+};
+export type RibbonOpts = {
+    hue: number;
+    sat?: number;
+    light?: number;
+    alpha: number;
+    /** stroke width in CSS pixels (the whole point of ribbons over gl.LINES) */
+    width: number;
+    group?: string;
+};
+export type PointLight = {
+    p: V3;
+    intensity: number;
+    falloff: number;
+};
+export type Projected = {
+    x: number;
+    y: number;
+    s: number;
+    z: number;
+};
+export type GrowFn = (t: number, dt: number, w: World) => void;
+export type WorldOpts = {
+    canvas: HTMLCanvasElement;
+    maxDpr?: number;
+    drift?: number;
+    parallax?: number;
+    controls?: boolean;
+    /** shadow maps — lights[0] casts. true, or { size (px, default 2048), softness, bias } */
+    shadows?: boolean | {
+        size?: number;
+        softness?: number;
+        bias?: number;
+    };
+    /** "light" renders the same recipe as ink on paper. Default "dark". */
+    theme?: "dark" | "light";
+    /** the engine owns its ground: fog and fades resolve toward this colour.
+     *  "transparent" renders direct-to-canvas with no post chain (legacy compositing). */
+    background?: {
+        hue: number;
+        sat?: number;
+        light?: number;
+    } | "transparent";
+    /** the HDR post chain (bloom + SSAO + composite + FXAA). Default true. */
+    post?: boolean;
+    camera?: {
+        target?: V3;
+        dist?: number;
+        pitch?: number;
+        yaw?: number;
+        fov?: number;
+    };
+};
+export declare class World {
+    private canvas;
+    private gl;
+    private overlay;
+    private og;
+    private opts;
+    private pFace;
+    private pLine;
+    private pPt;
+    private pRib;
+    private pDepth;
+    private post;
+    private ink;
+    private bg;
+    private transparent;
+    private shadowsOn;
+    private shadowSize;
+    private shadowSoft;
+    private shadowBias;
+    private shadowFBO;
+    private shadowTex;
+    private svp;
+    private sFace;
+    private sLine;
+    private sPt;
+    private sRib;
+    private dFaceA;
+    private dLineA;
+    private dPtA;
+    private dRibA;
+    private labels;
+    private bFace;
+    private bLine;
+    private bPt;
+    private bRib;
+    private bFaceD;
+    private bLineD;
+    private bPtD;
+    private bRibD;
+    private staticDirty;
+    private hooks;
+    private raf;
+    private t0;
+    private tPrev;
+    private disposed;
+    private lastT;
+    private cleanup;
+    private fLight;
+    private fRib;
+    cam: {
+        target: V3;
+        dist: number;
+        pitch: number;
+        yawBase: number;
+        yawUser: number;
+        pitchUser: number;
+        distT: number;
+        fov: number;
+    };
+    light: {
+        dir: V3;
+        ambient: number;
+        diffuse: number;
+        signed: boolean;
+    };
+    /** up to 8 point lights; lights[0] casts the shadow map (when shadows are on) */
+    lights: PointLight[];
+    /** per-pixel specular strength (0 = matte); skin catches the light around 0.5 */
+    specular: number;
+    ambientSky: V3;
+    ambientGround: V3;
+    /** filmic tone map (ACES-ish) — runs in the composite pass now */
+    filmic: boolean;
+    /** the colour grade: violet-cool shadows, warm highlights — composite pass */
+    grade: boolean;
+    /** cinematic vignette 0..1 — composite pass (overlay fallback when post is off) */
+    vignette: number;
+    /** the global heartbeat 0..1 — rides the per-face blood */
+    bloodPulse: number;
+    /** HDR bloom — the light-on-dark aesthetic's native glow. Art-directable. */
+    bloom: {
+        on: boolean;
+        threshold: number;
+        knee: number;
+        strength: number;
+    };
+    /** depth-based SSAO — contact shading where surfaces meet */
+    ssao: {
+        on: boolean;
+        strength: number;
+        radius: number;
+    };
+    /** FXAA on the final composite */
+    fxaa: boolean;
+    private groupIdx;
+    private groupAlpha;
+    private groupTarget;
+    private groupMorph;
+    private groupMorphT;
+    private groupMat;
+    private groupNM;
+    private idxFor;
+    /** Fade a named group toward a target alpha — eased per frame. */
+    fade(name: string, target: number): void;
+    /** Blend a named group toward its morph target (meshMorph geometry) — eased per frame. */
+    morph(name: string, target: number): void;
+    /** Set a named group's model transform — a mat4 or a {translate, rotateY, scale...} spec.
+     *  Geometry in the group moves rigidly with NO CPU re-tessellation. */
+    setTransform(name: string, m: M4 | TransformSpec): void;
+    W: number;
+    H: number;
+    private mx;
+    private my;
+    private mxT;
+    private myT;
+    private yawUserT;
+    private pitchUserT;
+    private cx;
+    private rt;
+    private up;
+    private fw;
+    private focal;
+    private vp;
+    private readonly zNear;
+    private readonly zFar;
+    constructor(o: WorldOpts);
+    private wireControls;
+    private resize;
+    private col;
+    private parseCol;
+    private inkCss;
+    private themedCss;
+    private pushFace;
+    /** One static triangle. Pass per-vertex normals for smooth shading; omit for flat. */
+    face(a: V3, b: V3, c: V3, o: FaceOpts, na?: V3, nb?: V3, nc?: V3): void;
+    /** Upload a whole Mesh (geometry.ts builders) as static faces in one call. */
+    mesh(geo: Mesh, o: FaceOpts): void;
+    /** Upload a morph pair: the group's morph weight blends A -> B in the vertex shader.
+     *  The two meshes MUST have identical vertex counts (build them from the same recipe). */
+    meshMorph(geoA: Mesh, geoB: Mesh, o: FaceOpts): void;
+    line(a: V3, b: V3, o: LineOpts): void;
+    glow(p: V3, o: GlowOpts): void;
+    dust(p: V3, alpha: number): void;
+    private pushRibbon;
+    /** A static ribbon stroke — real pixel width, feathered edges, depth-tested. */
+    ribbon(pts: V3[], o: RibbonOpts): void;
+    grow(fn: GrowFn): void;
+    drawLine(a: V3, b: V3, color: string, alpha: number, width?: number): void;
+    drawPath(pts: {
+        p: V3;
+    }[], color: string, alpha: number, width?: number): void;
+    drawGlow(p: V3, hue: number | null, size: number, alpha: number): void;
+    drawLabel(p: V3, text: string, color: string, alpha: number, dy?: number): void;
+    drawFace(a: V3, b: V3, c: V3, o: FaceOpts, na?: V3, nb?: V3, nc?: V3): void;
+    /** A per-frame ribbon stroke — the animated counterpart of ribbon(). */
+    drawRibbon(pts: V3[], o: RibbonOpts): void;
+    /** Screen-space overlay (the 2D label canvas — never occluded). */
+    overlay2d(cb: (g: CanvasRenderingContext2D, w: World) => void): void;
+    private setupCamera;
+    project(p: V3): Projected | null;
+    fog(z: number): number;
+    pick(sx: number, sy: number, planeY?: number): V3 | null;
+    get surface(): HTMLCanvasElement;
+    private setGroups;
+    private setVP;
+    private setFog;
+    private setLights;
+    private attrib;
+    private depthDraw;
+    private drawFaces;
+    private drawLines;
+    private drawPts;
+    private drawRibbons;
+    private renderFrame;
+    start(): void;
+    /** Render one deterministic frame at time t (no loop) — stills, tests, screenshots. */
+    settle(t: number): void;
+    /** Stop the world. `releaseContext: true` also LOSES the GL context immediately —
+     *  browsers cap live contexts per page and reclaim them only at GC, so many-canvas
+     *  pages must release on teardown. A lost context is permanently dead on its canvas:
+     *  a releasing caller must mount a FRESH canvas to build again (React: key it). */
+    dispose(releaseContext?: boolean): void;
+}
+export declare function createWorld(o: WorldOpts): World;