@driftengine/core 3.61.0

package/dist/render/backend/webgpu/windStreakPass.js

@@ -0,0 +1,153 @@
+import { DEPTH_COMPARE } from '../../depthConvention.js';
+import { WINDSTREAKS_BINDINGS, WIND_STREAK_FRAG_WGSL, WIND_STREAK_VERT_WGSL, } from '../../shaders/generated/windStreaks.wgsl.js';
+import { buildWindStreakLattice } from '../../windStreakDraw.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The wind-streak pass: a lattice of debris that follows the camera and wraps.
+ *
+ * **Nothing here is per frame except ten uniforms.** The whole effect lives in the vertex
+ * shader — a particle's place comes from its index and the clock, and the box it sits in wraps
+ * around the camera — so there is no spawning, no pooling and no upload once the lattice is
+ * built.
+ *
+ * Blended over what is behind it rather than added, because dust in air occludes: this is the
+ * one effect in this backend that is neither opaque nor additive.
+ */
+export const WIND_STREAK_VERT_FIELDS = WINDSTREAKS_BINDINGS.WIND_STREAK_VERT.fields;
+export const WIND_STREAK_VERT_SIZE = WINDSTREAKS_BINDINGS.WIND_STREAK_VERT.uniformSize;
+export const WIND_STREAK_FRAG_FIELDS = WINDSTREAKS_BINDINGS.WIND_STREAK_FRAG.fields;
+export const WIND_STREAK_FRAG_SIZE = WINDSTREAKS_BINDINGS.WIND_STREAK_FRAG.uniformSize;
+const VERT_BINDING = WINDSTREAKS_BINDINGS.WIND_STREAK_VERT.uniforms;
+const FRAG_BINDING = WINDSTREAKS_BINDINGS.WIND_STREAK_FRAG.uniforms;
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008;
+export function createGpuWindStreaks(device, count, cellSize, onsetSpeed, fullSpeed) {
+    const lattice = buildWindStreakLattice(count);
+    const upload = (data, label) => {
+        const buffer = device.createBuffer({
+            label,
+            size: Math.max(4, data.byteLength),
+            usage: USAGE_VERTEX,
+        });
+        device.queue.writeBuffer(buffer, 0, data);
+        return buffer;
+    };
+    const corners = upload(lattice.corners, 'windStreaks.corners');
+    const indices = upload(lattice.indices, 'windStreaks.indices');
+    return {
+        corners,
+        indices,
+        vertexCount: lattice.vertexCount,
+        cellSize,
+        count,
+        onsetSpeed,
+        fullSpeed,
+        dispose() {
+            corners.destroy();
+            indices.destroy();
+        },
+    };
+}
+/**
+ * `aCorner` and `aIndex`, one buffer each, matching what `WindStreakRenderer` binds.
+ *
+ * Not interleaved, because they are two separate arrays on both sides and two of eight slots is
+ * nothing. The flat pass interleaves only because ten attributes will not fit.
+ */
+export function windStreakVertexLayouts() {
+    return [
+        {
+            arrayStride: 8,
+            attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x2' }],
+        },
+        {
+            arrayStride: 4,
+            attributes: [{ shaderLocation: 1, offset: 0, format: 'float32' }],
+        },
+    ];
+}
+export function createWindStreakBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'windStreaks.layout',
+        entries: [
+            /*
+             * **Addressed by a dynamic offset, so a frame can draw more than one batch.**
+             *
+             * With one buffer rewritten between draws, every batch reads whatever was written last:
+             * `queue.write*` calls are ordered on the queue timeline and the encoder is submitted after
+             * every one of them. The picture is each batch wearing the last one's colour, width, time
+             * and placement. That is the hazard `UniformRing` exists for, recorded in `AGENTS.md` on
+             * 2026-08-27, and this pass was one of four still carrying it — invisible for as long as
+             * nothing drew two, which is exactly how water kept it for eight releases.
+             *
+             * WebGL2 needs none of this: it sets uniforms and draws in one stream.
+             */
+            {
+                binding: VERT_BINDING,
+                visibility: VISIBILITY_VERTEX,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: WIND_STREAK_VERT_SIZE },
+            },
+            {
+                binding: FRAG_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: WIND_STREAK_FRAG_SIZE },
+            },
+        ],
+    });
+}
+export function createWindStreakBindGroup(device, layout, vertices, fragments) {
+    return device.createBindGroup({
+        label: 'windStreaks.bindGroup',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: vertices, size: WIND_STREAK_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: fragments, size: WIND_STREAK_FRAG_SIZE } },
+        ],
+    });
+}
+/**
+ * The pipeline.
+ *
+ * **Alpha over, depth tested, depth not written, nothing culled.** A streak is a two-sided
+ * card carried past the camera at any angle, so culling it would drop half of them for no
+ * saving; writing depth would let a translucent smear occlude whatever is drawn after it.
+ */
+export function windStreakPipeline(cache, device, layout) {
+    return cache.get('windStreaks', () => ({
+        label: 'windStreaks',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, {
+                label: 'windStreaks.vert',
+                code: WIND_STREAK_VERT_WGSL,
+            }),
+            entryPoint: 'main',
+            buffers: windStreakVertexLayouts(),
+        },
+        fragment: {
+            module: shaderModule(device, {
+                label: 'windStreaks.frag',
+                code: WIND_STREAK_FRAG_WGSL,
+            }),
+            entryPoint: 'main',
+            targets: [
+                {
+                    format: cache.format,
+                    blend: {
+                        color: {
+                            srcFactor: 'src-alpha',
+                            dstFactor: 'one-minus-src-alpha',
+                            operation: 'add',
+                        },
+                        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                    },
+                },
+            ],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+        multisample: { count: cache.sampleCount },
+        depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+    }));
+}

