@driftengine/core 4.8.2 → 4.8.4

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

@@ -0,0 +1,253 @@
+/**
+ * Skin's screen-space scattering on this backend: the targets, the kept draws and the two passes
+ * that spread them. `skinBlur.ts` is what the blur computes and why; this is where it runs.
+ *
+ * **What the renderer hands it.** Each skin draw, recorded into the frame with its diffuse taken
+ * out, is recorded a second time here with the diffuse alone. When the frame first draws something
+ * blended — or ends, if nothing is — the renderer ends its pass and calls `drawDiffuse`, which
+ * replays them into a half-float target against the frame's own depth; resolves the depth; and
+ * calls `spread`, which blurs across into a second target and then down, adding into the frame.
+ *
+ * **The draws are commands, not calls**, for the reason `LatePass` keeps its own pool: the frame
+ * graph's is spent at every flush, and these are replayed after the flush that ends the frame's
+ * pass. Each holds the per-draw ring slot its frame half used, and those stay valid until the
+ * encoder is replaced, which is after this has run.
+ *
+ * **What it costs**: every skin draw twice; two half-float targets the size of the frame, and a
+ * third multisampled one under multisampling; a depth resolve; and two full-screen passes that
+ * leave at once wherever no skin was drawn.
+ */
+import { SKIN_PROFILES } from '../../skinBlur.js';
+import { SKINBLUR_BINDINGS, SKIN_BLUR_FRAG_WGSL } from '../../shaders/generated/skinBlur.wgsl.js';
+import { SCENE_ALPHA_KEEPS } from '../../sceneCoverage.js';
+import { createCommandPool, resetPool, takeCommand } from './drawCommand.js';
+import { createPostStageLayout, postPipeline, postPipelineTargets } from './postPass.js';
+import { DYNAMIC_ALIGNMENT } from './uniformRing.js';
+const BINDINGS = SKINBLUR_BINDINGS.SKIN_BLUR_FRAG;
+const SLOT = Math.ceil(BINDINGS.uniformSize / DYNAMIC_ALIGNMENT) * DYNAMIC_ALIGNMENT;
+const USAGE_TARGET = 0x10 | 0x4; // RENDER_ATTACHMENT | TEXTURE_BINDING
+const USAGE_UNIFORM_DST = 0x40 | 0x8; // UNIFORM | COPY_DST
+/** The format the diffuse lands in: half floats, because it is linear light before any grade. */
+export const SKIN_TARGET_FORMAT = 'rgba16float';
+export class SkinScatterPass {
+    device;
+    layout;
+    uniforms;
+    staging = new Float32Array((SLOT * 2) / 4);
+    linear;
+    nearest;
+    commands = createCommandPool(16);
+    /** Each profile's scatter distance per channel, in metres: four floats a profile. */
+    profiles = new Float32Array(SKIN_PROFILES * 4);
+    diffuse = null;
+    diffuseMsaa = null;
+    across = null;
+    diffuseView = null;
+    diffuseMsaaView = null;
+    acrossView = null;
+    groupAcross = null;
+    groupDown = null;
+    groupsDepth = null;
+    constructor(device) {
+        this.device = device;
+        this.layout = createPostStageLayout(device, BINDINGS.uniforms, BINDINGS.uniformSize, [
+            { binding: BINDINGS.textures.uSkin },
+            { binding: BINDINGS.textures.uDepth, filterable: false },
+        ]);
+        this.uniforms = device.createBuffer({
+            label: 'skin.blurUniforms',
+            size: SLOT * 2,
+            usage: USAGE_UNIFORM_DST,
+        });
+        this.linear = device.createSampler({
+            label: 'skin.linear',
+            magFilter: 'linear',
+            minFilter: 'linear',
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge',
+        });
+        this.nearest = device.createSampler({
+            label: 'skin.nearest',
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge',
+        });
+    }
+    /** Whether any skin was kept for this frame. */
+    get pending() {
+        return this.commands.taken > 0;
+    }
+    /** A command for one skin draw's diffuse half, filled by the caller. */
+    take() {
+        return this.commands.commands[takeCommand(this.commands)];
+    }
+    /** What one profile scatters, per channel, in metres: the last material to name it says. */
+    setProfile(index, r, g, b) {
+        const at = Math.min(Math.max(Math.round(index), 0), SKIN_PROFILES - 1) * 4;
+        this.profiles[at] = r;
+        this.profiles[at + 1] = g;
+        this.profiles[at + 2] = b;
+    }
+    /** The targets at the frame's size and sample count, made again only when either changes. */
+    size(width, height, samples) {
+        if (this.diffuse !== null &&
+            this.diffuse.width === width &&
+            this.diffuse.height === height &&
+            samples > 1 === (this.diffuseMsaa !== null) &&
+            (this.diffuseMsaa === null || this.diffuseMsaa.sampleCount === samples)) {
+            return;
+        }
+        this.releaseTargets();
+        const make = (label, count) => this.device.createTexture({
+            label,
+            size: [width, height],
+            format: SKIN_TARGET_FORMAT,
+            sampleCount: count,
+            usage: count > 1 ? 0x10 : USAGE_TARGET,
+        });
+        this.diffuse = make('skin.diffuse', 1);
+        this.across = make('skin.across', 1);
+        this.diffuseMsaa = samples > 1 ? make('skin.diffuseMsaa', samples) : null;
+        this.diffuseView = this.diffuse.createView();
+        this.acrossView = this.across.createView();
+        this.diffuseMsaaView = this.diffuseMsaa?.createView() ?? null;
+        this.groupAcross = null;
+        this.groupDown = null;
+    }
+    /**
+     * Every kept draw's diffuse into the target, against the frame's own depth, which it reads and
+     * does not write. Called with no pass open on `encoder`.
+     */
+    drawDiffuse(encoder, depth, issue, timestampWrites) {
+        const target = this.diffuseView;
+        if (target === null)
+            return;
+        const pass = encoder.beginRenderPass({
+            label: 'skin.diffuse',
+            timestampWrites,
+            colorAttachments: [
+                {
+                    view: this.diffuseMsaaView ?? target,
+                    resolveTarget: this.diffuseMsaaView === null ? undefined : target,
+                    clearValue: [0, 0, 0, 0],
+                    loadOp: 'clear',
+                    storeOp: this.diffuseMsaaView === null ? 'store' : 'discard',
+                },
+            ],
+            depthStencilAttachment: { view: depth, depthLoadOp: 'load', depthStoreOp: 'store' },
+        });
+        for (let i = 0; i < this.commands.taken; i += 1) {
+            issue(pass, this.commands.commands[i]);
+        }
+        pass.end();
+    }
+    /**
+     * Across into the second target, then down and added into the frame's colour — `frame` the
+     * attachment its pass draws into, `resolve` where a multisampled one resolves, `samples` its
+     * count. `projection` is the frame's, `height` the frame's height in pixels.
+     */
+    spread(encoder, pipelines, depth, frame, resolve, samples, projection, inverseProjection, timestampWrites) {
+        const diffuse = this.diffuse;
+        if (diffuse === null || this.diffuseView === null || this.acrossView === null)
+            return;
+        if (this.groupAcross === null || this.groupDown === null || this.groupsDepth !== depth) {
+            this.groupAcross = this.group('skin.blurAcross', this.diffuseView, depth);
+            this.groupDown = this.group('skin.blurDown', this.acrossView, depth);
+            this.groupsDepth = depth;
+        }
+        this.writeUniforms(diffuse.width, diffuse.height, projection, inverseProjection);
+        const across = postPipeline(pipelines, this.device, this.layout, 'skin.blurAcross', SKIN_BLUR_FRAG_WGSL, SKIN_TARGET_FORMAT);
+        const down = postPipelineTargets(pipelines, this.device, this.layout, `skin.blurDown:${pipelines.format}:${samples}`, SKIN_BLUR_FRAG_WGSL, [
+            {
+                format: pipelines.format,
+                /* Added: its colour onto the frame's, the frame's alpha kept. */
+                blend: {
+                    color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+                    alpha: SCENE_ALPHA_KEEPS,
+                },
+            },
+        ], samples);
+        const first = encoder.beginRenderPass({
+            label: 'skin.blurAcross',
+            timestampWrites: timestampWrites(),
+            colorAttachments: [
+                { view: this.acrossView, clearValue: [0, 0, 0, 0], loadOp: 'clear', storeOp: 'store' },
+            ],
+        });
+        first.setPipeline(across);
+        first.setBindGroup(0, this.groupAcross, [0]);
+        first.draw(3);
+        first.end();
+        const second = encoder.beginRenderPass({
+            label: 'skin.blurDown',
+            timestampWrites: timestampWrites(),
+            colorAttachments: [
+                {
+                    view: frame,
+                    resolveTarget: resolve ?? undefined,
+                    loadOp: 'load',
+                    storeOp: 'store',
+                },
+            ],
+        });
+        second.setPipeline(down);
+        second.setBindGroup(0, this.groupDown, [SLOT]);
+        second.draw(3);
+        second.end();
+    }
+    /** Spent at the frame's start: the kept draws were this frame's. */
+    reset() {
+        resetPool(this.commands);
+    }
+    dispose() {
+        this.releaseTargets();
+        this.uniforms.destroy();
+    }
+    group(label, skin, depth) {
+        return this.device.createBindGroup({
+            label,
+            layout: this.layout,
+            entries: [
+                {
+                    binding: BINDINGS.uniforms,
+                    resource: { buffer: this.uniforms, size: BINDINGS.uniformSize },
+                },
+                { binding: BINDINGS.textures.uSkin.texture, resource: skin },
+                { binding: BINDINGS.textures.uSkin.sampler, resource: this.linear },
+                { binding: BINDINGS.textures.uDepth.texture, resource: depth },
+                { binding: BINDINGS.textures.uDepth.sampler, resource: this.nearest },
+            ],
+        });
+    }
+    /** Both axes' blocks: the step along each, and what they share. Column-major matrices. */
+    writeUniforms(width, height, projection, inverse) {
+        const f = this.staging;
+        const fields = BINDINGS.fields;
+        for (let axis = 0; axis < 2; axis += 1) {
+            const base = (axis * SLOT) / 4;
+            f[base + fields.uStep.offset / 4] = axis === 0 ? 1 / width : 0;
+            f[base + fields.uStep.offset / 4 + 1] = axis === 0 ? 0 : 1 / height;
+            /* The four terms that carry a depth back to view-space metres: the occlusion blur's own. */
+            const toZ = base + fields.uDepthToViewZ.offset / 4;
+            f[toZ] = inverse[10] ?? 0;
+            f[toZ + 1] = inverse[14] ?? 0;
+            f[toZ + 2] = inverse[11] ?? 0;
+            f[toZ + 3] = inverse[15] ?? 1;
+            /* Pixels a metre spans at a metre: the vertical focal length, which is the horizontal one
+               too wherever a pixel is square. */
+            f[base + fields.uFocal.offset / 4] = (projection[5] * height) / 2;
+            f.set(this.profiles, base + fields.uProfiles.offset / 4);
+        }
+        this.device.queue.writeBuffer(this.uniforms, 0, f);
+    }
+    releaseTargets() {
+        this.diffuse?.destroy();
+        this.diffuseMsaa?.destroy();
+        this.across?.destroy();
+        this.diffuse = null;
+        this.diffuseMsaa = null;
+        this.across = null;
+        this.diffuseView = null;
+        this.diffuseMsaaView = null;
+        this.acrossView = null;
+    }
+}

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

