@driftengine/core 3.61.0

package/dist/render/bloomPass.js

@@ -0,0 +1,219 @@
+import { BLOOM_DOWNSAMPLE_FRAG, BLOOM_PREFILTER_FRAG, BLOOM_UPSAMPLE_FRAG, } from './shaders/bloom.js';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
+import { compileProgram, uniformLocations } from './shader.js';
+import { BLOOM_FILTER_RADIUS_UV, bloomLevelSizes } from './bloomChain.js';
+/**
+ * The bloom chain: threshold the frame, halve it repeatedly, and add it back up.
+ *
+ * Its own module rather than more of `SceneTarget`, for the same reason `AmbientOcclusionPass`
+ * is: that class owns where the frame lands and how it reaches the canvas, and this owns one
+ * effect's targets and programs. The composite adds the texture this returns and knows nothing
+ * else about it.
+ *
+ * **A pyramid rather than one wide blur.** A gaussian broad enough to look like glare is
+ * hundreds of taps at full resolution. Halving the frame six times and adding the levels back
+ * costs about a third of a full-resolution pass in total, and the sum of the octaves is a
+ * falloff with no end to it, which is what a real glare has and a single kernel does not.
+ */
+export class BloomPass {
+    gl;
+    /** The chain, level 0 at half the frame and each one after it half again. */
+    levels = [];
+    width = 0;
+    height = 0;
+    /**
+     * Set once if a target will not complete, after which this pass does nothing and says so once.
+     *
+     * The alternative to an honest "off" is a frame with a texture nobody wrote added into it,
+     * and the last time an effect here sampled an unwritten target the failure presented as the
+     * driver being at fault. See `sceneTarget.ts`.
+     */
+    unavailable = false;
+    /** Half floats where the part will render to them. See the note in `allocate`. */
+    floatColor;
+    prefilterProgram;
+    prefilterUniforms;
+    downsampleProgram;
+    downsampleUniforms;
+    upsampleProgram;
+    upsampleUniforms;
+    vao;
+    /** Scratch for the source texel size, so a per-frame pass allocates nothing. */
+    texel = new Float32Array(2);
+    constructor(gl) {
+        this.gl = gl;
+        /*
+         * The same extension the scene target asks for, and asked for here too rather than passed
+         * in: a chain of eight-bit levels would clip the very values it exists to spread, so a
+         * threshold above 1 would produce a black bloom on a part that has the extension for the
+         * scene and not for this. Without it the levels are eight-bit and bloom still works on
+         * whatever survives below 1, which is what the scene target itself is doing in that case.
+         */
+        this.floatColor = gl.getExtension('EXT_color_buffer_float') !== null;
+        this.prefilterProgram = compileProgram(gl, FULLSCREEN_VERT, BLOOM_PREFILTER_FRAG, 'bloomPrefilter');
+        this.prefilterUniforms = uniformLocations(gl, this.prefilterProgram, 'bloomPrefilter');
+        this.downsampleProgram = compileProgram(gl, FULLSCREEN_VERT, BLOOM_DOWNSAMPLE_FRAG, 'bloomDownsample');
+        this.downsampleUniforms = uniformLocations(gl, this.downsampleProgram, 'bloomDownsample');
+        this.upsampleProgram = compileProgram(gl, FULLSCREEN_VERT, BLOOM_UPSAMPLE_FRAG, 'bloomUpsample');
+        this.upsampleUniforms = uniformLocations(gl, this.upsampleProgram, 'bloomUpsample');
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('BloomPass: createVertexArray failed');
+        this.vao = vao;
+    }
+    ensureSize(width, height) {
+        if (this.unavailable)
+            return false;
+        if (this.width === width && this.height === height && this.levels.length > 0)
+            return true;
+        const { gl } = this;
+        this.width = width;
+        this.height = height;
+        this.release();
+        /* The shape of the pyramid is shared, so the other backend cannot build a different one. */
+        for (const { width: levelWidth, height: levelHeight } of bloomLevelSizes(width, height)) {
+            const texture = this.allocate(levelWidth, levelHeight);
+            const framebuffer = gl.createFramebuffer();
+            if (texture === null || framebuffer === null)
+                break;
+            gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+            gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+            if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
+                gl.deleteFramebuffer(framebuffer);
+                gl.deleteTexture(texture);
+                break;
+            }
+            this.levels.push({ texture, framebuffer, width: levelWidth, height: levelHeight });
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        if (this.levels.length === 0) {
+            this.unavailable = true;
+            console.warn('BloomPass: no level of the chain would allocate, so bloom is off. The frame itself ' +
+                'is unaffected.');
+            return false;
+        }
+        return true;
+    }
+    allocate(width, height) {
+        const { gl } = this;
+        const texture = gl.createTexture();
+        if (texture === null)
+            return null;
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        /*
+         * `RGBA16F` where it is renderable. Half floats are filterable in WebGL2 without an
+         * extension — it is *rendering* to them that needs `EXT_color_buffer_float` — so linear
+         * filtering below is safe either way.
+         */
+        if (this.floatColor) {
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, width, height, 0, gl.RGBA, gl.HALF_FLOAT, null);
+        }
+        else {
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+        }
+        /* Linear, because every stage samples between texels on purpose: that is where the spread
+           comes from, and NEAREST here would show the pyramid as blocks. */
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        /* Clamped, or a tap past the edge pulls the opposite side of the screen into the corner —
+           and at the deepest level, where one texel is a large part of the frame, that is a bright
+           smear from somewhere the viewer is not looking. */
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        return texture;
+    }
+    /**
+     * Build the frame's bloom. Returns the texture to add, or null if this pass could not run,
+     * which the caller must read as "no bloom" rather than as black.
+     *
+     * `threshold` is in scene units, so it only separates a light from white paint on a target
+     * that kept the range. The caller owns that decision and the warning that goes with it.
+     */
+    run(scene, width, height, threshold) {
+        if (!this.ensureSize(width, height))
+            return null;
+        const { gl } = this;
+        const levels = this.levels;
+        const top = levels[0];
+        if (top === undefined)
+            return null;
+        /* One triangle over targets with no depth attachment. Anything inherited from the scene
+           pass would be tested against a buffer that is not there. */
+        gl.disable(gl.DEPTH_TEST);
+        gl.disable(gl.BLEND);
+        gl.disable(gl.CULL_FACE);
+        gl.depthMask(false);
+        gl.bindVertexArray(this.vao);
+        gl.activeTexture(gl.TEXTURE0);
+        /* Threshold, full resolution into level 0. The only stage that reads the scene. */
+        gl.useProgram(this.prefilterProgram);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, top.framebuffer);
+        gl.viewport(0, 0, top.width, top.height);
+        gl.bindTexture(gl.TEXTURE_2D, scene);
+        gl.uniform1i(this.prefilterUniforms['uSource'] ?? null, 0);
+        gl.uniform1f(this.prefilterUniforms['uThreshold'] ?? null, threshold);
+        this.uploadTexel(this.prefilterUniforms, width, height);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        /* Down the chain. Each level reads the one above it, which was written a draw ago. */
+        gl.useProgram(this.downsampleProgram);
+        gl.uniform1i(this.downsampleUniforms['uSource'] ?? null, 0);
+        for (let index = 1; index < levels.length; index++) {
+            const target = levels[index];
+            const source = levels[index - 1];
+            if (target === undefined || source === undefined)
+                break;
+            gl.bindFramebuffer(gl.FRAMEBUFFER, target.framebuffer);
+            gl.viewport(0, 0, target.width, target.height);
+            gl.bindTexture(gl.TEXTURE_2D, source.texture);
+            this.uploadTexel(this.downsampleUniforms, source.width, source.height);
+            gl.drawArrays(gl.TRIANGLES, 0, 3);
+        }
+        /*
+         * And back up, adding into each level rather than replacing it, so level 0 ends up holding
+         * every octave at once. Additive blending rather than a second target to ping-pong through:
+         * a level is only ever read while a *different* level is bound, so there is no feedback.
+         */
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.ONE, gl.ONE);
+        gl.useProgram(this.upsampleProgram);
+        gl.uniform1i(this.upsampleUniforms['uSource'] ?? null, 0);
+        gl.uniform1f(this.upsampleUniforms['uRadius'] ?? null, BLOOM_FILTER_RADIUS_UV);
+        for (let index = levels.length - 1; index > 0; index--) {
+            const target = levels[index - 1];
+            const source = levels[index];
+            if (target === undefined || source === undefined)
+                break;
+            gl.bindFramebuffer(gl.FRAMEBUFFER, target.framebuffer);
+            gl.viewport(0, 0, target.width, target.height);
+            gl.bindTexture(gl.TEXTURE_2D, source.texture);
+            gl.drawArrays(gl.TRIANGLES, 0, 3);
+        }
+        gl.disable(gl.BLEND);
+        gl.bindVertexArray(null);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        return top.texture;
+    }
+    /** One source texel in UV, which is what the thirteen taps are laid out in. */
+    uploadTexel(uniforms, width, height) {
+        this.texel[0] = 1 / width;
+        this.texel[1] = 1 / height;
+        this.gl.uniform2fv(uniforms['uTexel'] ?? null, this.texel);
+    }
+    release() {
+        const { gl } = this;
+        for (const level of this.levels) {
+            gl.deleteFramebuffer(level.framebuffer);
+            gl.deleteTexture(level.texture);
+        }
+        this.levels.length = 0;
+    }
+    dispose() {
+        const { gl } = this;
+        this.release();
+        gl.deleteProgram(this.prefilterProgram);
+        gl.deleteProgram(this.downsampleProgram);
+        gl.deleteProgram(this.upsampleProgram);
+        gl.deleteVertexArray(this.vao);
+    }
+}