package/dist/render/billboard.d.ts

@@ -0,0 +1,27 @@
+/** Model matrices for geometry that turns to face the viewer. */
+import { mat4 } from 'gl-matrix';
+import type { Camera } from './camera.ts';
+/**
+ * Orient a mesh so its +Z faces the camera, writing the model matrix in place.
+ *
+ * The two variants are a real distinction rather than a convenience pair, and picking
+ * the wrong one is the classic billboard mistake:
+ *
+ * - **Cylindrical** (`billboardMatrixY`) spins about the world Y axis only. Anything
+ *   standing on the ground uses this — a figure, a sign, a tree. Look down at it from
+ *   above and it stays upright, because a thing with feet does not tilt to face you.
+ * - **Spherical** (`billboardMatrix`) faces the camera on every axis. For something with
+ *   no up of its own: a spark, a puff of smoke, a glow.
+ *
+ * Allocation-free: the caller owns the matrix and it is overwritten, so a frame drawing
+ * a hundred of these allocates nothing.
+ */
+export declare function billboardMatrixY(out: mat4, x: number, y: number, z: number, cameraX: number, cameraZ: number, scaleX?: number, scaleY?: number): void;
+/**
+ * Face the camera on every axis, for geometry with no up of its own.
+ *
+ * Built from the camera's own basis rather than from the direction to the eye, so a row
+ * of these stays mutually parallel instead of fanning out toward the viewer — the
+ * difference is obvious the moment two are near each other at the screen edge.
+ */
+export declare function billboardMatrix(out: mat4, x: number, y: number, z: number, camera: Camera, scaleX?: number, scaleY?: number): void;

package/dist/render/billboard.js