@@ -1,4 +1,5 @@
 import type { SurfaceTextureOptions } from '../../surfaceTexture.ts';
+import type { CompressedTextureFormat, 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;
@@ -59,7 +60,9 @@ export declare class GpuSurfaceTexture {
     private effectsTable;
     /** Its view, which the flat group binds beside this image when it is a material's albedo. */
     effectsView: GPUTextureView | null;
-    constructor(device: GPUDevice, pipelines: PipelineCache, source: TexImageSource | readonly TexImageSource[], options?: SurfaceTextureOptions);
+    /** The block format a compressed texture holds, or null for one uploaded from images. */
+    private readonly blockFormat;
+    constructor(device: GPUDevice, pipelines: PipelineCache, source: SurfaceSource | readonly SurfaceSource[], options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
     /** A view of every layer, as the shaders' `texture_2d_array` bindings read it. */
     private arrayView;
     /** The view every binding of this image holds. A new one when `update` changes the size. */

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

@@ -1,6 +1,8 @@
 import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from '../../surfaceEffects.js';
 import { toHalfFloats } from '../../halfFloat.js';
-import { isSourceList, layerSize, refuseArrayUpdate, sourceSize } from '../../textureSource.js';
+import { layerSize, refuseArrayUpdate, sourceSize } from '../../textureSource.js';
+import { compressedLayers, planBlocks, refuseBlockUpdate } from '../../compressedSource.js';
+import { createCompressedTexture } from './compressedUpload.js';
 import { shaderModule } from './shaderModules.js';
 /**
  * A caller's image on the device, and the mip chain WebGPU will not build for it.
@@ -148,20 +150,41 @@ export class GpuSurfaceTexture {
     effectsTable = null;
     /** Its view, which the flat group binds beside this image when it is a material's albedo. */
     effectsView = null;
-    constructor(device, pipelines, source, options = {}) {
+    /** The block format a compressed texture holds, or null for one uploaded from images. */
+    blockFormat;
+    constructor(device, pipelines, source, options = {}, compressed = []) {
         this.device = device;
         this.pipelines = pipelines;
-        const sources = isSourceList(source) ? source : [source];
-        const { width, height } = layerSize(sources);
-        this.layers = sources.length;
-        this.mipmapped = options.mipmap ?? true;
+        const listed = (Array.isArray(source) ? source : [source]);
+        const blocks = compressedLayers(listed);
+        const srgb = (options.colorSpace ?? 'linear') === '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. */
-        this.format = (options.colorSpace ?? 'linear') === 'srgb' ? 'rgba8unorm-srgb' : 'rgba8unorm';
-        this.width = width;
-        this.height = height;
-        this.levels = this.mipmapped ? mipLevelCount(width, height) : 1;
-        this.texture = this.allocate();
+        this.format = srgb ? 'rgba8unorm-srgb' : 'rgba8unorm';
+        if (blocks !== null) {
+            /* Refused before anything is allocated; the stored chain, or level 0 alone where no chain
+               was asked for. See `compressedUpload.ts`. */
+            const plan = planBlocks(blocks, srgb, compressed);
+            const first = blocks[0];
+            this.layers = blocks.length;
+            this.blockFormat = first.format;
+            this.mipmapped = (options.mipmap ?? true) && plan.levels > 1;
+            this.width = first.width;
+            this.height = first.height;
+            this.levels = this.mipmapped ? plan.levels : 1;
+            this.texture = createCompressedTexture(device, plan.name, blocks, this.levels);
+        }
+        else {
+            const sources = listed;
+            const { width, height } = layerSize(sources);
+            this.layers = sources.length;
+            this.blockFormat = null;
+            this.mipmapped = options.mipmap ?? true;
+            this.width = width;
+            this.height = height;
+            this.levels = this.mipmapped ? mipLevelCount(width, height) : 1;
+            this.texture = this.allocate();
+        }
         this.current = this.arrayView(this.texture);
         const wrap = (options.wrap ?? 'repeat') === 'repeat' ? 'repeat' : 'clamp-to-edge';
         /*
@@ -193,7 +216,8 @@ export class GpuSurfaceTexture {
                 ? Math.max(1, Math.floor(options.anisotropy ?? DEFAULT_ANISOTROPY))
                 : 1,
         });
-        this.upload(sources);
+        if (blocks === null)
+            this.upload(listed);
         /* Half floats, as `renderer.ts` uploads it: filterable, so the ordinary float layout takes it,
            and read by `textureLoad` alone, so the filter never runs. */
         const effects = options.effects ?? [];
@@ -236,6 +260,7 @@ export class GpuSurfaceTexture {
         if (replaced === null)
             return null;
         refuseArrayUpdate(this.layers);
+        refuseBlockUpdate(this.blockFormat);
         const { width, height } = sourceSize(source);
         if (width === this.width && height === this.height) {
             this.upload([source]);

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

@@ -3,6 +3,7 @@ import { TEXT_BINDINGS, TEXT_FRAG_WGSL, TEXT_VERT_WGSL, } from '../../shaders/ge
 import { MAX_CELLS, TEXT_CUBE, TextLayout } from '../../textLayout.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The text pass: a string as instanced glyph cubes, drawn over the scene.
  *
@@ -174,7 +175,7 @@ export function textPipeline(cache, device, layout) {
                     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' },
+                        alpha: SCENE_ALPHA_COVERS,
                     },
                 },
             ],

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

@@ -3,6 +3,7 @@ import { WATER_BINDINGS, WATER_FRAG_WGSL, WATER_VERT_WGSL, } from '../../shaders
 import { PATCH_RESOLUTION, buildUnitSheet, buildWaterGrid } from '../../waterGrid.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The water pass: two sheets and a patch, displaced by a wave field in the vertex stage.
  *
@@ -148,7 +149,7 @@ export function waterPipeline(cache, device, layout) {
                     format: cache.format,
                     blend: {
                         color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-                        alpha: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: SCENE_ALPHA_COVERS,
                     },
                 },
             ],

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

@@ -3,6 +3,7 @@ import { WINDSTREAKS_BINDINGS, WIND_STREAK_FRAG_WGSL, WIND_STREAK_VERT_WGSL, } f
 import { buildWindStreakLattice } from '../../windStreakDraw.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The wind-streak pass: a lattice of debris that follows the camera and wraps.
  *
@@ -141,7 +142,7 @@ export function windStreakPipeline(cache, device, layout) {
                             dstFactor: 'one-minus-src-alpha',
                             operation: 'add',
                         },
-                        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: SCENE_ALPHA_COVERS,
                     },
                 },
             ],

package/dist/render/boltBatch.js

@@ -1,6 +1,7 @@
 import { compileProgram, uniformLocations } from './shader.js';
 import { BOLT_FRAG, BOLT_VERT } from './shaders/bolt.js';
 import { buildSegmentQuads, expandBoltSegments } from './segmentQuads.js';
+import { blendKeeping } from './sceneCoverage.js';
 /**
  * One draw call for a pool of electrical arcs.
  *
@@ -80,7 +81,7 @@ export class BoltBatch {
         if (segmentCount === 0)
             return;
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+        blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.bindVertexArray(this.vao);

package/dist/render/causticsRenderer.js

@@ -3,6 +3,7 @@ import { CAUSTICS_FRAG, CAUSTICS_VERT } from './shaders/caustics.js';
 import { bindAtmosphere } from './atmosphere.js';
 import { buildSheets } from './surfaceSheet.js';
 import { seaStateForWind } from './seaState.js';
+import { blendKeeping } from './sceneCoverage.js';
 /**
  * How far from the water the effect has died out.
  *
@@ -97,7 +98,7 @@ export class CausticsRenderer {
         gl.uniform1f(u['uWaveGain'] ?? null, sea.steepness);
         bindAtmosphere(gl, u, atmosphere, camera.position[1] ?? 0, underwaterEnabled);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.ONE, gl.ONE);
+        blendKeeping(gl, gl.ONE, gl.ONE);
         /*
          * No depth write, but depth *testing* stays on: the sheet sits a couple of
          * centimetres under the surface it lights, so geometry in front of it — the

package/dist/render/clothBindingData.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A mesh's cloth binding as data, and the texel layouts both backends upload it in.
+ *
+ * **What a consumer hands over** is per render vertex: the simulation triangle it follows (three
+ * particle indices — the same index three times for a vertex that follows one particle), where on
+ * it (barycentric u and v for the second and third particle), how far along the triangle's normal,
+ * and how much it follows at all (0 skinned, 1 cloth — commonly painted into a vertex colour); and
+ * the particles' rest positions in the mesh's model space. A garment's port decodes all of this
+ * from the cooked data; the engine owns placing the vertices, in `shaders/clothBinding.ts`.
+ *
+ * **Textures wrap onto rows of at most 2048 texels**, the width WebGL2 guarantees, padded to whole
+ * rows: a garment of 40,000 vertices is 80,000 binding texels, 40 rows. Validated by name before a
+ * byte goes to a device, because an index past the particles reads the padding — a vertex pinned
+ * to the origin, which looks like a broken rig rather than a bad binding.
+ */
+/** A mesh's cloth binding, one entry a render vertex unless said otherwise. */
+export interface ClothBindingData {
+    /** Three particle indices a vertex. */
+    readonly triangles: Uint32Array;
+    /** Barycentric u and v a vertex, for the second and third particle; the first takes the rest. */
+    readonly coordinates: Float32Array;
+    /** Metres along the triangle's normal. */
+    readonly offsets: Float32Array;
+    /** How much of the cloth's place a vertex takes: 0 skinned, 1 cloth. */
+    readonly weights: Float32Array;
+    /** The particles at rest, three floats each, in the mesh's model space. */
+    readonly rest: Float32Array;
+}
+/** The widest row a texture is wrapped onto. */
+export declare const CLOTH_TEXTURE_WIDTH = 2048;
+/** A texture of `texels`, wrapped onto rows. */
+export declare function clothTextureSize(texels: number): {
+    width: number;
+    height: number;
+};
+/** Refuse a binding whose arrays disagree with a mesh of `vertices`, or that names a missing particle. */
+export declare function validateClothBinding(data: ClothBindingData, vertices: number): void;
+/** The binding as RGBA float texels, two a vertex, padded to whole rows. */
+export declare function packClothBinding(data: ClothBindingData): Float32Array;
+/** Particles, three floats each, into RGBA texels in `out`. Allocation-free, for every frame. */
+export declare function packClothParticles(positions: Float32Array, out: Float32Array): void;

package/dist/render/clothBindingData.js

@@ -0,0 +1,72 @@
+/**
+ * A mesh's cloth binding as data, and the texel layouts both backends upload it in.
+ *
+ * **What a consumer hands over** is per render vertex: the simulation triangle it follows (three
+ * particle indices — the same index three times for a vertex that follows one particle), where on
+ * it (barycentric u and v for the second and third particle), how far along the triangle's normal,
+ * and how much it follows at all (0 skinned, 1 cloth — commonly painted into a vertex colour); and
+ * the particles' rest positions in the mesh's model space. A garment's port decodes all of this
+ * from the cooked data; the engine owns placing the vertices, in `shaders/clothBinding.ts`.
+ *
+ * **Textures wrap onto rows of at most 2048 texels**, the width WebGL2 guarantees, padded to whole
+ * rows: a garment of 40,000 vertices is 80,000 binding texels, 40 rows. Validated by name before a
+ * byte goes to a device, because an index past the particles reads the padding — a vertex pinned
+ * to the origin, which looks like a broken rig rather than a bad binding.
+ */
+/** The widest row a texture is wrapped onto. */
+export const CLOTH_TEXTURE_WIDTH = 2048;
+/** A texture of `texels`, wrapped onto rows. */
+export function clothTextureSize(texels) {
+    const width = Math.max(1, Math.min(CLOTH_TEXTURE_WIDTH, texels));
+    return { width, height: Math.max(1, Math.ceil(texels / width)) };
+}
+/** Refuse a binding whose arrays disagree with a mesh of `vertices`, or that names a missing particle. */
+export function validateClothBinding(data, vertices) {
+    const count = data.weights.length;
+    const fail = (what) => {
+        throw new Error(`cloth binding: ${what}`);
+    };
+    if (count !== vertices)
+        fail(`binds ${count} vertices and the mesh has ${vertices}`);
+    if (data.triangles.length !== count * 3)
+        fail(`${data.triangles.length / 3} triangles for ${count} vertices`);
+    if (data.coordinates.length !== count * 2)
+        fail(`${data.coordinates.length / 2} coordinates for ${count} vertices`);
+    if (data.offsets.length !== count)
+        fail(`${data.offsets.length} offsets for ${count} vertices`);
+    const particles = data.rest.length / 3;
+    if (!Number.isInteger(particles) || particles === 0)
+        fail(`rest holds ${data.rest.length} floats`);
+    for (let i = 0; i < data.triangles.length; i++) {
+        if (data.triangles[i] >= particles) {
+            fail(`vertex ${Math.floor(i / 3)} names particle ${data.triangles[i]} of ${particles}`);
+        }
+    }
+}
+/** The binding as RGBA float texels, two a vertex, padded to whole rows. */
+export function packClothBinding(data) {
+    const vertices = data.weights.length;
+    const { width, height } = clothTextureSize(vertices * 2);
+    const out = new Float32Array(width * height * 4);
+    for (let v = 0; v < vertices; v++) {
+        const at = v * 8;
+        out[at] = data.triangles[v * 3];
+        out[at + 1] = data.triangles[v * 3 + 1];
+        out[at + 2] = data.triangles[v * 3 + 2];
+        out[at + 3] = data.weights[v];
+        out[at + 4] = data.coordinates[v * 2];
+        out[at + 5] = data.coordinates[v * 2 + 1];
+        out[at + 6] = data.offsets[v];
+    }
+    return out;
+}
+/** Particles, three floats each, into RGBA texels in `out`. Allocation-free, for every frame. */
+export function packClothParticles(positions, out) {
+    const count = positions.length / 3;
+    for (let i = 0; i < count; i++) {
+        out[i * 4] = positions[i * 3];
+        out[i * 4 + 1] = positions[i * 3 + 1];
+        out[i * 4 + 2] = positions[i * 3 + 2];
+        out[i * 4 + 3] = 0;
+    }
+}

package/dist/render/clothPlacement.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Where a cloth-bound vertex goes: the reference for what the vertex stage computes.
+ *
+ * A render vertex bound to a simulation triangle (particles a, b, c) sits at its barycentric point
+ * — `a·(1 − u − v) + b·u + c·v` — raised `offset` along the triangle's normal; its normal turns as
+ * the triangle turned since rest. The turn is the rotation from the triangle's rest frame
+ * to its frame now, each frame built from its first edge and its normal, so a vertex beside the
+ * triangle, a fold's width away, moves as the cloth moves rather than as its skeleton does.
+ *
+ * **A vertex bound to one particle** — all three indices equal — sits on it and keeps its normal:
+ * a single point has no frame to turn by. That is how a binding says "follow this particle".
+ *
+ * **A reference, as `recon/motionVectors.ts` is**: nothing at run time calls it. The vertex stage in
+ * `shaders/clothBinding.ts` and the cloth motion stage in `shaders/recon/motion.wgsl.ts` are the
+ * same arithmetic for the device, and nothing but a device holds them to this — the source tests
+ * pin where the shader moves a vertex, not the numbers it moves it by. `demo/dev/skinnedCloth.html`
+ * is where the two backends were compared, and they agree to two levels in 255.
+ */
+/** Where a placement lands, written into caller-owned arrays. */
+export interface ClothPlacement {
+    readonly position: Float64Array;
+    readonly normal: Float64Array;
+}
+/** Place one vertex: `now` and `rest` are particle positions, three floats each. */
+export declare function clothPlace(now: ArrayLike<number>, rest: ArrayLike<number>, a: number, b: number, c: number, u: number, v: number, offset: number, restNormal: readonly [number, number, number], out: ClothPlacement): void;