@driftengine/core 4.9.0 → 4.11.0

package/dist/render/backend/webgpu/staticBundles.d.ts

@@ -0,0 +1,125 @@
+/**
+ * A static list on this backend: its draws recorded once, through the renderer's own draw path,
+ * into slots the list owns, and replayed as one render bundle per view.
+ *
+ * **What a recording holds is the frame's draws as the renderer would have recorded them**, taken
+ * from a pool of the list's instead of the frame graph's: a pipeline, a bind group, vertex buffers
+ * and four dynamic offsets each. Three of the four never change once recorded — the draw's own
+ * slot in `entries`, written once, and its material's slot in the store, pinned. The other two are
+ * the view's: the pass block and the view block, which differ between the frame, a mirror and a
+ * capture of the same frame. So each view a frame draws the list into takes a *copy* — a slot of
+ * `passes` and one of `views`, written for that view — and a bundle is encoded per copy from the
+ * same commands with that copy's two offsets. A frame that draws a list twice uploads two blocks
+ * and executes two bundles, and records nothing.
+ *
+ * **Its own buffers, and bind groups over them.** A bundle bakes the buffers its groups bind, and
+ * the frame's rings are reset every frame, so a list binds rings of its own: the renderer swaps
+ * them in while it records the list's draws, and the groups that recording builds go into the
+ * list's cache rather than the frame's.
+ *
+ * **Recorded again when what it baked has moved**: the renderer's groups (a texture forgotten, a
+ * frame texture rebound, a ring grown), the pipeline cache's lit set, the store's slots, or the
+ * list's own rings. Each is a number compared at replay, so a stale recording is never replayed.
+ *
+ * What it gives up: culling, since a bundle draws everything recorded into it; and memory, a pass
+ * block a view a list, which is a few kilobytes.
+ */
+import type { StaticDrawsList, StaticEntry } from '../../staticDraws.ts';
+import type { CommandPool, DrawCommand } from './drawCommand.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { UniformRing } from './uniformRing.ts';
+/** What one recording was made against, and what it recorded. */
+export interface StaticRecording {
+    readonly cache: PipelineCache;
+    /** The material block's words the list started from: the pass's state, which entries patch. */
+    readonly start: Int32Array;
+    readonly startHash: number;
+    readonly cutout: string;
+    readonly surfaceKept: boolean;
+    /** Stamps compared at replay; any that moved makes the recording stale. */
+    cacheVersion: number;
+    groupEpoch: number;
+    storeEpoch: number;
+    ringEpoch: number;
+    /** The frame pass's commands, and the reflection pass's surface halves, with the record's offsets. */
+    readonly frame: CommandPool;
+    readonly surface: CommandPool;
+    /** Material slots pinned for these commands, and the material changes recording them asked for. */
+    readonly pins: number[];
+    materialAsks: number;
+    /** Under the screen-space skin blur a skin entry splits into halves no bundle replays. */
+    immediate: boolean;
+    /** Per copy, the bundles `executeBundles` takes; null until a copy is first replayed. */
+    readonly frameBundles: (readonly GPURenderBundle[] | null)[];
+    readonly surfaceBundles: (readonly GPURenderBundle[] | null)[];
+    /** The frame it was last replayed in, which picks the one to let go. */
+    usedIn: number;
+}
+export declare class GpuStaticDraws implements StaticDrawsList {
+    private readonly device;
+    readonly list: StaticDrawsList;
+    private readonly passSize;
+    private readonly viewSize;
+    disposed: boolean;
+    /** The draws' own slots, one a draw, written by the recording. */
+    readonly drawRing: UniformRing;
+    /** A pass block and a view block a copy. */
+    passes: UniformRing;
+    views: UniformRing;
+    /** Bumped whenever the three rings are made again, which invalidates every recording. */
+    ringEpoch: number;
+    /** The list's own lit groups and blank group, built over its rings by the renderer. */
+    groups: Map<unknown, unknown>;
+    blank: GPUBindGroup | null;
+    /** The group epoch the cache above was built in. */
+    groupEpoch: number;
+    /** The store epoch the list's pins were taken in: pins from before a forgetting are let go of. */
+    pinEpoch: number;
+    readonly recordings: StaticRecording[];
+    private copies;
+    private copyFrame;
+    constructor(device: GPUDevice, list: StaticDrawsList, passSize: number, viewSize: number, drawSize: number);
+    /** The captured entries, which the renderer replays to record them. */
+    get entries(): readonly StaticEntry[];
+    get draws(): number;
+    /**
+     * The next view's copy in frame `frame`, growing the copies when a frame asks for more than there
+     * are — which makes every recording stale, since the groups bound the old rings.
+     */
+    takeCopy(frame: number): number;
+    /** The two offsets copy `copy` binds. */
+    passOffset(copy: number): number;
+    viewOffset(copy: number): number;
+    /** Copy `copy`'s pass block, written whole. Uploaded by `uploadCopy`. */
+    writePass(copy: number, block: Int32Array): void;
+    /** Copy `copy`'s two blocks to the device, and no other copy's: each view writes only its own. */
+    uploadCopy(copy: number): void;
+    /** The draws' own slots, after a recording wrote them. */
+    uploadDraws(): void;
+    /** A recording that matches, if one does: the same target, starting state and side passes. */
+    find(cache: PipelineCache, start: Int32Array, startHash: number, cutout: string, surfaceKept: boolean): StaticRecording | null;
+    /** A new, empty recording, letting the least recently used go past the most kept. */
+    open(cache: PipelineCache, start: Int32Array, startHash: number, cutout: string, surfaceKept: boolean, unpin: (offset: number) => void): StaticRecording;
+    /** Empty a recording to record it again: its pins let go, its commands and bundles dropped. */
+    clear(recording: StaticRecording, unpin: (offset: number) => void): void;
+    /** Every recording, let go; what disposal and a forgetting store both do. */
+    forget(unpin: ((offset: number) => void) | null): void;
+    dispose(unpin: ((offset: number) => void) | null): void;
+    private growCopies;
+    /** Every copy's slot, taken once: a copy is a fixed offset, never handed out again. */
+    private claimCopies;
+}
+/** A command the recording takes in place of the frame graph's. */
+export declare function takeRecorded(pool: CommandPool): DrawCommand;
+/** What a render bundle must agree with: the pass it is executed in. */
+export interface BundleTarget {
+    readonly colorFormats: (GPUTextureFormat | null)[];
+    readonly depthStencilFormat: GPUTextureFormat;
+    readonly sampleCount: number;
+    readonly depthReadOnly: boolean;
+}
+/**
+ * One copy's bundle of a pool's commands: each lit command as recorded but for the pass and view
+ * offsets, which are the copy's. Allocates, and runs once a copy a recording, never per frame.
+ */
+export declare function encodeBundle(device: GPUDevice, target: BundleTarget, pool: CommandPool, passOffset: number, viewOffset: number, label: string): readonly GPURenderBundle[];

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