@@ -0,0 +1,79 @@
+/** Model matrices for geometry that turns to face the viewer. */
+import { mat4 } from 'gl-matrix';
+/**
+ * Orient a mesh so its +Z faces the camera, writing the model matrix in place.
+ *
+ * The two variants are a real distinction rather than a convenience pair, and picking
+ * the wrong one is the classic billboard mistake:
+ *
+ * - **Cylindrical** (`billboardMatrixY`) spins about the world Y axis only. Anything
+ *   standing on the ground uses this — a figure, a sign, a tree. Look down at it from
+ *   above and it stays upright, because a thing with feet does not tilt to face you.
+ * - **Spherical** (`billboardMatrix`) faces the camera on every axis. For something with
+ *   no up of its own: a spark, a puff of smoke, a glow.
+ *
+ * Allocation-free: the caller owns the matrix and it is overwritten, so a frame drawing
+ * a hundred of these allocates nothing.
+ */
+export function billboardMatrixY(out, x, y, z, cameraX, cameraZ, scaleX = 1, scaleY = 1) {
+    /*
+     * Yaw from the camera's *horizontal* offset only. Using the full 3D direction is what
+     * makes a standing figure lean back as the camera rises above it.
+     */
+    const angle = Math.atan2(cameraX - x, cameraZ - z);
+    const sin = Math.sin(angle);
+    const cos = Math.cos(angle);
+    out[0] = cos * scaleX;
+    out[1] = 0;
+    out[2] = -sin * scaleX;
+    out[3] = 0;
+    out[4] = 0;
+    out[5] = scaleY;
+    out[6] = 0;
+    out[7] = 0;
+    out[8] = sin;
+    out[9] = 0;
+    out[10] = cos;
+    out[11] = 0;
+    out[12] = x;
+    out[13] = y;
+    out[14] = z;
+    out[15] = 1;
+}
+/**
+ * Face the camera on every axis, for geometry with no up of its own.
+ *
+ * Built from the camera's own basis rather than from the direction to the eye, so a row
+ * of these stays mutually parallel instead of fanning out toward the viewer — the
+ * difference is obvious the moment two are near each other at the screen edge.
+ */
+export function billboardMatrix(out, x, y, z, camera, scaleX = 1, scaleY = 1) {
+    // The view matrix's upper 3x3 is the camera basis, transposed; its rows are the
+    // world-space right/up/forward we want the quad's axes to be.
+    const view = camera.view;
+    const rightX = view[0];
+    const rightY = view[4];
+    const rightZ = view[8];
+    const upX = view[1];
+    const upY = view[5];
+    const upZ = view[9];
+    const forwardX = view[2];
+    const forwardY = view[6];
+    const forwardZ = view[10];
+    out[0] = rightX * scaleX;
+    out[1] = rightY * scaleX;
+    out[2] = rightZ * scaleX;
+    out[3] = 0;
+    out[4] = upX * scaleY;
+    out[5] = upY * scaleY;
+    out[6] = upZ * scaleY;
+    out[7] = 0;
+    out[8] = forwardX;
+    out[9] = forwardY;
+    out[10] = forwardZ;
+    out[11] = 0;
+    out[12] = x;
+    out[13] = y;
+    out[14] = z;
+    out[15] = 1;
+}

package/dist/render/bloomChain.d.ts

