@driftengine/core 4.8.3 → 4.8.5

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/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;

package/dist/render/clothPlacement.js

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+const NOW = new Float64Array(9);
+const REST = new Float64Array(9);
+/** A triangle's frame — first edge, normal × edge, normal — as three columns, into `out`. */
+function frame(particles, a, b, c, out) {
+    const ex = particles[b * 3] - particles[a * 3];
+    const ey = particles[b * 3 + 1] - particles[a * 3 + 1];
+    const ez = particles[b * 3 + 2] - particles[a * 3 + 2];
+    const fx = particles[c * 3] - particles[a * 3];
+    const fy = particles[c * 3 + 1] - particles[a * 3 + 1];
+    const fz = particles[c * 3 + 2] - particles[a * 3 + 2];
+    let nx = ey * fz - ez * fy;
+    let ny = ez * fx - ex * fz;
+    let nz = ex * fy - ey * fx;
+    const nl = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+    nx /= nl;
+    ny /= nl;
+    nz /= nl;
+    const el = Math.sqrt(ex * ex + ey * ey + ez * ez) || 1;
+    const tx = ex / el;
+    const ty = ey / el;
+    const tz = ez / el;
+    out[0] = tx;
+    out[1] = ty;
+    out[2] = tz;
+    out[3] = ny * tz - nz * ty;
+    out[4] = nz * tx - nx * tz;
+    out[5] = nx * ty - ny * tx;
+    out[6] = nx;
+    out[7] = ny;
+    out[8] = nz;
+}
+/** Place one vertex: `now` and `rest` are particle positions, three floats each. */
+export function clothPlace(now, rest, a, b, c, u, v, offset, restNormal, out) {
+    if (a === b && b === c) {
+        out.position[0] = now[a * 3];
+        out.position[1] = now[a * 3 + 1];
+        out.position[2] = now[a * 3 + 2];
+        out.normal[0] = restNormal[0];
+        out.normal[1] = restNormal[1];
+        out.normal[2] = restNormal[2];
+        return;
+    }
+    frame(now, a, b, c, NOW);
+    frame(rest, a, b, c, REST);
+    const w = 1 - u - v;
+    for (let k = 0; k < 3; k++) {
+        out.position[k] =
+            now[a * 3 + k] * w +
+                now[b * 3 + k] * u +
+                now[c * 3 + k] * v +
+                NOW[6 + k] * offset;
+    }
+    /* Turned by now × restᵀ: the rest normal in the rest frame's terms, rebuilt in the frame now. */
+    const t = REST[0] * restNormal[0] +
+        REST[1] * restNormal[1] +
+        REST[2] * restNormal[2];
+    const s = REST[3] * restNormal[0] +
+        REST[4] * restNormal[1] +
+        REST[5] * restNormal[2];
+    const n = REST[6] * restNormal[0] +
+        REST[7] * restNormal[1] +
+        REST[8] * restNormal[2];
+    for (let k = 0; k < 3; k++) {
+        out.normal[k] =
+            NOW[k] * t + NOW[3 + k] * s + NOW[6 + k] * n;
+    }
+}

package/dist/render/compressedSource.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A block-compressed image a caller hands to `createSurfaceTexture`, and the one decision about it
+ * both backends share: whether this device takes it as blocks.
+ *
+ * **Uploaded as it is, or not at all.** A BC texture costs a byte a texel on the GPU (BC7) or half
+ * of one (BC1) against four for RGBA, and keeps the mip chain its author built rather than one a box
+ * filter makes. A device that cannot sample the format — most phones, which have ASTC and ETC2 —
+ * gets nothing from the blocks, and the engine does not decode them here: core ships no decoder.
+ * The loader in `@driftengine/assets` asks `uploadsCompressed` first and decodes at load where the
+ * answer is no; a caller handing a source this device cannot take is refused by name.
+ *
+ * Backend-neutral, because both backends must agree on what they accept before either touches a
+ * device. `BlockFormat` is the same union `@driftengine/drft` names `BcFormat`; core imports nothing
+ * from that package, and a format added there without a twin here fails where the loader passes one
+ * to the other, at compile time.
+ */
+/** BC1 to BC5 and BC7. BC6H and the signed forms are not among them. */
+export type BlockFormat = 'bc1' | 'bc2' | 'bc3' | 'bc4' | 'bc5' | 'bc7';
+/** A format as a device offers it: the colour space is part of the name, as WebGPU's are. */
+export type CompressedTextureFormat = 'bc1' | 'bc1-srgb' | 'bc2' | 'bc2-srgb' | 'bc3' | 'bc3-srgb' | 'bc4' | 'bc5' | 'bc7' | 'bc7-srgb';
+/** Block-compressed texels with their stored mip chain, level 0 first. */
+export interface CompressedTextureSource {
+    readonly format: BlockFormat;
+    readonly width: number;
+    readonly height: number;
+    readonly levels: readonly Uint8Array[];
+}
+/** What `createSurfaceTexture` takes: an image, or blocks. */
+export type SurfaceSource = TexImageSource | CompressedTextureSource;
+/**
+ * The layers as blocks, or null where every one is an image. An array mixing the two is refused:
+ * one GPU texture has one format.
+ */
+export declare function compressedLayers(sources: readonly SurfaceSource[]): readonly CompressedTextureSource[] | null;
+/** Bytes per 4x4 block. */
+export declare const BLOCK_BYTES: Readonly<Record<BlockFormat, number>>;
+/** Whether `source` is a compressed source rather than an image. */
+export declare function isCompressedSource(source: unknown): source is CompressedTextureSource;
+/** The format a device would have to offer, or null for one with no sRGB form. */
+export declare function compressedFormatName(format: BlockFormat, srgb: boolean): CompressedTextureFormat | null;
+/**
+ * Whether a `width` by `height` source in `format` uploads as blocks on a device offering
+ * `available`. Level 0 must be whole blocks each way: WebGPU refuses any other size for a BC
+ * texture, and WebGL2's S3TC extension says the same, so a 6x6 image is decoded rather than
+ * refused. What would make that wrong is a device that pads; none is relied on here.
+ */
+export declare function uploadsCompressed(format: BlockFormat, srgb: boolean, width: number, height: number, available: readonly CompressedTextureFormat[]): boolean;
+/**
+ * How many levels the layers carry, after checking each is the size its place requires and every
+ * layer matches the first. Refuses by name: a short level uploaded anyway is a device error at
+ * submit, which on WebGPU is a frame that draws nothing and says so somewhere else.
+ */
+export declare function compressedLevels(layers: readonly CompressedTextureSource[]): number;
+/** What a refusal names: the format, its colour space, and what the device offers instead. */
+export declare function compressedRefusal(format: BlockFormat, srgb: boolean, width: number, height: number, available: readonly CompressedTextureFormat[]): string;
+/** The format name and level count blocks upload as here, or a refusal naming why they cannot. */
+export declare function planBlocks(blocks: readonly CompressedTextureSource[], srgb: boolean, compressed: readonly CompressedTextureFormat[]): {
+    readonly name: CompressedTextureFormat;
+    readonly levels: number;
+};
+/**
+ * `update` replaces pixels with an image, and a texture holding blocks has no pixels to replace:
+ * its format is the blocks', and an image would be a different texture. Refused rather than
+ * quietly reallocated, so the handle a draw holds keeps meaning what it meant.
+ */
+export declare function refuseBlockUpdate(format: BlockFormat | null): void;