@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/mesh.js

@@ -0,0 +1,472 @@
+/**
+ * Mesh: a vertex buffer (+ optional index buffer) in one of the engine's vertex layouts.
+ *
+ * - `VERTEX_LAYOUT_2D` (the default): `pos: vec2f, uv: vec2f, color: vec4f`, 8 floats
+ *   (`VERTEX_FLOATS`), 32 bytes per vertex.
+ * - `VERTEX_LAYOUT_3D`: `pos: vec3f, normal: vec3f, uv: vec2f, color: vec4f`, 12 floats
+ *   (`VERTEX3D_FLOATS`), 48 bytes per vertex.
+ * - `VERTEX_LAYOUT_3D_TANGENT`: the 3D layout plus `tangent: vec4f` (xyz, handedness w),
+ *   16 floats, 64 bytes per vertex.
+ *
+ * Positions are in the mesh's local space; each draw's 3×4 instance matrix (built from
+ * `DrawParams` x, y, w, h, rotation, or taken from a `Transform`) maps local → world space.
+ * For `DrawParams` that is `xy + rotate(pos * wh)`: the built-in quad spans -0.5..0.5 so
+ * `w, h` are its size in logical pixels; for arbitrary meshes authored directly in logical
+ * pixels, draw with `x = 0, y = 0, w = 1, h = 1`.
+ *
+ * Materials build one pipeline per (vertex layout, depth mode), lazily, on first use.
+ */
+export const VERTEX_FLOATS = 8;
+export const VERTEX_STRIDE = VERTEX_FLOATS * 4;
+export const VERTEX3D_FLOATS = 12;
+export const VERTEX3D_STRIDE = VERTEX3D_FLOATS * 4;
+/** The 2D layout's buffer layout (locations 0..2). */
+export const VERTEX_BUFFER_LAYOUT = {
+    arrayStride: VERTEX_STRIDE,
+    stepMode: 'vertex',
+    attributes: [
+        { shaderLocation: 0, offset: 0, format: 'float32x2' },
+        { shaderLocation: 1, offset: 8, format: 'float32x2' },
+        { shaderLocation: 2, offset: 16, format: 'float32x4' },
+    ],
+};
+/** The 3D layout's buffer layout: position 0, normal 10, uv 1, colour 2. */
+export const VERTEX3D_BUFFER_LAYOUT = {
+    arrayStride: VERTEX3D_STRIDE,
+    stepMode: 'vertex',
+    attributes: [
+        { shaderLocation: 0, offset: 0, format: 'float32x3' },
+        { shaderLocation: 10, offset: 12, format: 'float32x3' },
+        { shaderLocation: 1, offset: 24, format: 'float32x2' },
+        { shaderLocation: 2, offset: 32, format: 'float32x4' },
+    ],
+};
+/** 2D layout: `v.pos` is a `vec2f` (z = 0); the normal faces the viewer, `(0, 0, -1)`. */
+export const VERTEX_LAYOUT_2D = {
+    name: '2d',
+    positionOffset: 0,
+    floats: VERTEX_FLOATS,
+    stride: VERTEX_STRIDE,
+    buffer: VERTEX_BUFFER_LAYOUT,
+    wgslFields: `  @location(0) pos: vec2f,
+  @location(1) uv: vec2f,
+  @location(2) color: vec4f,`,
+    wgslPosition: 'vec3f(v.pos, 0.0)',
+    wgslNormal: 'vec3f(0.0, 0.0, -1.0)',
+};
+/** 3D layout: `v.pos` and `v.normal` are `vec3f`. */
+export const VERTEX_LAYOUT_3D = {
+    name: '3d',
+    positionOffset: 0,
+    floats: VERTEX3D_FLOATS,
+    stride: VERTEX3D_STRIDE,
+    buffer: VERTEX3D_BUFFER_LAYOUT,
+    wgslFields: `  @location(0) pos: vec3f,
+  @location(10) normal: vec3f,
+  @location(1) uv: vec2f,
+  @location(2) color: vec4f,`,
+    wgslPosition: 'v.pos',
+    wgslNormal: 'v.normal',
+};
+/**
+ * Tangent layout (ws/geom-2): the 3D layout's 12 floats followed by a tangent `vec4f` at
+ * `@location(13)` (3..9 are the instance buffer, 11 and 12 skinning): xyz the unit tangent
+ * along +u, w the handedness ±1, so the bitangent is `w · cross(normal, tangent)`. 16 floats,
+ * 64 bytes. `geom`'s `computeTangents` writes it; the prelude reads it like the 3D layout, so a
+ * material that ignores `v.tangent` draws unchanged.
+ */
+export const VERTEX_LAYOUT_3D_TANGENT = {
+    name: '3d-tangent',
+    positionOffset: 0,
+    floats: 16,
+    stride: 64,
+    buffer: {
+        arrayStride: 64,
+        stepMode: 'vertex',
+        attributes: [
+            { shaderLocation: 0, offset: 0, format: 'float32x3' },
+            { shaderLocation: 10, offset: 12, format: 'float32x3' },
+            { shaderLocation: 1, offset: 24, format: 'float32x2' },
+            { shaderLocation: 2, offset: 32, format: 'float32x4' },
+            { shaderLocation: 13, offset: 48, format: 'float32x4' },
+        ],
+    },
+    wgslFields: `  @location(0) pos: vec3f,
+  @location(10) normal: vec3f,
+  @location(1) uv: vec2f,
+  @location(2) color: vec4f,
+  @location(13) tangent: vec4f,`,
+    wgslPosition: 'v.pos',
+    wgslNormal: 'v.normal',
+    wgslTangent: 'v.tangent',
+};
+/** Floats of `VERTEX_LAYOUT_3D_UV2` (the 3D layout plus a second uv). */
+export const VERTEX3D_UV2_FLOATS = 14;
+export const VERTEX3D_UV2_STRIDE = VERTEX3D_UV2_FLOATS * 4;
+/**
+ * Two-uv layout (ws/render-4): the 3D layout's 12 floats followed by `uv1: vec2f` at
+ * `@location(14)` (glTF `TEXCOORD_1`, the usual home of a light or occlusion map): 14 floats,
+ * 56 bytes. The prelude carries it as `VSOut.uv1`; the standard material's maps pick it with
+ * `texCoord: 1`. Materials that ignore it draw as with the 3D layout.
+ */
+export const VERTEX_LAYOUT_3D_UV2 = {
+    name: '3d-uv2',
+    positionOffset: 0,
+    floats: VERTEX3D_UV2_FLOATS,
+    stride: VERTEX3D_UV2_STRIDE,
+    buffer: {
+        arrayStride: VERTEX3D_UV2_STRIDE,
+        stepMode: 'vertex',
+        attributes: [
+            { shaderLocation: 0, offset: 0, format: 'float32x3' },
+            { shaderLocation: 10, offset: 12, format: 'float32x3' },
+            { shaderLocation: 1, offset: 24, format: 'float32x2' },
+            { shaderLocation: 2, offset: 32, format: 'float32x4' },
+            { shaderLocation: 14, offset: 48, format: 'float32x2' },
+        ],
+    },
+    wgslFields: `  @location(0) pos: vec3f,
+  @location(10) normal: vec3f,
+  @location(1) uv: vec2f,
+  @location(2) color: vec4f,
+  @location(14) uv1: vec2f,`,
+    wgslPosition: 'v.pos',
+    wgslNormal: 'v.normal',
+    wgslUv1: 'v.uv1',
+};
+/**
+ * Skinned layout: the 3D layout's 12 floats followed by four joint indices (`uint8x4`, read as
+ * `vec4u`) and four weights (`unorm8x4`, read as `vec4f`), 8 bytes that occupy the slots of
+ * floats 12 and 13: 14 "floats" (`VERTEX_SKINNED_FLOATS`), 56 bytes per vertex. Write the
+ * joints and weights through a byte view of the vertex buffer (`setVertexSkin` in `skin.ts`),
+ * not as floats (a packed value may be a NaN pattern). `materialPrelude` applies the four
+ * weighted joint matrices from the material's `SkinPalette` before the instance matrix.
+ */
+export const VERTEX_SKINNED_FLOATS = 14;
+export const VERTEX_SKINNED_STRIDE = VERTEX_SKINNED_FLOATS * 4;
+/** Byte offset of the four joint indices inside a skinned vertex. */
+export const SKIN_JOINTS_BYTE_OFFSET = 48;
+/** Byte offset of the four weights (unorm8) inside a skinned vertex. */
+export const SKIN_WEIGHTS_BYTE_OFFSET = 52;
+/** The skinned layout's buffer layout: the 3D attributes, joints at 11 and weights at 12. */
+export const VERTEX_SKINNED_BUFFER_LAYOUT = {
+    arrayStride: VERTEX_SKINNED_STRIDE,
+    stepMode: 'vertex',
+    attributes: [
+        { shaderLocation: 0, offset: 0, format: 'float32x3' },
+        { shaderLocation: 10, offset: 12, format: 'float32x3' },
+        { shaderLocation: 1, offset: 24, format: 'float32x2' },
+        { shaderLocation: 2, offset: 32, format: 'float32x4' },
+        { shaderLocation: 11, offset: SKIN_JOINTS_BYTE_OFFSET, format: 'uint8x4' },
+        { shaderLocation: 12, offset: SKIN_WEIGHTS_BYTE_OFFSET, format: 'unorm8x4' },
+    ],
+};
+/**
+ * Skinned layout: `v.pos`, `v.normal`, `v.uv`, `v.color` as in 3D plus `v.joints: vec4u` and
+ * `v.weights: vec4f`. The prelude's `engine_local_position` / `engine_local_normal` return the
+ * skinned position and normal (`engine_skin`), so `engine_vertex` and every material work
+ * unchanged. The instance's palette slot travels in `params.w` (see `skin.ts`).
+ */
+export const VERTEX_LAYOUT_SKINNED = {
+    name: 'skinned',
+    positionOffset: 0,
+    floats: VERTEX_SKINNED_FLOATS,
+    stride: VERTEX_SKINNED_STRIDE,
+    buffer: VERTEX_SKINNED_BUFFER_LAYOUT,
+    wgslFields: `  @location(0) pos: vec3f,
+  @location(10) normal: vec3f,
+  @location(1) uv: vec2f,
+  @location(2) color: vec4f,
+  @location(11) joints: vec4u,
+  @location(12) weights: vec4f,`,
+    wgslPosition: 'engine_skin(v, v.pos, v.normal).position',
+    wgslNormal: 'engine_skin(v, v.pos, v.normal).normal',
+    wgslPreviousPosition: 'engine_skin_previous(v, v.pos)',
+    skinned: true,
+};
+/** Capacity (vertices) up to which `MeshDesc.autoBounds` defaults to on. */
+export const AUTO_BOUNDS_MAX_VERTICES = 65536;
+/** 1.5× growth, like a vector: amortised reallocations when a streamed mesh keeps growing. */
+const GROWTH = 1.5;
+export class Mesh {
+    device;
+    label;
+    /** Vertex layout of this mesh's buffer; pipelines are keyed by (material, layout). */
+    layout;
+    vertexBuffer;
+    indexBuffer = null;
+    indexFormat = 'uint16';
+    /** Vertices drawn (non-indexed) and uploaded by the last `update`. */
+    vertexCount = 0;
+    /**
+     * Indices drawn (`drawIndexed`) when > 0. With an index buffer and `indexCount` 0 the renderer
+     * skips the draw entirely (no non-indexed fallback, no draw call, nothing in
+     * `RenderStats`), so `update({ indexCount: 0 })` empties the mesh.
+     */
+    indexCount = 0;
+    /**
+     * Buffers reallocated so far, by `update()` exceeding `capacity` or changing the index format.
+     * A caller that caches `vertexBuffer`/`indexBuffer` (a drawable, a bind group) re-reads them
+     * when this changes.
+     */
+    growths = 0;
+    /**
+     * Bounding sphere in mesh space (the renderer carries it through each draw's instance matrix
+     * and culls against `camera.frustum`). From `MeshDesc.bounds`, `MeshUpdate.bounds` or, with
+     * `autoBounds`, the positions; `radius` Infinity when unknown (never culled). The object is
+     * owned by the mesh; read it, set it through `update({ bounds })`.
+     */
+    bounds = { center: [0, 0, 0], radius: Number.POSITIVE_INFINITY };
+    /** Whether `update()` recomputes `bounds` from uploaded vertices (`MeshDesc.autoBounds`). */
+    autoBounds;
+    /** Named index ranges from `MeshDesc.ranges`; storage only, the renderer never reads it. */
+    ranges;
+    /** The layout's position attribute (location 0) has a z component. */
+    pos3;
+    cap = { vertices: 0, indices: 0 };
+    /** 4-byte scratch for the last index of an odd uint16 count at the end of its buffer. */
+    tail16 = new Uint16Array(2);
+    constructor(device, desc) {
+        this.device = device;
+        this.label = desc.label ?? 'mesh';
+        this.layout = desc.layout ?? VERTEX_LAYOUT_2D;
+        const vCount = desc.vertices ? desc.vertices.length / this.layout.floats : 0;
+        this.cap.vertices = Math.max(vCount, desc.capacity?.vertices ?? 0, 1);
+        this.autoBounds = desc.autoBounds ?? this.cap.vertices < AUTO_BOUNDS_MAX_VERTICES;
+        this.ranges = desc.ranges;
+        this.pos3 = positionHasZ(this.layout);
+        this.vertexBuffer = this.makeVertexBuffer(this.cap.vertices);
+        const iCap = Math.max(desc.indices?.length ?? 0, desc.capacity?.indices ?? 0);
+        if (iCap > 0) {
+            this.indexFormat =
+                desc.indexFormat ??
+                    (desc.indices ? formatOf(desc.indices) : this.cap.vertices > 0xffff ? 'uint32' : 'uint16');
+            this.cap.indices = iCap;
+            this.indexBuffer = this.makeIndexBuffer(iCap);
+        }
+        if (desc.vertices || desc.indices || desc.bounds) {
+            this.update({ vertices: desc.vertices, indices: desc.indices, bounds: desc.bounds });
+        }
+    }
+    /** Room in the buffers (vertices, indices); `indices` is 0 for a non-indexed mesh. */
+    get capacity() {
+        return this.cap;
+    }
+    /**
+     * Replace geometry (`MeshUpdate`). Writes with `queue.writeBuffer` straight from each view's
+     * buffer and reuses the GPU buffers while the counts fit `capacity`; grows them (1.5×) only
+     * when a count exceeds it or the index format changes. Returns true when a buffer was
+     * reallocated (`growths` counts them). `bounds` are copied when given, else recomputed from
+     * the uploaded positions when `autoBounds` is on (a `Float32Array` view is read in place;
+     * any other view type gets one over the same buffer). Allocation-free otherwise.
+     *
+     * A `MeshReply` (`{ buffer, vertexCount, indexCount?, bounds? }`, a Worker's message) is the
+     * same upload read straight out of the one transferred buffer; it allocates the two views.
+     */
+    update(u) {
+        if ('buffer' in u && u.buffer instanceof ArrayBuffer)
+            return this.updateFromReply(u);
+        return this.updateViews(u);
+    }
+    updateFromReply(r) {
+        const { stride } = this.layout;
+        const vBytes = r.vertexCount * stride;
+        const vertices = new Uint8Array(r.buffer, 0, vBytes);
+        let indices;
+        if (r.indexCount !== undefined) {
+            const bpi = this.indexFormat === 'uint32' ? 4 : 2;
+            const at = r.indexOffset ?? (vBytes + 3) & ~3;
+            indices = new Uint8Array(r.buffer, at, r.indexCount * bpi);
+        }
+        return this.updateViews({
+            vertices,
+            indices,
+            vertexCount: r.vertexCount,
+            // A reply without indices on an indexed mesh draws nothing until the next one.
+            indexCount: r.indexCount ?? (this.indexBuffer ? 0 : undefined),
+            bounds: r.bounds,
+        });
+    }
+    updateViews(u) {
+        let grew = false;
+        const { stride } = this.layout;
+        if (u.vertices) {
+            const count = u.vertexCount ?? Math.floor(u.vertices.byteLength / stride);
+            if (count > this.cap.vertices) {
+                this.vertexBuffer.destroy();
+                this.cap.vertices = Math.ceil(count * GROWTH);
+                this.vertexBuffer = this.makeVertexBuffer(this.cap.vertices);
+                grew = true;
+            }
+            this.vertexCount = count;
+            if (count > 0) {
+                this.device.queue.writeBuffer(this.vertexBuffer, 0, u.vertices.buffer, u.vertices.byteOffset, count * stride);
+            }
+            if (!u.bounds && this.autoBounds)
+                this.computeBounds(u.vertices, count);
+        }
+        else if (u.vertexCount !== undefined) {
+            this.vertexCount = Math.min(u.vertexCount, this.cap.vertices);
+        }
+        if (u.indices) {
+            const fmt = formatOf(u.indices, this.indexFormat);
+            const bpi = fmt === 'uint32' ? 4 : 2;
+            const count = u.indexCount ?? Math.floor(u.indices.byteLength / bpi);
+            if (!this.indexBuffer || count > this.cap.indices || fmt !== this.indexFormat) {
+                this.indexBuffer?.destroy();
+                this.cap.indices = Math.max(Math.ceil(count * GROWTH), 1);
+                this.indexFormat = fmt;
+                this.indexBuffer = this.makeIndexBuffer(this.cap.indices);
+                grew = true;
+            }
+            this.indexCount = count;
+            this.writeIndices(u.indices, count * bpi);
+        }
+        else if (u.indexCount !== undefined && this.indexBuffer) {
+            this.indexCount = Math.min(u.indexCount, this.cap.indices);
+        }
+        if (u.bounds) {
+            const b = this.bounds;
+            const c = u.bounds.center;
+            b.center[0] = c[0];
+            b.center[1] = c[1];
+            b.center[2] = c[2];
+            b.radius = u.bounds.radius;
+        }
+        if (grew)
+            this.growths++;
+        return grew;
+    }
+    /**
+     * Bounding sphere of the first `count` vertices of `view` in this layout: the centre of their
+     * axis-aligned box, the radius the farthest vertex from it. 2D positions have z = 0.
+     */
+    computeBounds(view, count) {
+        const b = this.bounds;
+        if (count === 0) {
+            b.center[0] = 0;
+            b.center[1] = 0;
+            b.center[2] = 0;
+            b.radius = 0;
+            return;
+        }
+        const floats = this.layout.floats;
+        const f = view instanceof Float32Array
+            ? view
+            : new Float32Array(view.buffer, view.byteOffset, count * floats);
+        const has3 = this.pos3;
+        let minX = Number.POSITIVE_INFINITY;
+        let minY = Number.POSITIVE_INFINITY;
+        let minZ = Number.POSITIVE_INFINITY;
+        let maxX = Number.NEGATIVE_INFINITY;
+        let maxY = Number.NEGATIVE_INFINITY;
+        let maxZ = Number.NEGATIVE_INFINITY;
+        const end = count * floats;
+        for (let o = 0; o < end; o += floats) {
+            const x = f[o];
+            const y = f[o + 1];
+            const z = has3 ? f[o + 2] : 0;
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (y < minY)
+                minY = y;
+            if (y > maxY)
+                maxY = y;
+            if (z < minZ)
+                minZ = z;
+            if (z > maxZ)
+                maxZ = z;
+        }
+        const cx = (minX + maxX) / 2;
+        const cy = (minY + maxY) / 2;
+        const cz = (minZ + maxZ) / 2;
+        let r2 = 0;
+        for (let o = 0; o < end; o += floats) {
+            const dx = f[o] - cx;
+            const dy = f[o + 1] - cy;
+            const dz = (has3 ? f[o + 2] : 0) - cz;
+            const d = dx * dx + dy * dy + dz * dz;
+            if (d > r2)
+                r2 = d;
+        }
+        b.center[0] = cx;
+        b.center[1] = cy;
+        b.center[2] = cz;
+        b.radius = Math.sqrt(r2);
+    }
+    /** `writeBuffer` wants 4-byte sizes and offsets; a uint16 count may be odd. */
+    writeIndices(view, bytes) {
+        if (bytes === 0)
+            return;
+        const ib = this.indexBuffer;
+        const { buffer, byteOffset } = view;
+        const even = bytes & ~3;
+        if (even === bytes) {
+            this.device.queue.writeBuffer(ib, 0, buffer, byteOffset, bytes);
+            return;
+        }
+        if (byteOffset + bytes + 2 <= buffer.byteLength) {
+            // Two bytes of slack after the data: upload them as padding.
+            this.device.queue.writeBuffer(ib, 0, buffer, byteOffset, bytes + 2);
+            return;
+        }
+        // The odd index ends its buffer: write the even prefix, then the last index via the scratch.
+        if (even > 0)
+            this.device.queue.writeBuffer(ib, 0, buffer, byteOffset, even);
+        const bytesView = new DataView(buffer, byteOffset + even, 2);
+        this.tail16[0] = bytesView.getUint16(0, true);
+        this.device.queue.writeBuffer(ib, even, this.tail16.buffer, 0, 4);
+    }
+    /** The `GPUVertexBufferLayout` of `layout` (buffer slot 0 of every pipeline drawing it). */
+    get vertexBufferLayout() {
+        return this.layout.buffer;
+    }
+    destroy() {
+        this.vertexBuffer.destroy();
+        this.indexBuffer?.destroy();
+    }
+    makeVertexBuffer(count) {
+        return this.device.createBuffer({
+            label: `${this.label}-vb`,
+            size: count * this.layout.stride,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+        });
+    }
+    makeIndexBuffer(count) {
+        const bytes = count * (this.indexFormat === 'uint32' ? 4 : 2);
+        return this.device.createBuffer({
+            label: `${this.label}-ib`,
+            size: Math.ceil(bytes / 4) * 4,
+            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+    }
+}
+/** Does the layout's position attribute (shader location 0) carry three components? */
+function positionHasZ(layout) {
+    for (const a of layout.buffer.attributes) {
+        if (a.shaderLocation === 0)
+            return a.format === 'float32x3' || a.format === 'float32x4';
+    }
+    return false;
+}
+/** Index format implied by a typed array; any other view keeps `fallback`. */
+function formatOf(view, fallback = 'uint16') {
+    if (view instanceof Uint32Array)
+        return 'uint32';
+    if (view instanceof Uint16Array)
+        return 'uint16';
+    return fallback;
+}
+/** Unit quad centred on the origin (-0.5..0.5), uv (0,0) top-left, white. */
+export function quadGeometry() {
+    // biome-ignore format: vertex table
+    const vertices = new Float32Array([
+        -0.5, -0.5, 0, 0, 1, 1, 1, 1,
+        0.5, -0.5, 1, 0, 1, 1, 1, 1,
+        0.5, 0.5, 1, 1, 1, 1, 1, 1,
+        -0.5, 0.5, 0, 1, 1, 1, 1, 1,
+    ]);
+    return { vertices, indices: new Uint16Array([0, 1, 2, 0, 2, 3]) };
+}

package/dist/render/mipmap.d.ts

@@ -0,0 +1,16 @@
+import type { Texture } from './texture.js';
+/** How `generateMipmaps` reduces a level: `'linear'` averages each 2×2 block, `'nearest'` keeps its top-left texel. */
+export type MipFilter = 'linear' | 'nearest';
+export interface GenerateMipmapsOptions {
+    /** Default `'linear'`. */
+    filter?: MipFilter;
+}
+/**
+ * Fill mip levels 1..`mipLevels - 1` of `texture` from level 0 on the GPU, each level rendered
+ * from the one above by a tiny blit pipeline (one per format and filter, cached per device).
+ * Arrays are handled layer by layer. The texture needs `TEXTURE_BINDING | RENDER_ATTACHMENT`
+ * usage and a renderable float format (e.g. `rgba8unorm`, `rgba8unorm-srgb`, `rgba16float`);
+ * sRGB textures average in linear space. One command buffer is submitted; a texture with one
+ * level is left as it is. Creation-time work: it allocates views and bind groups.
+ */
+export declare function generateMipmaps(device: GPUDevice, texture: Texture, opts?: GenerateMipmapsOptions): void;

package/dist/render/mipmap.js

@@ -0,0 +1,121 @@
+/**
+ * Fullscreen triangle; the fragment shader reads the level above with `textureLoad` (so any
+ * float format works, filterable or not) at twice its own pixel, clamped to the source size.
+ */
+const MIPMAP_WGSL = /* wgsl */ `
+@group(0) @binding(0) var src: texture_2d<f32>;
+
+@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
+  let p = vec2f(f32((i << 1u) & 2u), f32(i & 2u));
+  return vec4f(p * 2.0 - 1.0, 0.0, 1.0);
+}
+
+fn at(p: vec2i) -> vec4f {
+  let last = vec2i(textureDimensions(src)) - 1;
+  return textureLoad(src, min(p, last), 0);
+}
+
+@fragment fn fs_linear(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+  let p = vec2i(floor(pos.xy)) * 2;
+  return 0.25 * (at(p) + at(p + vec2i(1, 0)) + at(p + vec2i(0, 1)) + at(p + vec2i(1, 1)));
+}
+
+@fragment fn fs_nearest(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+  return at(vec2i(floor(pos.xy)) * 2);
+}
+`;
+const kits = new WeakMap();
+function kitFor(device) {
+    let kit = kits.get(device);
+    if (!kit) {
+        const layout = device.createBindGroupLayout({
+            label: 'mipmap-layout',
+            entries: [
+                {
+                    binding: 0,
+                    visibility: GPUShaderStage.FRAGMENT,
+                    texture: { sampleType: 'unfilterable-float' },
+                },
+            ],
+        });
+        kit = {
+            module: device.createShaderModule({ label: 'mipmap', code: MIPMAP_WGSL }),
+            layout,
+            pipelineLayout: device.createPipelineLayout({
+                label: 'mipmap-pipeline-layout',
+                bindGroupLayouts: [layout],
+            }),
+            pipelines: new Map(),
+        };
+        kits.set(device, kit);
+    }
+    return kit;
+}
+/** The blit pipeline for `format` and `filter`: built once per device, then cached. */
+function pipelineFor(device, format, filter) {
+    const kit = kitFor(device);
+    const key = `${format}:${filter}`;
+    let pipeline = kit.pipelines.get(key);
+    if (!pipeline) {
+        pipeline = device.createRenderPipeline({
+            label: `mipmap:${key}`,
+            layout: kit.pipelineLayout,
+            vertex: { module: kit.module, entryPoint: 'vs' },
+            fragment: {
+                module: kit.module,
+                entryPoint: filter === 'nearest' ? 'fs_nearest' : 'fs_linear',
+                targets: [{ format }],
+            },
+            primitive: { topology: 'triangle-list' },
+        });
+        kit.pipelines.set(key, pipeline);
+    }
+    return { pipeline, layout: kit.layout };
+}
+/**
+ * Fill mip levels 1..`mipLevels - 1` of `texture` from level 0 on the GPU, each level rendered
+ * from the one above by a tiny blit pipeline (one per format and filter, cached per device).
+ * Arrays are handled layer by layer. The texture needs `TEXTURE_BINDING | RENDER_ATTACHMENT`
+ * usage and a renderable float format (e.g. `rgba8unorm`, `rgba8unorm-srgb`, `rgba16float`);
+ * sRGB textures average in linear space. One command buffer is submitted; a texture with one
+ * level is left as it is. Creation-time work: it allocates views and bind groups.
+ */
+export function generateMipmaps(device, texture, opts = {}) {
+    if (texture.mipLevels <= 1)
+        return;
+    const need = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT;
+    if ((texture.texture.usage & need) !== need) {
+        throw new Error(`generateMipmaps: ${texture.texture.label || 'texture'} needs TEXTURE_BINDING | RENDER_ATTACHMENT usage`);
+    }
+    const { pipeline, layout } = pipelineFor(device, texture.format, opts.filter ?? 'linear');
+    const encoder = device.createCommandEncoder({ label: 'mipmap' });
+    const view = (level, layer) => texture.texture.createView({
+        label: `mipmap:${level}:${layer}`,
+        dimension: '2d',
+        baseMipLevel: level,
+        mipLevelCount: 1,
+        baseArrayLayer: layer,
+        arrayLayerCount: 1,
+    });
+    for (let layer = 0; layer < texture.layers; layer++) {
+        let src = view(0, layer);
+        for (let level = 1; level < texture.mipLevels; level++) {
+            const dst = view(level, layer);
+            const group = device.createBindGroup({
+                label: `mipmap:${level}:${layer}`,
+                layout,
+                entries: [{ binding: 0, resource: src }],
+            });
+            const pass = encoder.beginRenderPass({
+                label: `mipmap:${level}:${layer}`,
+                colorAttachments: [{ view: dst, loadOp: 'clear', storeOp: 'store' }],
+            });
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, group);
+            pass.draw(3);
+            pass.end();
+            src = dst;
+        }
+    }
+    device.queue.submit([encoder.finish()]);
+}

package/dist/render/parallax.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Parallax (ws/ergo-2d-2): tile layers that scroll at a fraction of the camera. `update` moves
+ * each layer's `origin` to `base + camera × (1 - factor)`, so a layer with factor 0 is pinned to
+ * the screen and one with factor 1 moves with the world; a layer with a `wrapW` / `wrapH`
+ * pattern period is kept within one period of the camera instead (the origin stays in
+ * `camera - wrap .. camera`), so a short repeating strip covers any scroll distance. `draw`
+ * draws the layers in order, far to near. No allocation per frame.
+ */
+import type { Frame, InstanceParams } from './frame.js';
+import type { Renderer } from './renderer.js';
+import type { TileLayer } from './tile-layer.js';
+export interface ParallaxLayerOptions {
+    layer: TileLayer;
+    /** 0 pins the layer to the view, 1 moves it with the world. */
+    factorX: number;
+    factorY: number;
+    /** Pattern period in px: the layer wraps every `wrapW` along x (default none). */
+    wrapW?: number;
+    wrapH?: number;
+    /** Per-layer draw params (tint, order, layers), passed to `TileLayer.draw`. */
+    params?: InstanceParams;
+}
+export interface ParallaxLayer extends ParallaxLayerOptions {
+    /** The layer's `origin` when the parallax was made: where it sits at camera `(0, 0)`. */
+    readonly baseX: number;
+    readonly baseY: number;
+    /** Offset `update` last added to the base (`camera × (1 - factor)`, wrapped). */
+    readonly offsetX: number;
+    readonly offsetY: number;
+}
+export interface Parallax {
+    /** The layers, in draw order. */
+    readonly layers: readonly ParallaxLayer[];
+    /**
+     * Aim every layer for a view whose top-left is `(cameraX, cameraY)` (an ortho2d `Camera`'s
+     * `x`, `y`): writes each layer's `origin`.
+     */
+    update(cameraX: number, cameraY: number): void;
+    /** `layer.draw(frame, params)` for each layer in order. */
+    draw(frame: Frame): void;
+    /** Destroys every layer. */
+    destroy(): void;
+}
+/** Wrapped parallax offset: `camera - (camera × factor mod wrap)`, in `camera - wrap .. camera`. */
+export declare function parallaxOffset(camera: number, factor: number, wrap?: number): number;
+/**
+ * Make a `Parallax` over layers built on `renderer`. Each layer's `origin` at this moment is its
+ * base position. Allocates once.
+ */
+export declare function createParallax(_renderer: Renderer, layers: ParallaxLayerOptions[]): Parallax;