package/dist/render/boltBatch.d.ts

@@ -0,0 +1,39 @@
+import type { BoltSegments } from './boltPool.ts';
+/**
+ * One draw call for a pool of electrical arcs.
+ *
+ * Four vertices per segment rather than instancing, because a segment's two
+ * endpoints *are* its geometry — there is no repeated base shape to instance, and
+ * an instanced version would upload the same two positions per vertex anyway.
+ *
+ * Additive and depth-tested without writing depth, like every other emissive
+ * effect here: an arc adds light to what is behind it and must not occlude
+ * whatever is drawn next.
+ */
+export declare class BoltBatch {
+    readonly program: WebGLProgram;
+    readonly uniforms: Record<string, WebGLUniformLocation>;
+    private readonly vao;
+    private readonly buffers;
+    private readonly fromBuffer;
+    private readonly toBuffer;
+    private readonly arcBuffer;
+    /** Scratch, expanded from the pool's per-segment arrays to per-vertex ones. */
+    private readonly from;
+    private readonly to;
+    private readonly arc;
+    private readonly capacity;
+    constructor(gl: WebGL2RenderingContext, capacity: number, label: string);
+    /**
+     * Send this frame's arcs, expanding each segment to its four vertices.
+     *
+     * The expansion is `segmentQuads.ts`'s because it is a fact about how the geometry is drawn
+     * rather than about GL — the pool is deliberately GL-free and testable, and the WebGPU batch
+     * needs exactly the same four vertices.
+     */
+    upload(gl: WebGL2RenderingContext, data: BoltSegments): number;
+    drawTo(gl: WebGL2RenderingContext, segmentCount: number): void;
+    dispose(gl: WebGL2RenderingContext): void;
+    private dynamic;
+    private staticAttr;
+}