@@ -0,0 +1,66 @@
+/**
+ * How wide the bloom pyramid is, how far it reaches, and where it stops.
+ *
+ * **Backend-neutral because both backends build the same pyramid**, and a difference in any of
+ * these three numbers is a difference in the picture that nothing else would explain. The WebGL2
+ * pass held the only copy and the WebGPU composite was written without it, which is how one
+ * backend ended up running the first stage of eleven and calling it bloom: it drew, it validated,
+ * and the frame it produced was a thresholded image with no blur in it at all. Measured on
+ * night-court, that was 7,512 pixels moved against WebGL2's 47,574.
+ *
+ * `bloomPass.ts` binds these on one side and `webgpu/renderer.ts` on the other.
+ */
+/**
+ * How many halvings the chain may take.
+ *
+ * Six covers a 4K frame down to about 30 pixels across, which is where a level stops describing
+ * a halo and starts describing the whole screen. Fewer would put an end on the falloff; more
+ * would spend draws on levels that add a flat tint.
+ */
+export declare const BLOOM_LEVELS = 6;
+/** Below this a level is too small to describe anything but an average of the frame. */
+export declare const BLOOM_MIN_SIDE = 8;
+/**
+ * How far the tent reaches on the way back up, in UV.
+ *
+ * In UV rather than in texels, so the spread is the same fraction of the picture on every
+ * display and at every level of the chain. This is the "one radius" of the three numbers this
+ * effect is allowed: it is fixed rather than exposed because nobody has asked to move it, and a
+ * caller who does gets it as a construction-time option rather than as a magic literal here.
+ */
+export declare const BLOOM_FILTER_RADIUS_UV = 0.005;
+/**
+ * What is wrong with a profile that asked for bloom, in words, or null when nothing is.
+ *
+ * **Shared because it is a fact about the profile rather than about a backend**, and because a
+ * warning that only one backend says is a warning half the consumers never see. WebGL2 said both
+ * of these at init and this backend said something else entirely from its setters — that the
+ * composite did not exist yet, which stopped being true the day it landed and went on being
+ * printed. A stale warning is worse than none: it tells somebody a working feature is broken.
+ *
+ * Not a clamp and not a refusal. The effect still runs and still spreads whatever passes its
+ * threshold. What it cannot do is separate a light from a white wall, because on a target that
+ * does not keep the range they arrive as the same colour. That is the class of fault this engine
+ * has shipped twice under other names — a shadow strength of zero behind an enabled shadow pass,
+ * an exposure with no curve to be exposed into — where everything is switched on, nothing is
+ * wrong, and nothing happens.
+ */
+export declare function bloomProfileWarning(quality: {
+    readonly bloom: number;
+    readonly screenEffects: boolean;
+    readonly hdrScene: boolean;
+    readonly bloomThreshold: number;
+}): string | null;
+/** One level of the pyramid: level 0 is half the frame and each one after it half again. */
+export interface BloomLevelSize {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * The pyramid for a frame of this size, largest first, or an empty list where none would fit.
+ *
+ * Empty is a real answer rather than a failure: a frame small enough that its half is under
+ * `BLOOM_MIN_SIDE` has nowhere for a halo to live, and a caller reads that as "no bloom this
+ * frame" exactly as it reads a target that would not allocate.
+ */
+export declare function bloomLevelSizes(width: number, height: number): BloomLevelSize[];

package/dist/render/bloomChain.js

@@ -0,0 +1,83 @@
+/**
+ * How wide the bloom pyramid is, how far it reaches, and where it stops.
+ *
+ * **Backend-neutral because both backends build the same pyramid**, and a difference in any of
+ * these three numbers is a difference in the picture that nothing else would explain. The WebGL2
+ * pass held the only copy and the WebGPU composite was written without it, which is how one
+ * backend ended up running the first stage of eleven and calling it bloom: it drew, it validated,
+ * and the frame it produced was a thresholded image with no blur in it at all. Measured on
+ * night-court, that was 7,512 pixels moved against WebGL2's 47,574.
+ *
+ * `bloomPass.ts` binds these on one side and `webgpu/renderer.ts` on the other.
+ */
+/**
+ * How many halvings the chain may take.
+ *
+ * Six covers a 4K frame down to about 30 pixels across, which is where a level stops describing
+ * a halo and starts describing the whole screen. Fewer would put an end on the falloff; more
+ * would spend draws on levels that add a flat tint.
+ */
+export const BLOOM_LEVELS = 6;
+/** Below this a level is too small to describe anything but an average of the frame. */
+export const BLOOM_MIN_SIDE = 8;
+/**
+ * How far the tent reaches on the way back up, in UV.
+ *
+ * In UV rather than in texels, so the spread is the same fraction of the picture on every
+ * display and at every level of the chain. This is the "one radius" of the three numbers this
+ * effect is allowed: it is fixed rather than exposed because nobody has asked to move it, and a
+ * caller who does gets it as a construction-time option rather than as a magic literal here.
+ */
+export const BLOOM_FILTER_RADIUS_UV = 0.005;
+/**
+ * What is wrong with a profile that asked for bloom, in words, or null when nothing is.
+ *
+ * **Shared because it is a fact about the profile rather than about a backend**, and because a
+ * warning that only one backend says is a warning half the consumers never see. WebGL2 said both
+ * of these at init and this backend said something else entirely from its setters — that the
+ * composite did not exist yet, which stopped being true the day it landed and went on being
+ * printed. A stale warning is worse than none: it tells somebody a working feature is broken.
+ *
+ * Not a clamp and not a refusal. The effect still runs and still spreads whatever passes its
+ * threshold. What it cannot do is separate a light from a white wall, because on a target that
+ * does not keep the range they arrive as the same colour. That is the class of fault this engine
+ * has shipped twice under other names — a shadow strength of zero behind an enabled shadow pass,
+ * an exposure with no curve to be exposed into — where everything is switched on, nothing is
+ * wrong, and nothing happens.
+ */
+export function bloomProfileWarning(quality) {
+    if (quality.bloom <= 0)
+        return null;
+    if (!quality.screenEffects) {
+        return ('bloom needs screenEffects, since without the off-screen target there is no finished ' +
+            'frame to threshold. It is off.');
+    }
+    if (!quality.hdrScene) {
+        return (`bloom is on with hdrScene off, so the scene is clipped to 0..1 before the composite ` +
+            `sees it and a threshold of ${quality.bloomThreshold} in scene units can only mean ` +
+            `whiteness. Turn hdrScene on, or set a threshold below 1.`);
+    }
+    return null;
+}
+/**
+ * The pyramid for a frame of this size, largest first, or an empty list where none would fit.
+ *
+ * Empty is a real answer rather than a failure: a frame small enough that its half is under
+ * `BLOOM_MIN_SIDE` has nowhere for a halo to live, and a caller reads that as "no bloom this
+ * frame" exactly as it reads a target that would not allocate.
+ */
+export function bloomLevelSizes(width, height) {
+    const sizes = [];
+    let levelWidth = width;
+    let levelHeight = height;
+    for (let level = 0; level < BLOOM_LEVELS; level++) {
+        levelWidth = Math.floor(levelWidth / 2);
+        levelHeight = Math.floor(levelHeight / 2);
+        /* Below this a level is a handful of texels describing the whole frame, which adds a
+           flat tint rather than a halo, and one more halving of a 3-pixel side is 1. */
+        if (levelWidth < BLOOM_MIN_SIDE || levelHeight < BLOOM_MIN_SIDE)
+            break;
+        sizes.push({ width: levelWidth, height: levelHeight });
+    }
+    return sizes;
+}

package/dist/render/bloomPass.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 declare class BloomPass {
+    private readonly gl;
+    /** The chain, level 0 at half the frame and each one after it half again. */
+    private readonly levels;
+    private width;
+    private height;
+    /**
+     * 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`.
+     */
+    private unavailable;
+    /** Half floats where the part will render to them. See the note in `allocate`. */
+    private readonly floatColor;
+    private readonly prefilterProgram;
+    private readonly prefilterUniforms;
+    private readonly downsampleProgram;
+    private readonly downsampleUniforms;
+    private readonly upsampleProgram;
+    private readonly upsampleUniforms;
+    private readonly vao;
+    /** Scratch for the source texel size, so a per-frame pass allocates nothing. */
+    private readonly texel;
+    constructor(gl: WebGL2RenderingContext);
+    private ensureSize;
+    private allocate;
+    /**
+     * 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: WebGLTexture, width: number, height: number, threshold: number): WebGLTexture | null;
+    /** One source texel in UV, which is what the thirteen taps are laid out in. */
+    private uploadTexel;
+    private release;
+    dispose(): void;
+}