@chromatic-coherence/generative-engine 1.1.0 → 1.3.0

package/dist/world.d.ts

@@ -88,6 +88,14 @@ export declare class World {
     private pPt;
     private pRib;
     private pDepth;
+    private pFaceI;
+    private pDepthI;
+    private instanced;
+    /** W9 — the one wind that blows through every swaying instanced batch */
+    wind: {
+        dir: V3;
+        speed: number;
+    };
     private post;
     private ink;
     private bg;
@@ -171,6 +179,20 @@ export declare class World {
     };
     /** FXAA on the final composite */
     fxaa: boolean;
+    /** depth of field (W8) — blur grows with distance from the focus plane (world units) */
+    dof: {
+        on: boolean;
+        focus: number;
+        range: number;
+        maxBlur: number;
+    };
+    /** camera motion blur (W8) — depth reprojection into the previous frame's view */
+    motionBlur: {
+        on: boolean;
+        strength: number;
+    };
+    private prevVP;
+    private prevVPValid;
     private groupIdx;
     private groupAlpha;
     private groupTarget;
@@ -223,6 +245,17 @@ export declare class World {
     private pushRibbon;
     /** A static ribbon stroke — real pixel width, feathered edges, depth-tested. */
     ribbon(pts: V3[], o: RibbonOpts): void;
+    /** W8 — GPU instancing: upload a Mesh ONCE and draw it at every given transform in a
+     *  single instanced call (scene + shadow pass alike). A forest is one draw. Instances
+     *  ride their group's fade / morph / transform like any other geometry. */
+    meshInstanced(geo: Mesh, instances: (M4 | TransformSpec)[], o: FaceOpts & {
+        /** W9 GPU wind: per-instance sway computed in the vertex stage (shadows included).
+         *  amp scales with vertex height; freq in rad/s; phases auto-scatter per instance. */
+        sway?: {
+            amp: number;
+            freq?: number;
+        };
+    }): void;
     grow(fn: GrowFn): void;
     drawLine(a: V3, b: V3, color: string, alpha: number, width?: number): void;
     drawPath(pts: {
@@ -250,6 +283,10 @@ export declare class World {
     private drawLines;
     private drawPts;
     private drawRibbons;
+    /** Instanced records under a given program (scene or depth pass). Divisors are reset
+     *  after each draw — attribute divisor is global-per-index state and would otherwise
+     *  poison the non-instanced draws that share those indices. */
+    private drawInstancedAll;
     private renderFrame;
     private frameFn;
     private pausedByUser;

package/dist/world.js

@@ -3,8 +3,8 @@
 // WebGL2 renderer: HDR scene target + post chain (bloom, SSAO, composite, FXAA),
 // hardware-PCF depth-texture shadows, per-group transforms + morph targets in the
 // vertex stage, mesh + ribbon primitives. Zero third-party imports, on purpose.
-import { v3, add, sub, scale, cross, norm, clamp, hsl, mIdent, mPerspective, mLookAt, mMul, mCompose, normalMat3, } from "./math.js";
-import { FACE_VS, FACE_FS, DEPTH_VS, DEPTH_FS, LINE_VS, LINE_FS, PT_VS, PT_FS, RIBBON_VS, RIBBON_FS, } from "./shaders.js";
+import { v3, add, sub, scale, cross, norm, clamp, hsl, mIdent, mPerspective, mLookAt, mMul, mCompose, mInvert, normalMat3, } from "./math.js";
+import { FACE_VS, FACE_FS, DEPTH_VS, DEPTH_FS, LINE_VS, LINE_FS, PT_VS, PT_FS, RIBBON_VS, RIBBON_FS, FACE_INST_VS, DEPTH_INST_VS, } from "./shaders.js";
 import { PInfo, PostChain } from "./post.js";
 const FACE_STRIDE = 18; // pos3 norm3 rgb3 gloss1 blood1 grp1 pos2:3 norm2:3
 const LINE_STRIDE = 8; // pos3 col4 grp1
@@ -33,6 +33,9 @@ export class World {
         this.groupNM.set(normalMat3(mat), i * 9);
     }
     constructor(o) {
+        this.instanced = [];
+        /** W9 — the one wind that blows through every swaying instanced batch */
+        this.wind = { dir: v3(1, 0, 0.35), speed: 1 };
         this.ink = false;
         this.bg = [0.024, 0.016, 0.055];
         this.transparent = false;
@@ -84,6 +87,12 @@ export class World {
         this.ssao = { on: true, strength: 0.55, radius: 22 };
         /** FXAA on the final composite */
         this.fxaa = true;
+        /** depth of field (W8) — blur grows with distance from the focus plane (world units) */
+        this.dof = { on: false, focus: 700, range: 420, maxBlur: 10 };
+        /** camera motion blur (W8) — depth reprojection into the previous frame's view */
+        this.motionBlur = { on: false, strength: 0.6 };
+        this.prevVP = mIdent();
+        this.prevVPValid = false;
         // groups: fade alpha + morph weight + transform, resolved in the vertex stage
         this.groupIdx = new Map([["default", 0]]);
         this.groupAlpha = new Float32Array(8).fill(1);
@@ -156,6 +165,8 @@ export class World {
         this.pPt = new PInfo(gl, PT_VS, PT_FS);
         this.pRib = new PInfo(gl, RIBBON_VS, RIBBON_FS);
         this.pDepth = new PInfo(gl, DEPTH_VS, DEPTH_FS);
+        this.pFaceI = new PInfo(gl, FACE_INST_VS, FACE_FS);
+        this.pDepthI = new PInfo(gl, DEPTH_INST_VS, DEPTH_FS);
         this.post = (o.post ?? true) && !this.transparent ? new PostChain(gl) : null;
         this.shadowsOn = !!o.shadows;
         if (o.shadows && typeof o.shadows === "object") {
@@ -371,6 +382,35 @@ export class World {
     }
     /** A static ribbon stroke — real pixel width, feathered edges, depth-tested. */
     ribbon(pts, o) { this.pushRibbon(this.sRib, pts, o); this.staticDirty = true; }
+    /** W8 — GPU instancing: upload a Mesh ONCE and draw it at every given transform in a
+     *  single instanced call (scene + shadow pass alike). A forest is one draw. Instances
+     *  ride their group's fade / morph / transform like any other geometry. */
+    meshInstanced(geo, instances, o) {
+        if (!instances.length)
+            return;
+        const gl = this.gl;
+        const store = [];
+        const P = geo.pos, N = geo.nrm;
+        for (let i = 0; i < P.length; i += 9) {
+            this.pushFace(store, v3(P[i], P[i + 1], P[i + 2]), v3(P[i + 3], P[i + 4], P[i + 5]), v3(P[i + 6], P[i + 7], P[i + 8]), o, v3(N[i], N[i + 1], N[i + 2]), v3(N[i + 3], N[i + 4], N[i + 5]), v3(N[i + 6], N[i + 7], N[i + 8]));
+        }
+        const mats = new Float32Array(instances.length * 20); // mat4 + sway vec4, one stride
+        instances.forEach((m, i) => {
+            mats.set(m instanceof Float32Array ? m : mCompose(m), i * 20);
+            const ph = ((i * 2654435761) % 6283) / 1000; // scattered phase
+            mats[i * 20 + 16] = ph;
+            mats[i * 20 + 17] = (o.sway?.freq ?? 1.3) * (0.85 + ((i * 97) % 30) / 100);
+            mats[i * 20 + 18] = (o.sway?.amp ?? 0) * 0.01;
+            mats[i * 20 + 19] = 0;
+        });
+        const vbuf = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, vbuf);
+        gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(store), gl.STATIC_DRAW);
+        const ibuf = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, ibuf);
+        gl.bufferData(gl.ARRAY_BUFFER, mats, gl.STATIC_DRAW);
+        this.instanced.push({ vbuf, ibuf, verts: store.length / FACE_STRIDE, count: instances.length });
+    }
     grow(fn) { this.hooks.push(fn); }
     // ── the living verbs (gathered per frame) ──
     drawLine(a, b, color, alpha, width = 1) {
@@ -563,11 +603,53 @@ export class World {
         this.attrib(this.pRib, "aGrp", 1, RIB_STRIDE, 15);
         gl.drawArrays(gl.TRIANGLES, 0, verts);
     }
+    /** Instanced records under a given program (scene or depth pass). Divisors are reset
+     *  after each draw — attribute divisor is global-per-index state and would otherwise
+     *  poison the non-instanced draws that share those indices. */
+    drawInstancedAll(p, depthOnly) {
+        if (!this.instanced.length)
+            return;
+        const gl = this.gl;
+        for (const rec of this.instanced) {
+            gl.bindBuffer(gl.ARRAY_BUFFER, rec.vbuf);
+            this.attrib(p, "aPos", 3, FACE_STRIDE, 0);
+            if (!depthOnly) {
+                this.attrib(p, "aNorm", 3, FACE_STRIDE, 3);
+                this.attrib(p, "aCol", 4, FACE_STRIDE, 6);
+                this.attrib(p, "aBlood", 1, FACE_STRIDE, 10);
+            }
+            this.attrib(p, "aGrp", 1, FACE_STRIDE, 11);
+            this.attrib(p, "aPos2", 3, FACE_STRIDE, 12);
+            if (!depthOnly)
+                this.attrib(p, "aNorm2", 3, FACE_STRIDE, 15);
+            gl.bindBuffer(gl.ARRAY_BUFFER, rec.ibuf);
+            const locs = [];
+            for (let k = 0; k < 5; k++) { // aI0..3 = the matrix, aIP = the sway params
+                const loc = gl.getAttribLocation(p.prog, k < 4 ? "aI" + k : "aIP");
+                if (loc < 0)
+                    continue;
+                gl.enableVertexAttribArray(loc);
+                gl.vertexAttribPointer(loc, 4, gl.FLOAT, false, 80, k * 16);
+                gl.vertexAttribDivisor(loc, 1);
+                locs.push(loc);
+            }
+            gl.drawArraysInstanced(gl.TRIANGLES, 0, rec.verts, rec.count);
+            for (const loc of locs)
+                gl.vertexAttribDivisor(loc, 0);
+        }
+    }
     // ── the frame ──
     renderFrame(t, dt) {
         const gl = this.gl;
         this.lastT = t;
+        if (this.motionBlur.on && this.prevVPValid)
+            this.prevVP = new Float32Array(this.vp);
         this.setupCamera(t, dt);
+        if (this.motionBlur.on && !this.prevVPValid) {
+            // first blurred frame: previous = current, so velocity is zero (no identity streak)
+            this.prevVP = new Float32Array(this.vp);
+            this.prevVPValid = true;
+        }
         this.fLight.length = 0;
         this.fRib.length = 0;
         this.dFaceA.length = 0;
@@ -640,6 +722,14 @@ export class World {
                 gl.bindBuffer(gl.ARRAY_BUFFER, this.bFaceD);
                 this.depthDraw(this.bFaceD, this.dFaceA.length / FACE_STRIDE);
             }
+            if (this.instanced.length) {
+                this.pDepthI.use();
+                gl.uniformMatrix4fv(this.pDepthI.u("uVP"), false, this.svp);
+                gl.uniform1f(this.pDepthI.u("uT"), t * this.wind.speed);
+                gl.uniform3f(this.pDepthI.u("uWindDir"), this.wind.dir.x, this.wind.dir.y, this.wind.dir.z);
+                this.setGroups(this.pDepthI);
+                this.drawInstancedAll(this.pDepthI, true);
+            }
             gl.bindFramebuffer(gl.FRAMEBUFFER, null);
         }
         // the scene pass — into the HDR target when the post chain is on
@@ -664,6 +754,14 @@ export class World {
         this.drawFaces(this.bFace, this.sFace.length / FACE_STRIDE, null);
         if (this.dFaceA.length)
             this.drawFaces(this.bFaceD, this.dFaceA.length / FACE_STRIDE, new Float32Array(this.dFaceA));
+        if (this.instanced.length) {
+            this.pFaceI.use();
+            this.setVP(this.pFaceI);
+            this.setLights(this.pFaceI, fogK);
+            gl.uniform1f(this.pFaceI.u("uT"), t * this.wind.speed);
+            gl.uniform3f(this.pFaceI.u("uWindDir"), this.wind.dir.x, this.wind.dir.y, this.wind.dir.z);
+            this.drawInstancedAll(this.pFaceI, false);
+        }
         // the light — additive, depth-TESTED but not written (ink: normal alpha blend)
         gl.depthMask(false);
         gl.enable(gl.BLEND);
@@ -701,6 +799,9 @@ export class World {
                 ssaoOn: this.ssao.on, ssaoStrength: this.ssao.strength, ssaoRadius: this.ssao.radius,
                 filmic: this.filmic && !this.ink, grade: this.grade, vignette: this.vignette, ink: this.ink,
                 fxaa: this.fxaa, near: this.zNear, far: this.zFar,
+                dofOn: this.dof.on, dofFocus: this.dof.focus, dofRange: this.dof.range, dofMaxBlur: this.dof.maxBlur,
+                moOn: this.motionBlur.on, moStrength: this.motionBlur.strength,
+                invVP: this.motionBlur.on ? mInvert(this.vp) : undefined, prevVP: this.prevVP,
             });
         }
         // labels — 2D overlay, never occluded (the honest exception)
@@ -784,6 +885,11 @@ export class World {
             c();
         this.cleanup = [];
         this.overlay.remove();
+        for (const rec of this.instanced) {
+            this.gl.deleteBuffer(rec.vbuf);
+            this.gl.deleteBuffer(rec.ibuf);
+        }
+        this.instanced = [];
         this.post?.dispose();
         if (releaseContext)
             this.gl.getExtension("WEBGL_lose_context")?.loseContext();

package/package.json

@@ -1,44 +1,44 @@
-{
-  "name": "@chromatic-coherence/generative-engine",
-  "version": "1.1.0",
-  "description": "THE THIRD ENGINE — a zero-dependency WebGL2 graphics engine grown from generative-charts-3d: HDR + bloom + SSAO post chain, hardware-PCF shadow maps, a geometry stdlib, ribbon strokes, group transforms and morph targets. The charts API rides on top unchanged.",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "sideEffects": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "node test/run.mjs",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "3d",
-    "webgl2",
-    "engine",
-    "graphics",
-    "bloom",
-    "ssao",
-    "shadows",
-    "zero-dependency"
-  ],
-  "author": "Chromatic Coherence",
-  "license": "SEE LICENSE IN LICENSE",
-  "devDependencies": {
-    "typescript": "^5"
-  }
-}
+{
+  "name": "@chromatic-coherence/generative-engine",
+  "version": "1.3.0",
+  "description": "THE THIRD ENGINE — a zero-dependency WebGL2 graphics engine grown from generative-charts-3d: HDR + bloom + SSAO post chain, hardware-PCF shadow maps, a geometry stdlib, ribbon strokes, group transforms and morph targets. The charts API rides on top unchanged.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node test/run.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "3d",
+    "webgl2",
+    "engine",
+    "graphics",
+    "bloom",
+    "ssao",
+    "shadows",
+    "zero-dependency"
+  ],
+  "author": "Chromatic Coherence",
+  "license": "SEE LICENSE IN LICENSE",
+  "devDependencies": {
+    "typescript": "^5"
+  }
+}