package/dist/render/boltBatch.js

@@ -0,0 +1,121 @@
+import { compileProgram, uniformLocations } from './shader.js';
+import { BOLT_FRAG, BOLT_VERT } from './shaders/bolt.js';
+import { buildSegmentQuads, expandBoltSegments } from './segmentQuads.js';
+/**
+ * One draw call for a pool of electrical arcs.
+ *
+ * Four vertices per segment rather than instancing, because a segment's two
+ * endpoints *are* its geometry — there is no repeated base shape to instance, and
+ * an instanced version would upload the same two positions per vertex anyway.
+ *
+ * Additive and depth-tested without writing depth, like every other emissive
+ * effect here: an arc adds light to what is behind it and must not occlude
+ * whatever is drawn next.
+ */
+export class BoltBatch {
+    program;
+    uniforms;
+    vao;
+    buffers = [];
+    fromBuffer;
+    toBuffer;
+    arcBuffer;
+    /** Scratch, expanded from the pool's per-segment arrays to per-vertex ones. */
+    from;
+    to;
+    arc;
+    capacity;
+    constructor(gl, capacity, label) {
+        this.program = compileProgram(gl, BOLT_VERT, BOLT_FRAG, label);
+        this.uniforms = uniformLocations(gl, this.program, 'boltBatch');
+        this.capacity = capacity;
+        const verts = capacity * 4;
+        this.from = new Float32Array(verts * 3);
+        this.to = new Float32Array(verts * 3);
+        this.arc = new Float32Array(verts * 4);
+        /*
+         * The corner layout and the index list are the only static data: which end of
+         * the segment a vertex sits at, and which side of it. Everything else arrives
+         * per frame. Built in `segmentQuads.ts`, so both backends draw one arc.
+         */
+        const { corners, indices } = buildSegmentQuads(capacity);
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error(`${label}: createVertexArray failed`);
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        this.fromBuffer = this.dynamic(gl, 0, verts * 3, 3, label);
+        this.toBuffer = this.dynamic(gl, 1, verts * 3, 3, label);
+        this.staticAttr(gl, 2, corners, 2, label);
+        this.arcBuffer = this.dynamic(gl, 3, verts * 4, 4, label);
+        const indexBuffer = gl.createBuffer();
+        if (indexBuffer === null)
+            throw new Error(`${label}: createBuffer failed`);
+        this.buffers.push(indexBuffer);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+        gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);
+        gl.bindVertexArray(null);
+    }
+    /**
+     * Send this frame's arcs, expanding each segment to its four vertices.
+     *
+     * The expansion is `segmentQuads.ts`'s because it is a fact about how the geometry is drawn
+     * rather than about GL — the pool is deliberately GL-free and testable, and the WebGPU batch
+     * needs exactly the same four vertices.
+     */
+    upload(gl, data) {
+        const count = expandBoltSegments(data, this.capacity, this.from, this.to, this.arc);
+        if (count === 0)
+            return 0;
+        const verts = count * 4;
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.fromBuffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.from, 0, verts * 3);
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.toBuffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.to, 0, verts * 3);
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.arcBuffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.arc, 0, verts * 4);
+        return count;
+    }
+    drawTo(gl, segmentCount) {
+        if (segmentCount === 0)
+            return;
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        gl.bindVertexArray(this.vao);
+        gl.drawElements(gl.TRIANGLES, segmentCount * 6, gl.UNSIGNED_INT, 0);
+        gl.bindVertexArray(null);
+        gl.enable(gl.CULL_FACE);
+        gl.depthMask(true);
+        gl.disable(gl.BLEND);
+    }
+    dispose(gl) {
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        this.buffers.length = 0;
+        gl.deleteVertexArray(this.vao);
+        gl.deleteProgram(this.program);
+    }
+    dynamic(gl, location, floats, size, label) {
+        const buffer = gl.createBuffer();
+        if (buffer === null)
+            throw new Error(`${label}: createBuffer failed`);
+        this.buffers.push(buffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, floats * 4, gl.DYNAMIC_DRAW);
+        gl.enableVertexAttribArray(location);
+        gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        return buffer;
+    }
+    staticAttr(gl, location, data, size, label) {
+        const buffer = gl.createBuffer();
+        if (buffer === null)
+            throw new Error(`${label}: createBuffer failed`);
+        this.buffers.push(buffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
+        gl.enableVertexAttribArray(location);
+        gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+    }
+}