@@ -0,0 +1,242 @@
+import { createCommandPool, resetPool, takeCommand } from './drawCommand.js';
+import { UniformRing } from './uniformRing.js';
+const USAGE_UNIFORM_DST = 0x0040 | 0x0008;
+/** Views a list starts with room for: the frame's and one capture's. Doubles when a frame asks more. */
+const FIRST_COPIES = 2;
+/** Recordings a list keeps before letting the oldest go: a target and a starting state each. */
+const MOST_RECORDINGS = 4;
+export class GpuStaticDraws {
+    device;
+    list;
+    passSize;
+    viewSize;
+    disposed = false;
+    /** The draws' own slots, one a draw, written by the recording. */
+    drawRing;
+    /** A pass block and a view block a copy. */
+    passes;
+    views;
+    /** Bumped whenever the three rings are made again, which invalidates every recording. */
+    ringEpoch = 0;
+    /** The list's own lit groups and blank group, built over its rings by the renderer. */
+    groups = new Map();
+    blank = null;
+    /** The group epoch the cache above was built in. */
+    groupEpoch = -1;
+    /** The store epoch the list's pins were taken in: pins from before a forgetting are let go of. */
+    pinEpoch = -1;
+    recordings = [];
+    copies = 0;
+    copyFrame = -1;
+    constructor(device, list, passSize, viewSize, drawSize) {
+        this.device = device;
+        this.list = list;
+        this.passSize = passSize;
+        this.viewSize = viewSize;
+        this.drawRing = new UniformRing(device, drawSize, Math.max(1, list.draws), USAGE_UNIFORM_DST, 'static.draws');
+        this.passes = new UniformRing(device, passSize, FIRST_COPIES, USAGE_UNIFORM_DST, 'static.passes');
+        this.views = new UniformRing(device, viewSize, FIRST_COPIES, USAGE_UNIFORM_DST, 'static.views');
+        this.claimCopies();
+    }
+    /** The captured entries, which the renderer replays to record them. */
+    get entries() {
+        return this.list.entries;
+    }
+    get draws() {
+        return this.list.draws;
+    }
+    /**
+     * The next view's copy in frame `frame`, growing the copies when a frame asks for more than there
+     * are — which makes every recording stale, since the groups bound the old rings.
+     */
+    takeCopy(frame) {
+        if (frame !== this.copyFrame) {
+            this.copyFrame = frame;
+            this.copies = 0;
+        }
+        const copy = this.copies;
+        this.copies += 1;
+        if (copy >= this.passes.slots)
+            this.growCopies(this.passes.slots * 2);
+        return copy;
+    }
+    /** The two offsets copy `copy` binds. */
+    passOffset(copy) {
+        return copy * this.passes.slotSize;
+    }
+    viewOffset(copy) {
+        return copy * this.views.slotSize;
+    }
+    /** Copy `copy`'s pass block, written whole. Uploaded by `uploadCopy`. */
+    writePass(copy, block) {
+        this.passes.writeBlock(this.passOffset(copy), block);
+    }
+    /** Copy `copy`'s two blocks to the device, and no other copy's: each view writes only its own. */
+    uploadCopy(copy) {
+        this.passes.uploadSlot(this.passOffset(copy));
+        this.views.uploadSlot(this.viewOffset(copy));
+    }
+    /** The draws' own slots, after a recording wrote them. */
+    uploadDraws() {
+        this.drawRing.flush();
+    }
+    /** A recording that matches, if one does: the same target, starting state and side passes. */
+    find(cache, start, startHash, cutout, surfaceKept) {
+        for (const recording of this.recordings) {
+            if (recording.cache === cache &&
+                recording.startHash === startHash &&
+                recording.cutout === cutout &&
+                recording.surfaceKept === surfaceKept &&
+                sameWords(recording.start, start)) {
+                return recording;
+            }
+        }
+        return null;
+    }
+    /** A new, empty recording, letting the least recently used go past the most kept. */
+    open(cache, start, startHash, cutout, surfaceKept, unpin) {
+        if (this.recordings.length >= MOST_RECORDINGS) {
+            let oldest = 0;
+            for (let i = 1; i < this.recordings.length; i++) {
+                if (this.recordings[i].usedIn <
+                    this.recordings[oldest].usedIn)
+                    oldest = i;
+            }
+            const [gone] = this.recordings.splice(oldest, 1);
+            if (gone !== undefined)
+                release(gone, unpin);
+        }
+        const recording = {
+            cache,
+            start: new Int32Array(start),
+            startHash,
+            cutout,
+            surfaceKept,
+            cacheVersion: -1,
+            groupEpoch: -1,
+            storeEpoch: -1,
+            ringEpoch: -1,
+            frame: createCommandPool(this.list.draws),
+            surface: createCommandPool(0),
+            pins: [],
+            materialAsks: 0,
+            immediate: false,
+            frameBundles: [],
+            surfaceBundles: [],
+            usedIn: -1,
+        };
+        this.recordings.push(recording);
+        return recording;
+    }
+    /** Empty a recording to record it again: its pins let go, its commands and bundles dropped. */
+    clear(recording, unpin) {
+        release(recording, unpin);
+        resetPool(recording.frame);
+        resetPool(recording.surface);
+        recording.frameBundles.length = 0;
+        recording.surfaceBundles.length = 0;
+        recording.immediate = false;
+        recording.materialAsks = 0;
+    }
+    /** Every recording, let go; what disposal and a forgetting store both do. */
+    forget(unpin) {
+        for (const recording of this.recordings)
+            release(recording, unpin);
+        this.recordings.length = 0;
+    }
+    dispose(unpin) {
+        this.disposed = true;
+        this.forget(unpin);
+        this.drawRing.dispose();
+        this.passes.dispose();
+        this.views.dispose();
+    }
+    growCopies(copies) {
+        this.passes.dispose();
+        this.views.dispose();
+        this.passes = new UniformRing(this.device, this.passSize, copies, USAGE_UNIFORM_DST, 'static.passes');
+        this.views = new UniformRing(this.device, this.viewSize, copies, USAGE_UNIFORM_DST, 'static.views');
+        this.claimCopies();
+        this.ringEpoch += 1;
+        this.groups = new Map();
+        this.blank = null;
+    }
+    /** Every copy's slot, taken once: a copy is a fixed offset, never handed out again. */
+    claimCopies() {
+        for (let copy = 0; copy < this.passes.slots; copy++) {
+            this.passes.allocate();
+            this.views.allocate();
+        }
+    }
+}
+/** A command the recording takes in place of the frame graph's. */
+export function takeRecorded(pool) {
+    const command = pool.commands[takeCommand(pool)];
+    command.offsetCount = 0;
+    command.vertexCount = 0;
+    command.indexBuffer = null;
+    command.indexFormat = 'uint32';
+    command.indexed = false;
+    command.instances = 1;
+    command.indirect = null;
+    return command;
+}
+/**
+ * One copy's bundle of a pool's commands: each lit command as recorded but for the pass and view
+ * offsets, which are the copy's. Allocates, and runs once a copy a recording, never per frame.
+ */
+export function encodeBundle(device, target, pool, passOffset, viewOffset, label) {
+    const encoder = device.createRenderBundleEncoder({
+        label,
+        colorFormats: target.colorFormats,
+        depthStencilFormat: target.depthStencilFormat,
+        sampleCount: target.sampleCount,
+        depthReadOnly: target.depthReadOnly,
+        stencilReadOnly: target.depthReadOnly,
+    });
+    for (let i = 0; i < pool.taken; i++) {
+        const command = pool.commands[i];
+        if (command.pipeline === null || command.bindGroup === null)
+            continue;
+        if (command.offsetCount !== 4) {
+            throw new Error(`static draws: a recorded command bound ${command.offsetCount} offsets, not a lit draw's four`);
+        }
+        encoder.setPipeline(command.pipeline);
+        encoder.setBindGroup(0, command.bindGroup, [
+            command.offsetA,
+            passOffset,
+            command.offsetC,
+            viewOffset,
+        ]);
+        for (let slot = 0; slot < command.vertexCount; slot++) {
+            const buffer = command.vertexBuffers[slot];
+            if (buffer != null)
+                encoder.setVertexBuffer(slot, buffer);
+        }
+        if (command.indexed && command.indexBuffer !== null) {
+            encoder.setIndexBuffer(command.indexBuffer, command.indexFormat);
+            if (command.indirect !== null)
+                encoder.drawIndexedIndirect(command.indirect, 0);
+            else
+                encoder.drawIndexed(command.count, command.instances);
+        }
+        else {
+            encoder.draw(command.count, command.instances);
+        }
+    }
+    return [encoder.finish({ label })];
+}
+function release(recording, unpin) {
+    if (unpin !== null)
+        for (const offset of recording.pins)
+            unpin(offset);
+    recording.pins.length = 0;
+}
+function sameWords(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}

