@driftengine/core 4.13.6 → 4.14.1

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

@@ -8,7 +8,7 @@
  * for every resource a later write in the frame overwrites. A skin posed twice in a frame draws its
  * last pose everywhere, as a mesh rewritten twice with `updateMesh` does.
  */
-import { reachOf } from '../../pointSkin.js';
+import { reachOf, widenReach } from '../../pointSkin.js';
 import { POINT_SKIN_WGSL, POINT_SKIN_WORKGROUP } from './shaders/pointSkin.wgsl.js';
 const STORAGE = 0x0080;
 const UNIFORM = 0x0040;
@@ -26,28 +26,31 @@ export function createPointSkinPipeline(device) {
 }
 export class GpuPointSkin {
     mesh;
+    /** Widened by each rewrite, never narrowed: see `widenReach`. */
     reach;
     count;
     pipeline;
     joints;
+    /** Params, points with their weights, joints named, normals: in that order. */
     buffers;
     group;
+    /** A rewrite's vertices laid out as the buffers hold them, grown to the largest rewrite. */
+    scratch = {
+        points: new Float32Array(0),
+        named: new Uint32Array(0),
+        normals: new Float32Array(0),
+    };
     constructor(device, pipeline, mesh, data) {
         this.mesh = mesh;
         this.pipeline = pipeline;
         this.reach = reachOf(data);
         const count = data.weights.length / 4;
         this.count = count;
-        /* Each influence a vec4: its point, and its weight in w. */
-        const points = new Float32Array(count * 16);
-        for (let i = 0; i < count * 4; i++) {
-            points.set(data.points.subarray(i * 3, i * 3 + 3), i * 4);
-            points[i * 4 + 3] = data.weights[i];
-        }
-        const named = Uint32Array.from(data.joints);
-        const normals = new Float32Array(count * 4);
-        for (let v = 0; v < count; v++)
-            normals.set(data.normals.subarray(v * 3, v * 3 + 3), v * 4);
+        const { points, named, normals } = laidOut(data, count, {
+            points: new Float32Array(count * 16),
+            named: new Uint32Array(count * 4),
+            normals: new Float32Array(count * 4),
+        });
         const params = new Uint32Array([count, 0, 0, 0]);
         const made = (label, contents, usage) => {
             const buffer = device.createBuffer({
@@ -58,22 +61,21 @@ export class GpuPointSkin {
             device.queue.writeBuffer(buffer, 0, contents);
             return buffer;
         };
-        this.joints = device.createBuffer({
-            label: 'pointSkin.joints',
-            size: Math.max(1, this.reach.joints) * 64,
-            usage: STORAGE | COPY_DST,
-        });
-        const buffers = [
+        this.joints = jointBuffer(device, this.reach.joints);
+        this.buffers = [
             made('pointSkin.params', params, UNIFORM),
             made('pointSkin.points', points, STORAGE),
             made('pointSkin.named', named, STORAGE),
             made('pointSkin.normals', normals, STORAGE),
         ];
-        this.buffers = buffers;
-        const [positionsOut, normalsOut] = mesh.vertexBuffers;
-        this.group = device.createBindGroup({
+        this.group = this.bind(device);
+    }
+    bind(device) {
+        const buffers = this.buffers;
+        const [positionsOut, normalsOut] = this.mesh.vertexBuffers;
+        return device.createBindGroup({
             label: 'pointSkin.pose',
-            layout: pipeline.getBindGroupLayout(0),
+            layout: this.pipeline.getBindGroupLayout(0),
             entries: [
                 { binding: 0, resource: { buffer: buffers[0] } },
                 { binding: 1, resource: { buffer: this.joints } },
@@ -85,6 +87,36 @@ export class GpuPointSkin {
             ],
         });
     }
+    /**
+     * Rewrite vertices `first` onward, as many as `data` holds, in place: three queue writes at their
+     * offsets. **A queue write reaches every dispatch submitted after it**, so the renderer submits a
+     * pose already recorded before calling this, and the rewrite reaches the next pose alone, as it
+     * does on WebGL2. A joint none of the skin named before grows the joints buffer, which is made
+     * again with its bind group; the old one goes once the work already submitted is done with it.
+     */
+    rewrite(device, first, data) {
+        const count = data.weights.length / 4;
+        const scratch = this.scratch;
+        if (scratch.named.length < count * 4) {
+            this.scratch = {
+                points: new Float32Array(count * 16),
+                named: new Uint32Array(count * 4),
+                normals: new Float32Array(count * 4),
+            };
+        }
+        const { points, named, normals } = laidOut(data, count, this.scratch);
+        const buffers = this.buffers;
+        device.queue.writeBuffer(buffers[1], first * 64, points, 0, count * 16);
+        device.queue.writeBuffer(buffers[2], first * 16, named, 0, count * 4);
+        device.queue.writeBuffer(buffers[3], first * 16, normals, 0, count * 4);
+        const joints = this.reach.joints;
+        this.reach = widenReach(this.reach, data);
+        if (Math.max(1, this.reach.joints) > Math.max(1, joints)) {
+            this.joints.destroy();
+            this.joints = jointBuffer(device, this.reach.joints);
+            this.group = this.bind(device);
+        }
+    }
     /** Write the pose's joints and record the dispatch that poses every vertex into `encoder`. */
     pose(device, encoder, matrices) {
         if (this.reach.joints > 0) {
@@ -102,3 +134,29 @@ export class GpuPointSkin {
             buffer.destroy();
     }
 }
+function jointBuffer(device, joints) {
+    return device.createBuffer({
+        label: 'pointSkin.joints',
+        size: Math.max(1, joints) * 64,
+        usage: STORAGE | COPY_DST,
+    });
+}
+/**
+ * `count` vertices of `data` as the buffers hold them, into `out`'s leading entries: each influence
+ * a vec4 of its point and its weight in w, the joints as integers, each normal a vec4.
+ */
+function laidOut(data, count, out) {
+    for (let i = 0; i < count * 4; i++) {
+        out.points[i * 4] = data.points[i * 3];
+        out.points[i * 4 + 1] = data.points[i * 3 + 1];
+        out.points[i * 4 + 2] = data.points[i * 3 + 2];
+        out.points[i * 4 + 3] = data.weights[i];
+        out.named[i] = data.joints[i];
+    }
+    for (let v = 0; v < count; v++) {
+        out.normals[v * 4] = data.normals[v * 3];
+        out.normals[v * 4 + 1] = data.normals[v * 3 + 1];
+        out.normals[v * 4 + 2] = data.normals[v * 3 + 2];
+    }
+    return out;
+}

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

@@ -215,7 +215,7 @@ sampleCount?: number): GPURenderPipeline;
  * draws a plausible picture.
  */
 export declare const TAA_FRAG_FIELDS: UniformFields;
-export declare const TAA_FRAG_SIZE: 112;
+export declare const TAA_FRAG_SIZE: 128;
 export declare const TAA_UNIFORMS: 1;
 export declare const TAA_TEXTURES: {
     readonly uScene: {
@@ -243,6 +243,11 @@ export declare const TAA_TEXTURES: {
         readonly sampler: 41;
         readonly type: "sampler2D";
     };
+    readonly uMotion: {
+        readonly texture: 42;
+        readonly sampler: 43;
+        readonly type: "sampler2D";
+    };
 };
 /**
  * The order-independent resolve's inputs. It has no uniform block of its own — the whole pass is

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

@@ -26,6 +26,7 @@ import { GpuPointSkin } from './pointSkinPass.ts';
 import { type PointSkinData } from '../../pointSkin.ts';
 import type { ComputeHost } from './computeHost.ts';
 import { type SurfaceOverlay } from '../../surfaceOverlay.ts';
+import { type BaseDecal } from '../../baseDecals.ts';
 import type { ClothBindingData } from '../../clothBindingData.ts';
 import type { CompressedTextureFormat, CompressedTextureSource, SurfaceSource } from '../../compressedSource.ts';
 import { GpuSdfText } from './sdfTextPass.ts';
@@ -1215,6 +1216,12 @@ export declare class WebGPURenderer implements RendererApi {
     private warnedLayersModelMap;
     /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
     private readonly detailFloats;
+    /** `uEmissiveFlow`, a material's glow moved and masked, packed by `packEmissiveFlow`. */
+    private readonly flowFloats;
+    /** `uIridescence`, a material's iridescent overlay packed by `packIridescentOverlay`. */
+    private readonly iridescentFloats;
+    /** The refusals of an overlay already said, each once. */
+    private readonly warnedIridescent;
     /** The detail refusals already said, each once. See `detailOfMaterial`. */
     private readonly warnedDetail;
     private warnedLayersTriplanar;
@@ -2142,6 +2149,8 @@ export declare class WebGPURenderer implements RendererApi {
     /** The moving layer's own matrix on, the first time a frame draws that layer with one. */
     private enableMovingSun;
     /** One of the lit stage's switches on, in every cache a lit pipeline can come from. */
+    /** A material's iridescent overlay, or null where it is malformed, said once. */
+    private iridescentOf;
     private enableLit;
     /** One resolution every glass caster is read through, so recording one allocates nothing. */
     private readonly glassCasterScratch;
@@ -2419,6 +2428,13 @@ export declare class WebGPURenderer implements RendererApi {
      * a destroyed buffer in a submit loses the whole command buffer. Nothing else reads them, so once
      * the rewrites are submitted, which only moves them earlier, the buffers can go at once.
      */
+    /**
+     * Rewrite part of a skin in place. **A pose already recorded is submitted first**, since a queue
+     * write reaches every dispatch submitted after it and would otherwise reach a pose the caller made
+     * before the rewrite; then the pose after it alone reads the rewrite, as on WebGL2. A rewrite with
+     * nothing pending submits nothing.
+     */
+    updatePointSkin(skin: GpuPointSkin, first: number, data: PointSkinData): void;
     disposePointSkin(skin: GpuPointSkin): void;
     /**
      * Rewrite a mesh's colours. Refused in words on a mesh that did not ask for `dynamicColors`,
@@ -4217,6 +4233,14 @@ export declare class WebGPURenderer implements RendererApi {
     /** The profiles as packed and the cookie images, kept so either can rebuild the atlas. */
     private iesAtlas;
     private cookieImages;
+    /** The images the frame's base decals lay, in the atlas's band of them. See `setBaseDecalImages`. */
+    private decalImages;
+    /** The decals as last laid, packed again whenever the cookies move their band. */
+    private baseDecalList;
+    /** `uBaseDecals`, held until the next `setBaseDecals`, across passes. */
+    private readonly baseDecalFloats;
+    /** The refusals of a decal or its image already said, each once. */
+    private readonly warnedBaseDecals;
     /** The scene's DriftLight field, and its two volumes once it is whole. See `createLightField`. */
     private lightField;
     private driftIndex;
@@ -4388,6 +4412,23 @@ export declare class WebGPURenderer implements RendererApi {
      * call a tile fills the row without a canvas in between.
      */
     setSpotCookies(images: readonly TexImageSource[]): void;
+    /**
+     * The images the frame's base decals lay, each a `BASE_DECAL_TILE` square. The same count again
+     * copies the squares into the atlas and nothing else; a different count builds it again. See
+     * `renderer.ts` and `baseDecals.ts`. **Once a frame, before the draws they mark**: a copy reaches
+     * every draw of the frame it is made in, as any queue write does.
+     */
+    setBaseDecalImages(images: readonly TexImageSource[]): void;
+    /** The decal images into their squares of the atlas. */
+    private copyDecalImages;
+    /** Whether an image is a decal's square, said once where it is not. */
+    private decalImageFits;
+    /**
+     * The decals laid into the base colours of the draws after it, until the next call, across
+     * passes. In the material block, as the overlay is, and written again where each pass starts it.
+     * See `renderer.ts` and `baseDecals.ts`.
+     */
+    setBaseDecals(decals: readonly BaseDecal[]): void;
     /** Let the atlas go, to be built again from what is in hand the next time it is bound. */
     private forgetFixtureAtlas;
     /**

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

@@ -42,7 +42,7 @@ import { ProbeSweeps } from '../../probeSweeps.js';
 import { ggxMaxLevelFor, irradianceLevelFor, octahedralEdgeFor } from '../../prefilterEnvMap.js';
 import { environmentTexels } from './environmentTexels.js';
 import { packIesAtlas } from '../../iesProfile.js';
-import { fixtureAtlasLayout, fixtureAtlasTexels } from '../../fixtureAtlas.js';
+import { decalBandTop, fixtureAtlasLayout, fixtureAtlasTexels } from '../../fixtureAtlas.js';
 import { resolveSurfaceScene } from '../../surfaceScene.js';
 import { COOKIE_TILE } from '../../lightBudget.js';
 import { FULL_LIGHT_BUDGET } from '../../uniformVectorBudget.js';
@@ -64,7 +64,7 @@ import { gpuCompressedFormats } from './compressedUpload.js';
 import { GpuClothBinding, GpuClothParticles, clothStandIn } from './clothTextures.js';
 import { GroupShelf } from './groupShelf.js';
 import { GpuPointSkin, createPointSkinPipeline } from './pointSkinPass.js';
-import { poseBounds, validatePointSkin, validatePose, } from '../../pointSkin.js';
+import { poseBounds, validatePointSkin, validatePointSkinRange, validatePose, } from '../../pointSkin.js';
 import { MODEL_PARAM_FLOATS, eyeAxisInWorld, packModel, skinProfileDistance, } from '../../surfaceModel.js';
 import { OVERLAY_FLOATS, overlayLays, packSurfaceOverlay, } from '../../surfaceOverlay.js';
 import { PROJECTION_FLOATS, packSurfaceProjection } from '../../surfaceProjection.js';
@@ -74,6 +74,10 @@ import { orthographicDepthSpan } from '../../lightMatrix.js';
 import { LAYER_FLOATS, layerMaskMap, layeredProjection, layersFitBeside, packSurfaceLayers, } from '../../surfaceLayers.js';
 import { DETAIL_FLOATS, detailOf, detailRefusal, detailRefusalWarning, packSurfaceDetail, } from '../../surfaceDetail.js';
 import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.js';
+import { EMISSIVE_FLOW_FLOATS, packEmissiveFlow } from '../../emissiveFlow.js';
+import { BASE_DECAL_FLOATS, BASE_DECAL_TILE, packBaseDecals, } from '../../baseDecals.js';
+import { sourceSize } from '../../textureSource.js';
+import { IRIDESCENT_FLOATS, iridescentRefusal, packIridescentOverlay, } from '../../iridescentOverlay.js';
 import { frameReflectionsRefused, resolveFrameReflections, } from '../../frameReflections.js';
 import { REFLECTION_SURFACE_FORMAT, ReflectionSurfacePass } from './reflectionSurfacePass.js';
 import { validateClothBinding } from '../../clothBindingData.js';
@@ -106,7 +110,7 @@ import { PARTICLE_INDICES } from '../../shaders/particle.js';
 import { createScatterDeform, resolveScatterDeform, } from '../../scatterDeform.js';
 import { createResolvedPointLights, resolvePointLights, } from '../../lightBudget.js';
 import { resolveRenderQuality } from '../../renderQuality.js';
-import { DEFAULT_GLOBAL_MEDIUM, WEAK_GPU_MEDIUM_STEPS, createResolvedMediumLamps, mediumActive, mediumTargetSize, resolveGlobalMedium, resolveGlobalMediumSettings, resolveMediumLamps, } from '../../globalMedium.js';
+import { mediumSkyFill, DEFAULT_GLOBAL_MEDIUM, WEAK_GPU_MEDIUM_STEPS, createResolvedMediumLamps, mediumActive, mediumTargetSize, resolveGlobalMedium, resolveGlobalMediumSettings, resolveMediumLamps, } from '../../globalMedium.js';
 import { castsDepth, glassOf } from '../../shadowCasters.js';
 import { materialHasMaps, noteMapsWithoutUvs } from '../../mapsWithoutUvs.js';
 import { VIEW_MODEL_DEPTH_SHARE, viewModelDepthRange } from '../../viewModel.js';
@@ -157,6 +161,8 @@ import { fitProbeGrid } from '../../gi/probeGridFit.js';
  * `fitProbeGrid` widens it uniformly when the budget bites, so a large scene gets a coarser grid
  * rather than a truncated one.
  */
+/** The ambient a medium is lit by in a frame bound with no environment: none. */
+const MEDIUM_NO_AMBIENT = [0, 0, 0];
 const INDIRECT_PROBE_SPACING = 2;
 /** What the trace is given when a frame never said what was lighting it. */
 const NO_SUN = [0, 0, 0];
@@ -2283,6 +2289,12 @@ export class WebGPURenderer {
     warnedLayersModelMap = false;
     /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
     detailFloats = new Float32Array(DETAIL_FLOATS);
+    /** `uEmissiveFlow`, a material's glow moved and masked, packed by `packEmissiveFlow`. */
+    flowFloats = new Float32Array(EMISSIVE_FLOW_FLOATS);
+    /** `uIridescence`, a material's iridescent overlay packed by `packIridescentOverlay`. */
+    iridescentFloats = new Float32Array(IRIDESCENT_FLOATS);
+    /** The refusals of an overlay already said, each once. */
+    warnedIridescent = new Set();
     /** The detail refusals already said, each once. See `detailOfMaterial`. */
     warnedDetail = new Set();
     warnedLayersTriplanar = false;
@@ -2750,6 +2762,18 @@ export class WebGPURenderer {
             f[emissive] = asked?.[0] ?? 1;
             f[emissive + 1] = asked?.[1] ?? 1;
             f[emissive + 2] = asked?.[2] ?? 1;
+            /* And its glow's scroll and mask, the first time a material asks: emissiveFlow.ts. */
+            if (packEmissiveFlow(material, this.flowFloats))
+                this.enableLit('EMISSIVE_FLOW');
+            f.set(this.flowFloats, this.materialField('uEmissiveFlow'));
+            /* And its iridescent overlay, the first time a material lays one: iridescentOverlay.ts. */
+            const iridescent = this.iridescentOf(material);
+            packIridescentOverlay(iridescent, material ?? {}, this.iridescentFloats);
+            f.set(this.iridescentFloats, this.materialField('uIridescence'));
+            /* And whether the frame's decals mark it. See `SurfaceMaterial.receivesDecals`. */
+            f[this.materialField('uDecalReceiver')] = material?.receivesDecals === false ? 1 : 0;
+            if (iridescent !== null)
+                this.enableLit('IRIDESCENT_OVERLAY');
             /* The model's numbers and whether its map is bound. See `packModel`. */
             packModel(material?.model ?? null, ownModelMap !== null, this.modelParams, material?.physicalSpecular === true);
             /* The first physical highlight asked for is when the lit pipelines start carrying one. */
@@ -5148,6 +5172,20 @@ export class WebGPURenderer {
         }
     }
     /** One of the lit stage's switches on, in every cache a lit pipeline can come from. */
+    /** A material's iridescent overlay, or null where it is malformed, said once. */
+    iridescentOf(material) {
+        const overlay = material?.iridescentOverlay ?? null;
+        if (overlay === null)
+            return null;
+        const refusal = iridescentRefusal(overlay);
+        if (refusal === null)
+            return overlay;
+        if (!this.warnedIridescent.has(refusal)) {
+            this.warnedIridescent.add(refusal);
+            console.warn(`Renderer: an iridescent overlay is refused: ${refusal}. Drawn without it.`);
+        }
+        return null;
+    }
     enableLit(feature) {
         if (this.pipelines.litSwitches[feature])
             return;
@@ -6278,6 +6316,9 @@ export class WebGPURenderer {
             { binding: TAA_TEXTURES.uFlicker },
             { binding: TAA_TEXTURES.uFlickerMotion },
             { binding: TAA_TEXTURES.uDepth, filterable: false },
+            /* WebGL2's movers' motion (`motionTarget.ts`); here the depth stands in and is never read,
+               `uMotionOn` being 0, since this backend follows movers through its reconstruction. */
+            { binding: TAA_TEXTURES.uMotion, filterable: false },
         ]);
         this.taaUniforms = device.createBuffer({
             label: 'post.taaUniforms',
@@ -7120,6 +7161,20 @@ export class WebGPURenderer {
      * a destroyed buffer in a submit loses the whole command buffer. Nothing else reads them, so once
      * the rewrites are submitted, which only moves them earlier, the buffers can go at once.
      */
+    /**
+     * Rewrite part of a skin in place. **A pose already recorded is submitted first**, since a queue
+     * write reaches every dispatch submitted after it and would otherwise reach a pose the caller made
+     * before the rewrite; then the pose after it alone reads the rewrite, as on WebGL2. A rewrite with
+     * nothing pending submits nothing.
+     */
+    updatePointSkin(skin, first, data) {
+        validatePointSkinRange(data, first, skin.mesh.vertexCount);
+        if (this.surface.lost)
+            return;
+        if (this.pendingRewrites !== null)
+            this.submit([]);
+        skin.rewrite(this.surface.device, first, data);
+    }
     disposePointSkin(skin) {
         if (this.pendingRewrites !== null && !this.surface.lost)
             this.submit([]);
@@ -7277,6 +7332,13 @@ export class WebGPURenderer {
         f.fill(0, at('uLayerLooks'), at('uLayerLooks') + LOOK_FLOATS);
         /* Nor detail. */
         f.fill(0, at('uDetail'), at('uDetail') + DETAIL_FLOATS);
+        /* Nor a glow that moves or is masked. */
+        f.fill(0, at('uEmissiveFlow'), at('uEmissiveFlow') + EMISSIVE_FLOW_FLOATS);
+        /* Nor an iridescent overlay. */
+        f.fill(0, at('uIridescence'), at('uIridescence') + IRIDESCENT_FLOATS);
+        /* The frame's decals as last laid, held across passes, and every surface receiving them. */
+        f.set(this.baseDecalFloats, at('uBaseDecals'));
+        f[at('uDecalReceiver')] = 0;
         f[at('uCutout')] = 0;
         f[at('uCutout') + 1] = 0;
         this.cutoutResolveStaged = 'hard';
@@ -11318,6 +11380,8 @@ export class WebGPURenderer {
             f[depthRow + 3] = 1;
         }
         f[at('uAntiFlicker')] = 1;
+        /* The camera's motion alone: this backend follows a mover through its reconstruction. */
+        f[at('uMotionOn')] = 0;
         device.queue.writeBuffer(this.taaUniforms, 0, this.taaStaging);
         const pass = encoder.beginRenderPass({
             label: 'post.taa',
@@ -11726,7 +11790,7 @@ export class WebGPURenderer {
         f.set(this.frameEye, at('uCameraPos'));
         f.set(env?.directionalDir ?? [0, 1, 0], at('uSunDir'));
         f.set(env?.directionalColor ?? [0, 0, 0], at('uSunColor'));
-        f.set(env?.ambient ?? [0, 0, 0], at('uAmbient'));
+        f.set(mediumSkyFill(options, env?.ambient ?? MEDIUM_NO_AMBIENT), at('uAmbient'));
         f[at('uDensity')] = options.density;
         const height = at('uHeight');
         f[height] = options.heightFalloff;
@@ -14658,6 +14722,14 @@ export class WebGPURenderer {
     /** The profiles as packed and the cookie images, kept so either can rebuild the atlas. */
     iesAtlas = packIesAtlas([]);
     cookieImages = [];
+    /** The images the frame's base decals lay, in the atlas's band of them. See `setBaseDecalImages`. */
+    decalImages = [];
+    /** The decals as last laid, packed again whenever the cookies move their band. */
+    baseDecalList = [];
+    /** `uBaseDecals`, held until the next `setBaseDecals`, across passes. */
+    baseDecalFloats = new Float32Array(BASE_DECAL_FLOATS);
+    /** The refusals of a decal or its image already said, each once. */
+    warnedBaseDecals = new Set();
     /** The scene's DriftLight field, and its two volumes once it is whole. See `createLightField`. */
     lightField = null;
     driftIndex = null;
@@ -15153,6 +15225,70 @@ export class WebGPURenderer {
         this.cookieImages = images.slice();
         this.forgetFixtureAtlas();
         this.rebuildFlatBindGroup();
+        /* The decals' band starts below the cookies, so their rows move with them. */
+        if (this.baseDecalList.length > 0)
+            this.setBaseDecals(this.baseDecalList);
+    }
+    /**
+     * The images the frame's base decals lay, each a `BASE_DECAL_TILE` square. The same count again
+     * copies the squares into the atlas and nothing else; a different count builds it again. See
+     * `renderer.ts` and `baseDecals.ts`. **Once a frame, before the draws they mark**: a copy reaches
+     * every draw of the frame it is made in, as any queue write does.
+     */
+    setBaseDecalImages(images) {
+        if (this.surface.lost)
+            return;
+        if (images.length === this.decalImages.length && this.fixtureTexture !== null) {
+            this.decalImages = images;
+            this.copyDecalImages(this.fixtureTexture);
+            return;
+        }
+        this.decalImages = images.slice();
+        this.forgetFixtureAtlas();
+        this.rebuildFlatBindGroup();
+        this.setBaseDecals(this.baseDecalList);
+    }
+    /** The decal images into their squares of the atlas. */
+    copyDecalImages(texture) {
+        const top = decalBandTop(this.cookieImages.length);
+        for (let tile = 0; tile < this.decalImages.length; tile++) {
+            const source = this.decalImages[tile];
+            if (source === undefined || !this.decalImageFits(source))
+                continue;
+            this.surface.device.queue.copyExternalImageToTexture({ source: source }, { texture, origin: { x: tile * BASE_DECAL_TILE, y: top } }, { width: BASE_DECAL_TILE, height: BASE_DECAL_TILE });
+        }
+    }
+    /** Whether an image is a decal's square, said once where it is not. */
+    decalImageFits(image) {
+        const { width, height } = sourceSize(image);
+        if (width === BASE_DECAL_TILE && height === BASE_DECAL_TILE)
+            return true;
+        const refusal = `a base decal image of ${width} by ${height}; it is a square of ${BASE_DECAL_TILE} ` +
+            'texels, and is left clear';
+        if (!this.warnedBaseDecals.has(refusal)) {
+            this.warnedBaseDecals.add(refusal);
+            console.warn(`WebGPU: ${refusal}.`);
+        }
+        return false;
+    }
+    /**
+     * The decals laid into the base colours of the draws after it, until the next call, across
+     * passes. In the material block, as the overlay is, and written again where each pass starts it.
+     * See `renderer.ts` and `baseDecals.ts`.
+     */
+    setBaseDecals(decals) {
+        if (this.surface.lost)
+            return;
+        this.baseDecalList = decals;
+        const refusal = packBaseDecals(decals, this.decalImages.length, decalBandTop(this.cookieImages.length), this.baseDecalFloats);
+        if (refusal !== null && !this.warnedBaseDecals.has(refusal)) {
+            this.warnedBaseDecals.add(refusal);
+            console.warn(`WebGPU: ${refusal}.`);
+        }
+        if (this.baseDecalFloats[0] > 0)
+            this.enableLit('BASE_DECALS');
+        this.perFrameFloats.set(this.baseDecalFloats, this.materialField('uBaseDecals'));
+        this.materials.dirty();
     }
     /** Let the atlas go, to be built again from what is in hand the next time it is bound. */
     forgetFixtureAtlas() {
@@ -15172,7 +15308,7 @@ export class WebGPURenderer {
         if (this.fixtureView !== null)
             return this.fixtureView;
         const { device } = this.surface;
-        const layout = fixtureAtlasLayout(this.iesAtlas.height, this.cookieImages.length);
+        const layout = fixtureAtlasLayout(this.iesAtlas.height, this.cookieImages.length, this.decalImages.length);
         const texture = device.createTexture({
             label: 'fixture.atlas',
             size: [layout.width, layout.height],
@@ -15188,6 +15324,7 @@ export class WebGPURenderer {
                 continue;
             device.queue.copyExternalImageToTexture({ source: source }, { texture, origin: { x: tile * COOKIE_TILE, y: 0 } }, { width: COOKIE_TILE, height: COOKIE_TILE });
         }
+        this.copyDecalImages(texture);
         this.fixtureTexture = texture;
         this.fixtureView = texture.createView();
         this.iesRows = this.iesAtlas.height;
@@ -15903,6 +16040,7 @@ export class WebGPURenderer {
                     ...entry(TAA_TEXTURES.uFlicker, record),
                     ...entry(TAA_TEXTURES.uFlickerMotion, motion),
                     ...entry(TAA_TEXTURES.uDepth, this.resolvedDepthView, true),
+                    ...entry(TAA_TEXTURES.uMotion, this.resolvedDepthView, true),
                 ],
             });
         }

package/dist/render/baseDecals.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Decals laid into the base colour of what they land on, before it is lit: `setBaseDecals` and
+ * `setBaseDecalImages`, packed into `uBaseDecals` for the lit stage's `BASE_DECALS` switch.
+ *
+ * **What they are for, and why `DecalProjector` is not it.** A projected decal multiplies the
+ * finished pixel, so where the surface under it glows, a lettered floor or a lit panel, the mark
+ * dims the glow too. A shadow a body throws on a lit floor, a footprint, a stain is a change in what
+ * the surface *is*: it darkens the colour light falls on and leaves what the surface emits, how
+ * rough it is and its normal as they are. So each of these is a box, as a `DecalBox` is, an image
+ * read across its face, and the base colour moved toward the image's colour by its alpha.
+ *
+ * **The images ride in the fixture atlas**, a band of `BASE_DECAL_TILE` squares between the cookies
+ * and the photometric profiles (`fixtureAtlas.ts`), because the lit stage has no texture binding
+ * left (`textureUnitBudget.test.ts`). An image is that square, read as a picture: its colour is
+ * decoded from sRGB and its alpha is as it is. Rewriting them once a frame is the use they are for,
+ * and costs an upload of the squares; changing how many there are builds the atlas again.
+ *
+ * **What it gives up**: eight a frame, the uniforms they take being the limit (thirty-four vectors,
+ * so WebGL2 refuses them, in words, on a part whose lit stage has no room); the GPU-driven pipeline
+ * does not draw them; and a surface opts out by its material (`receivesDecals: false`), not by a
+ * mask of what each decal may mark.
+ */
+import { type DecalBox } from './decalProjector.ts';
+/** Decals a frame. */
+export declare const MAX_BASE_DECALS = 8;
+/** Texels across an image's square in the atlas. */
+export declare const BASE_DECAL_TILE = 128;
+/** Floats in `uBaseDecals`: a header, then four vectors a decal. */
+export declare const BASE_DECAL_FLOATS: number;
+/** One decal: a box, which image it lays, and how much. */
+export interface BaseDecal extends DecalBox {
+    /** Which of `setBaseDecalImages`' images it lays, from 0. */
+    readonly image: number;
+    /** How much of the image's alpha lands, 0 to 1. Default 1. */
+    readonly opacity?: number;
+    /**
+     * How far from facing back along `forward` a surface may be turned and still be marked, as a
+     * cosine of the geometric normal against it. Default 0.2, so a floor is marked and the side of a
+     * step it stands on is not smeared. -1 marks every surface in the box.
+     */
+    readonly facingCos?: number;
+}
+/**
+ * Pack `decals` against `images` laid in the atlas band starting at row `bandTop` into `out`, and
+ * return why one was left out, or null where none was: past the eighth, an image there is none of,
+ * or a box with no size or no orientation. The rest are packed in order.
+ */
+export declare function packBaseDecals(decals: readonly BaseDecal[], images: number, bandTop: number, out: Float32Array): string | null;

package/dist/render/baseDecals.js

@@ -0,0 +1,71 @@
+/**
+ * Decals laid into the base colour of what they land on, before it is lit: `setBaseDecals` and
+ * `setBaseDecalImages`, packed into `uBaseDecals` for the lit stage's `BASE_DECALS` switch.
+ *
+ * **What they are for, and why `DecalProjector` is not it.** A projected decal multiplies the
+ * finished pixel, so where the surface under it glows, a lettered floor or a lit panel, the mark
+ * dims the glow too. A shadow a body throws on a lit floor, a footprint, a stain is a change in what
+ * the surface *is*: it darkens the colour light falls on and leaves what the surface emits, how
+ * rough it is and its normal as they are. So each of these is a box, as a `DecalBox` is, an image
+ * read across its face, and the base colour moved toward the image's colour by its alpha.
+ *
+ * **The images ride in the fixture atlas**, a band of `BASE_DECAL_TILE` squares between the cookies
+ * and the photometric profiles (`fixtureAtlas.ts`), because the lit stage has no texture binding
+ * left (`textureUnitBudget.test.ts`). An image is that square, read as a picture: its colour is
+ * decoded from sRGB and its alpha is as it is. Rewriting them once a frame is the use they are for,
+ * and costs an upload of the squares; changing how many there are builds the atlas again.
+ *
+ * **What it gives up**: eight a frame, the uniforms they take being the limit (thirty-four vectors,
+ * so WebGL2 refuses them, in words, on a part whose lit stage has no room); the GPU-driven pipeline
+ * does not draw them; and a surface opts out by its material (`receivesDecals: false`), not by a
+ * mask of what each decal may mark.
+ */
+import { worldToDecalMatrix } from './decalProjector.js';
+/** Decals a frame. */
+export const MAX_BASE_DECALS = 8;
+/** Texels across an image's square in the atlas. */
+export const BASE_DECAL_TILE = 128;
+/** Floats in `uBaseDecals`: a header, then four vectors a decal. */
+export const BASE_DECAL_FLOATS = (1 + MAX_BASE_DECALS * 4) * 4;
+const MATRIX = new Float32Array(16);
+/**
+ * Pack `decals` against `images` laid in the atlas band starting at row `bandTop` into `out`, and
+ * return why one was left out, or null where none was: past the eighth, an image there is none of,
+ * or a box with no size or no orientation. The rest are packed in order.
+ */
+export function packBaseDecals(decals, images, bandTop, out) {
+    out.fill(0);
+    let refusal = decals.length > MAX_BASE_DECALS
+        ? `${decals.length} base decals; a frame lays the first ${MAX_BASE_DECALS}`
+        : null;
+    let kept = 0;
+    for (let i = 0; i < decals.length && kept < MAX_BASE_DECALS; i++) {
+        const decal = decals[i];
+        if (!(Number.isInteger(decal.image) && decal.image >= 0 && decal.image < images)) {
+            refusal ??= `a base decal lays image ${decal.image} and there are ${images}`;
+            continue;
+        }
+        try {
+            worldToDecalMatrix(MATRIX, decal);
+        }
+        catch (cause) {
+            refusal ??= cause instanceof Error ? cause.message : String(cause);
+            continue;
+        }
+        const at = 4 + kept * 16;
+        for (let row = 0; row < 3; row++) {
+            out[at + row * 4] = MATRIX[row];
+            out[at + row * 4 + 1] = MATRIX[4 + row];
+            out[at + row * 4 + 2] = MATRIX[8 + row];
+            out[at + row * 4 + 3] = MATRIX[12 + row];
+        }
+        out[at + 12] = decal.image;
+        out[at + 13] = Math.min(1, Math.max(0, decal.opacity ?? 1));
+        out[at + 14] = decal.facingCos ?? 0.2;
+        kept += 1;
+    }
+    out[0] = kept;
+    out[1] = bandTop;
+    out[2] = BASE_DECAL_TILE;
+    return refusal;
+}