package/dist/render/boltPool.d.ts

@@ -0,0 +1,135 @@
+import type { Vec3 } from '../math/color.ts';
+/**
+ * A pool of short-lived electrical arcs — lightning, and anything else that
+ * strikes between two points and crackles while it lasts.
+ *
+ * The simulation half only, exactly like `ParticlePool`: this class holds no GL
+ * resources, so it is testable without a context, and the drawing lives in
+ * `BoltBatch` where the standing rule says WebGL belongs. What comes out is a
+ * flat array of *segment endpoints*, which is the one thing a ribbon of quads
+ * needs and the one thing a caller can check.
+ *
+ * **It advances rather than evaluates, so it is for real-time scenes only.** `update(dt)` steps
+ * an internal cursor, which means the same plan stepped by two different sequences of `dt`
+ * produces different arcs. A consumer that renders one plan twice, once against a wall clock for
+ * a preview and once against a frame index for an export, cannot make the two agree. Reported
+ * from outside, alongside the observation that `PlumeRenderer.draw` has the signature that does
+ * work: it takes the time to *evaluate at* rather than a step to advance by, so the same second
+ * draws the same smoke however the frames were spaced. A stateless variant here is not built.
+ *
+ * A bolt is a jagged polyline between its two ends, and the jaggedness is
+ * **re-drawn while it lives** rather than animated. That is what separates
+ * lightning from a wire: real arcs do not bend smoothly, they are replaced, many
+ * times a second, by a different path between the same two points. Interpolating
+ * node positions produces a wobbling snake, which reads as a rope or a tentacle;
+ * re-striking produces the crackle.
+ *
+ * Displacement is mid-point subdivision, seeded, so a replay strikes the same
+ * bolts the run did. Nothing here reads a clock or `Math.random`.
+ */
+export interface BoltPoolOptions {
+    /** How many arcs may be alive at once. */
+    capacity: number;
+    /**
+     * Nodes per arc, both ends included. Must be `2^k + 1` so mid-point
+     * subdivision lands exactly on it; anything else is rounded up to the next.
+     */
+    nodes: number;
+    /** Seconds an arc lives. */
+    lifeSec: number;
+    /** How far a node may wander off the straight line, as a share of the span. */
+    jitter: number;
+    /** How many times a second a live arc re-draws its path. */
+    restrikeHz: number;
+}
+/** One arc's worth of geometry, as the caller reads it back. */
+/**
+ * The arcs a batch draws, as plain arrays with a live count.
+ *
+ * **Fillable from outside, and that is the answer to wanting bolts without a pool.** `BoltPool`
+ * advances rather than evaluates, so it cannot serve a consumer that renders one plan twice, once
+ * against a wall clock and once against a frame index, and expects the same pixels. Nothing here
+ * requires the pool: write `from`, `to`, `along`, `fade`, `seed` and `brightness` from any
+ * function of a seed and an absolute time, set `count`, and hand it to the batch. That is exactly
+ * the route a consumer already took with `ParticleInstances`, and it works for the same reason:
+ * the *material* is the valuable half and it is separable from whatever decides where things are.
+ *
+ * Reported from outside, where the pool's own note that a stateless variant is not built read as
+ * "there is no way to do this" rather than "there is no second pool". There is no second pool and
+ * none is needed.
+ */
+export interface BoltSegments {
+    /** `from` and `to` per segment, three floats each, live segments first. */
+    from: Float32Array;
+    to: Float32Array;
+    /** Per segment: normalised distance along its arc, and the arc's own fade. */
+    along: Float32Array;
+    fade: Float32Array;
+    /** Per segment: the arc's seed, and how bright the caller asked for it. */
+    seed: Float32Array;
+    brightness: Float32Array;
+    /** How many segments of the above are live. */
+    count: number;
+    capacity: number;
+}
+export declare class BoltPool {
+    private readonly options;
+    readonly segments: BoltSegments;
+    private readonly nodeCount;
+    private readonly segmentsPerBolt;
+    /** Node positions, `capacity * nodeCount * 3`. */
+    private readonly nodes;
+    /** Both ends, held so a re-strike draws a new path between the same points. */
+    private readonly ends;
+    private readonly age;
+    /** Per-arc lifetime, so a volley is not a row of identically-timed flashes. */
+    private readonly life;
+    private readonly seed;
+    private readonly brightness;
+    /** Seconds until this arc re-draws its path. */
+    private readonly restrike;
+    private next;
+    constructor(options: BoltPoolOptions);
+    /** How many arcs are alive. */
+    get live(): number;
+    /**
+     * Strike an arc between two points.
+     *
+     * `seed` drives the path instead of `Math.random`, so a caller inside a
+     * deterministic system can pass a tick count and get the same lightning twice.
+     */
+    strike(x0: number, y0: number, z0: number, x1: number, y1: number, z1: number, seed: number, brightness?: number, 
+    /**
+     * Multiplier on the pool's lifetime for this arc alone.
+     *
+     * A volley of arcs that all die on the same frame reads as one object being
+     * switched off, which is the most predictable thing a flash can do. Varying it
+     * per strike is the cheapest way to make a burst decay like several discharges.
+     */
+    lifeScale?: number): void;
+    /**
+     * Age every arc, re-strike the ones whose path is due, and rebuild the
+     * segment arrays.
+     *
+     * Compacting as it goes, like the particle pool: live segments are written to
+     * the front, so a draw submits exactly the live count and a dead arc costs one
+     * loop iteration.
+     */
+    update(dt: number): void;
+    /** Drop everything, for a respawn or a scene change. */
+    clear(): void;
+    /**
+     * Lay one arc's nodes out: the straight line, then mid-point displacement.
+     *
+     * Displacement is perpendicular to the span and halves with each subdivision,
+     * which is what gives an arc detail at every scale instead of one big zigzag —
+     * the same construction a fractal terrain uses, in one dimension. The ends
+     * never move, because they are where the arc was asked to strike.
+     */
+    private drawPath;
+}
+/** A hot core and an outer glow, as a caller-facing pair. */
+export interface BoltColors {
+    core: Vec3;
+    edge: Vec3;
+}