package/dist/render/backend/webgpu/surfaceTexturePass.d.ts

@@ -1,7 +1,7 @@
 import type { SurfaceTextureOptions } from '../../surfaceTexture.ts';
 import type { LightmapTexels } from '../../lightmap.ts';
 import type { SceneCaptureTexels } from '../../sceneCapture.ts';
-import type { CompressedTextureFormat, SurfaceSource } from '../../compressedSource.ts';
+import type { CompressedTextureFormat, CompressedTextureSource, SurfaceSource } from '../../compressedSource.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 /** How many levels an image of this size has, counting the one it arrives with. */
 export declare function mipLevelCount(width: number, height: number): number;
@@ -63,7 +63,9 @@ export declare class GpuSurfaceTexture {
     /** Its view, which the flat group binds beside this image when it is a material's albedo. */
     effectsView: GPUTextureView | null;
     /** The block format a compressed texture holds, or null for one uploaded from images. */
-    private readonly blockFormat;
+    private blockFormat;
+    /** Whether the image is colour, decoded from sRGB as it is sampled: what blocks swapped in keep. */
+    private readonly srgb;
     constructor(device: GPUDevice, pipelines: PipelineCache, source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels | SceneCaptureTexels, options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
     /** A view of every layer, as the shaders' `texture_2d_array` bindings read it. */
     private arrayView;
@@ -84,8 +86,13 @@ export declare class GpuSurfaceTexture {
      * hit that whenever the preview's decode won the race. The view is new then, and the texture it
      * replaced is handed back rather than destroyed: a draw recorded earlier in this frame may still
      * read it, so the renderer destroys it once nothing can, and drops every binding of the old view.
+     *
+     * **Blocks replace an image the same way**, at any size: a texture of their format holds them,
+     * read in the colour space this one was made for, and the image's is handed back. Refused, as a
+     * texture made from them would be, where `compressed` — the formats the device samples — does not
+     * take them. The way back is refused: an image cannot replace blocks.
      */
-    update(source: TexImageSource): GPUTexture | null;
+    update(source: TexImageSource | CompressedTextureSource, compressed?: readonly CompressedTextureFormat[]): GPUTexture | null;
     private allocate;
     dispose(): void;
     private upload;

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

@@ -3,7 +3,7 @@ import { toHalfFloats } from '../../halfFloat.js';
 import { isLightmapTexels } from '../../lightmap.js';
 import { isSceneCaptureTexels } from '../../sceneCapture.js';
 import { layerSize, refuseArrayUpdate, sourceSize } from '../../textureSource.js';
-import { compressedLayers, planBlocks, refuseBlockUpdate } from '../../compressedSource.js';
+import { compressedLayers, isCompressedSource, planBlocks, refuseBlockUpdate, } from '../../compressedSource.js';
 import { createCompressedTexture } from './compressedUpload.js';
 import { shaderModule } from './shaderModules.js';
 /**
@@ -154,6 +154,8 @@ export class GpuSurfaceTexture {
     effectsView = null;
     /** The block format a compressed texture holds, or null for one uploaded from images. */
     blockFormat;
+    /** Whether the image is colour, decoded from sRGB as it is sampled: what blocks swapped in keep. */
+    srgb;
     constructor(device, pipelines, source, options = {}, compressed = []) {
         this.device = device;
         this.pipelines = pipelines;
@@ -164,6 +166,7 @@ export class GpuSurfaceTexture {
         const listed = (baked !== null || capture !== null ? [] : Array.isArray(source) ? source : [source]);
         const blocks = compressedLayers(listed);
         const srgb = (options.colorSpace ?? 'linear') === 'srgb';
+        this.srgb = srgb;
         /* `SRGB8_ALPHA8`'s equivalent. Decoded in the sampler, before filtering, which is the only
            place it is correct — `surfaceTexture.ts` makes the argument in full. A capture takes the
            world's own format, which its pass resolves into. */
@@ -294,12 +297,27 @@ export class GpuSurfaceTexture {
      * hit that whenever the preview's decode won the race. The view is new then, and the texture it
      * replaced is handed back rather than destroyed: a draw recorded earlier in this frame may still
      * read it, so the renderer destroys it once nothing can, and drops every binding of the old view.
+     *
+     * **Blocks replace an image the same way**, at any size: a texture of their format holds them,
+     * read in the colour space this one was made for, and the image's is handed back. Refused, as a
+     * texture made from them would be, where `compressed` — the formats the device samples — does not
+     * take them. The way back is refused: an image cannot replace blocks.
      */
-    update(source) {
+    update(source, compressed = []) {
         const replaced = this.texture;
         if (replaced === null)
             return null;
         refuseArrayUpdate(this.layers);
+        if (isCompressedSource(source)) {
+            const plan = planBlocks([source], this.srgb, compressed);
+            this.blockFormat = source.format;
+            this.width = source.width;
+            this.height = source.height;
+            this.levels = this.mipmapped ? plan.levels : 1;
+            this.texture = createCompressedTexture(this.device, plan.name, [source], this.levels);
+            this.current = this.arrayView(this.texture);
+            return replaced;
+        }
         refuseBlockUpdate(this.blockFormat);
         const { width, height } = sourceSize(source);
         if (width === this.width && height === this.height) {

package/dist/render/backend/webgpu/uniformRing.d.ts

@@ -7,6 +7,21 @@ import type { BudgetCounter } from '../budget.ts';
  * an alignment restated somewhere else is an alignment that can disagree.
  */
 export declare const DYNAMIC_ALIGNMENT = 256;
+/**
+ * The most staging one ring may hold, and therefore the most device memory it may take.
+ *
+ * **A ceiling on the growth, because a runaway consumer should degrade rather than crash.** Past
+ * this the ring refuses to grow and goes on skipping work and reporting it, which is the right end
+ * state for a frame asking for something no device should be asked for. What growth changes is
+ * where that line sits: at a number chosen against a phone's memory rather than at whatever the
+ * ring happened to be constructed with.
+ *
+ * Sixty-four mebibytes is far past any legitimate scene — the flat vertex ring's slot is 1,540
+ * bytes, so this is forty-three thousand draws, and the fragment ring's is at most 13,312, which
+ * is five thousand material changes in one frame. The device buffer matches the staging, so a ring
+ * at this ceiling holds 128 MiB in total and only ever reaches it by being asked to.
+ */
+export declare const MAX_RING_BYTES: number;
 /**
  * Per-draw uniforms, in slots, written once and bound by offset.
  *
@@ -159,5 +174,11 @@ export declare class UniformRing {
      * staging without passing a method that lowers `clean` — which is why the staging stays private.
      */
     flush(): void;
+    /**
+     * Upload one slot now, and nothing else: for a ring whose slots are all claimed once and written
+     * one at a time — a static list's copies — where `flush` would send every slot above the lowest
+     * one written. Leaves the watermark as it was, so a later `flush` still owes what it owed.
+     */
+    uploadSlot(slot: number): void;
     dispose(): void;
 }

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

@@ -20,7 +20,7 @@ export const DYNAMIC_ALIGNMENT = 256;
  * is five thousand material changes in one frame. The device buffer matches the staging, so a ring
  * at this ceiling holds 128 MiB in total and only ever reaches it by being asked to.
  */
-const MAX_RING_BYTES = 64 * 1024 * 1024;
+export const MAX_RING_BYTES = 64 * 1024 * 1024;
 /**
  * Per-draw uniforms, in slots, written once and bound by offset.
  *
@@ -252,6 +252,14 @@ export class UniformRing {
         this.device.queue.writeBuffer(this.buffer, from, this.staging, from, end - from);
         this.clean = end;
     }
+    /**
+     * Upload one slot now, and nothing else: for a ring whose slots are all claimed once and written
+     * one at a time — a static list's copies — where `flush` would send every slot above the lowest
+     * one written. Leaves the watermark as it was, so a later `flush` still owes what it owed.
+     */
+    uploadSlot(slot) {
+        this.device.queue.writeBuffer(this.buffer, slot, this.staging, slot, this.slotSize);
+    }
     dispose() {
         this.buffer.destroy();
     }

package/dist/render/backend/webgpu/vertexFormats.d.ts

@@ -0,0 +1,22 @@
+import { type AttributePacking, type VertexPacking } from '../../vertexPacking.ts';
+/** The key's suffix for this packing: one word each attribute not travelling as floats. */
+export declare function packingKey(packing: VertexPacking): string;
+/** Mark this packing in a pipeline's `present`, which is what `vertexBufferLayouts` reads. */
+export declare function markPacking(present: Record<string, boolean>, packing: VertexPacking): void;
+/** Mark the packing a mesh's key names, for a pass that has the mesh and not its data. */
+export declare function markPackingOfKey(present: Record<string, boolean>, key: string): void;
+/** How `present` says this attribute travels: floats unless a word says otherwise. */
+export declare function packingIn(present: Readonly<Record<string, boolean>>, name: string): AttributePacking;
+/** The format an attribute is read with, packed this way, or `float` as given. */
+export declare function packedFormat(float: GPUVertexFormat, packing: AttributePacking): GPUVertexFormat;
+/** Bytes a vertex spends on one attribute read with `format`. */
+export declare function formatBytes(format: GPUVertexFormat): number;
+/**
+ * One attribute of vertices `from` to `to` into its sixteen-bit field of the interleaved rows,
+ * `scale` being `SNORM16_ONE` or `UNORM16_ONE`. Rounded by `toFixed16`, as `fixedArray` rounds
+ * for the other backend; the range was checked when the packing was chosen.
+ *
+ * Unrolled by width, as `interleaveField` is and for its reason: the general loop was most of a
+ * heavy load's upload. Three and four are the widths a packed attribute has.
+ */
+export declare function interleaveFixed(rows: Int16Array | Uint16Array, source: Float32Array, width: number, step: number, fieldOffset: number, from: number, to: number, scale: number): void;

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

@@ -0,0 +1,97 @@
+import { PACKED_ATTRIBUTES, toFixed16, } from '../../vertexPacking.js';
+/**
+ * A mesh's packed attributes as a WebGPU vertex reads them: each one's format and bytes, the words
+ * a pipeline key carries for them, and the writers that put sixteen-bit fixed point into the
+ * interleaved rows. What is packed how is `vertexPacking.ts`'s decision; this is only its binding.
+ *
+ * **Sixteen-bit fields are four wide, never three**, because WebGPU has no three-component
+ * sixteen-bit format: a normal or a colour takes `x4` and leaves the fourth zero, and the shader's
+ * `vec3` input reads the first three. So a normal costs eight bytes here against six on WebGL2,
+ * which reads three. Every field stays a whole number of four-byte words, so a vertex does too.
+ */
+/** The ways an attribute can travel other than as floats, as the key words name them. */
+const PACKINGS = ['snorm16', 'unorm16', 'constant'];
+/** The pipeline key's word for one attribute's packing. Not a prefix of any other word. */
+function word(name, packing) {
+    return `${name}~${packing}`;
+}
+/** The key's suffix for this packing: one word each attribute not travelling as floats. */
+export function packingKey(packing) {
+    let key = '';
+    for (const name of PACKED_ATTRIBUTES) {
+        if (packing[name] !== 'float')
+            key += `:${word(name, packing[name])}`;
+    }
+    return key;
+}
+/** Mark this packing in a pipeline's `present`, which is what `vertexBufferLayouts` reads. */
+export function markPacking(present, packing) {
+    for (const name of PACKED_ATTRIBUTES) {
+        if (packing[name] !== 'float')
+            present[word(name, packing[name])] = true;
+    }
+}
+/** Mark the packing a mesh's key names, for a pass that has the mesh and not its data. */
+export function markPackingOfKey(present, key) {
+    for (const name of PACKED_ATTRIBUTES) {
+        for (const packing of PACKINGS) {
+            if (key.includes(`:${word(name, packing)}`))
+                present[word(name, packing)] = true;
+        }
+    }
+}
+/** How `present` says this attribute travels: floats unless a word says otherwise. */
+export function packingIn(present, name) {
+    for (const packing of PACKINGS) {
+        if (present[word(name, packing)] === true)
+            return packing;
+    }
+    return 'float';
+}
+/** The format an attribute is read with, packed this way, or `float` as given. */
+export function packedFormat(float, packing) {
+    if (packing === 'snorm16')
+        return 'snorm16x4';
+    if (packing === 'unorm16')
+        return 'unorm16x4';
+    return float;
+}
+/** Bytes a vertex spends on one attribute read with `format`. */
+export function formatBytes(format) {
+    if (format === 'snorm16x4' || format === 'unorm16x4')
+        return 8;
+    if (format === 'float32x4')
+        return 16;
+    if (format === 'float32x3')
+        return 12;
+    if (format === 'float32x2')
+        return 8;
+    return 4;
+}
+/**
+ * One attribute of vertices `from` to `to` into its sixteen-bit field of the interleaved rows,
+ * `scale` being `SNORM16_ONE` or `UNORM16_ONE`. Rounded by `toFixed16`, as `fixedArray` rounds
+ * for the other backend; the range was checked when the packing was chosen.
+ *
+ * Unrolled by width, as `interleaveField` is and for its reason: the general loop was most of a
+ * heavy load's upload. Three and four are the widths a packed attribute has.
+ */
+export function interleaveFixed(rows, source, width, step, fieldOffset, from, to, scale) {
+    let write = from * step + fieldOffset;
+    const end = to * width;
+    if (width === 3) {
+        for (let read = from * 3; read < end; read += 3, write += step) {
+            rows[write] = toFixed16(source[read], scale);
+            rows[write + 1] = toFixed16(source[read + 1], scale);
+            rows[write + 2] = toFixed16(source[read + 2], scale);
+        }
+    }
+    else {
+        for (let read = from * 4; read < end; read += 4, write += step) {
+            rows[write] = toFixed16(source[read], scale);
+            rows[write + 1] = toFixed16(source[read + 1], scale);
+            rows[write + 2] = toFixed16(source[read + 2], scale);
+            rows[write + 3] = toFixed16(source[read + 3], scale);
+        }
+    }
+}

package/dist/render/bloomChain.d.ts

@@ -62,7 +62,7 @@ export declare function bloomProfileWarning(quality: {
  * already takes. Absent, or a field absent, is the response every frame had before 4.8.6.
  *
  * **Why it exists: one band over the colour less the threshold washes a stage built for another
- * engine.** Unreal's standard bloom keeps `saturate((L − threshold) / 2)` of a colour rather than
+ * engine.** A ramped bloom keeps `saturate((L − threshold) / 2)` of a colour rather than
  * the colour less the threshold, and spreads it over six bands, each in a tint of its own. A
  * stage authored against that — a threshold of 0.1 and tints summing below one — came out white
  * here, because subtracting so low a threshold keeps nearly every light in the frame at full
@@ -72,8 +72,8 @@ export interface BloomResponse {
     /**
      * Scene units over which a colour comes in, from none of it at the threshold to all of it this
      * far past. **0, the default, subtracts instead**: a colour keeps what it has past the threshold,
-     * the response since bloom shipped. Unreal's is 2 after exposure, so a frame exposed by `e` that
-     * wants it passes `2 / e`, as it passes the threshold over the exposure.
+     * the response since bloom shipped. A ramped bloom's is 2 after exposure, so a frame exposed by
+     * `e` that wants it passes `2 / e`, as it passes the threshold over the exposure.
      *
      * Brightness is still the largest channel rather than luminance, for the reason
      * `shaders/bloom.ts` gives; on a neutral colour the two are equal.