@driftengine/core 4.11.0 → 4.12.0

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

@@ -63,8 +63,11 @@ import { GpuClothBinding, GpuClothParticles, clothStandIn } from './clothTexture
 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';
+import { resolveTransmission } from '../../transmission.js';
+import { resolveOcclusionFade } from '../../occlusionFade.js';
 import { orthographicDepthSpan } from '../../lightMatrix.js';
-import { LAYER_FLOATS, packSurfaceLayers } from '../../surfaceLayers.js';
+import { LAYER_FLOATS, layerMaskMap, layeredProjection, layersFitBeside, packSurfaceLayers, } from '../../surfaceLayers.js';
+import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.js';
 import { frameReflectionsRefused, resolveFrameReflections, } from '../../frameReflections.js';
 import { REFLECTION_SURFACE_FORMAT, ReflectionSurfacePass } from './reflectionSurfacePass.js';
 import { validateClothBinding } from '../../clothBindingData.js';
@@ -228,6 +231,11 @@ const MAX_OVERLAYS = 64;
  * and passes nobody has written yet; the cost is sixteen kilobytes.
  */
 const MAX_SKY_DRAWS = 64;
+/** The draw a preparation asks pipelines for: every option at its default. See `prepareMesh`. */
+const PREPARED_DRAW = {};
+/** A preparation's morph states for a mesh with no targets, and for one with some. */
+const NOT_MORPHED = [false];
+const MORPHED_OR_NOT = [false, true];
 /**
  * Whether the environment probe's permutation fits this device's per-stage binding limits.
  *
@@ -1646,6 +1654,8 @@ export class WebGPURenderer {
     temporalHistoryUsable = false;
     aoStaging = new ArrayBuffer(AO_FRAG_SIZE);
     aoFloats = new Float32Array(this.aoStaging);
+    /** Where occlusion fades out with distance, `uFade`: none until a caller sets one. */
+    aoFade = new Float32Array([-1, 0]);
     aoBindGroup = null;
     aoBlurLayout;
     /**
@@ -2247,7 +2257,15 @@ export class WebGPURenderer {
     projection = new Float32Array(PROJECTION_FLOATS);
     /** `uLayers`, the material's layers packed by `packSurfaceLayers`. */
     layerFloats = new Float32Array(LAYER_FLOATS);
+    /** `uLayerLooks`, the material's layer picks and looks packed by `packLayerLooks`. */
+    lookFloats = new Float32Array(LOOK_FLOATS);
+    /**
+     * `uGlassTint` as the material leaves it, its light from behind and that light's colour, which a
+     * pane overwrites for its own draw and `releaseSeeThrough` puts back. See `transmission.ts`.
+     */
+    transmission = new Float32Array([-1, -1, -1, 0]);
     warnedLayersModelMap = false;
+    warnedLayersTriplanar = false;
     /** Its numbers, `uModelParams`, packed by `packModel`. */
     modelParams = new Float32Array(MODEL_PARAM_FLOATS);
     /**
@@ -2649,9 +2667,9 @@ export class WebGPURenderer {
         const orm = (material?.orm ?? null);
         const emissiveMap = (material?.emissive ?? null);
         const ownModelMap = (material?.modelMap ?? null);
-        /* A layered material's mask goes where a model's map would: see `SurfaceMaterial.layers`. */
+        /* A layered material's mask, where it is a map, goes where a model's would: surfaceLayers.ts. */
         const layers = this.layersOf(material);
-        const modelMap = ownModelMap ?? (layers?.mask ?? null);
+        const modelMap = ownModelMap ?? layerMaskMap(layers);
         this.materialModel = material?.model ?? null;
         const reflectivity = material?.reflectivity;
         const environmentGain = material?.environmentGain;
@@ -2715,11 +2733,14 @@ export class WebGPURenderer {
             if (material?.physicalSpecular === true)
                 this.enableLit('PHYSICAL_SPECULAR');
             /* Maps placed by the world: the first material that asks is when lit pipelines carry it. */
-            packSurfaceProjection(material?.projection, this.projection);
+            const projection = layeredProjection(material?.projection, layers);
+            if (projection !== (material?.projection ?? null))
+                this.warnLayersTriplanar();
+            packSurfaceProjection(projection, this.projection);
             f.set(this.projection, this.materialField('uWorldUv'));
-            /* How much light from behind it lets through, in the glass tint's spare lane. */
-            f[this.materialField('uGlassTint') + 3] =
-                Math.min(Math.max(material?.diffuseTransmission ?? 0, 0), 1) || 0;
+            /* How much light from behind it lets through, and its colour: transmission.ts. */
+            resolveTransmission(material, this.transmission);
+            f.set(this.transmission, this.materialField('uGlassTint'));
             if (this.projection[0] > 0)
                 this.enableLit('WORLD_UVS');
             /* And its layers, the first time a material blends any: layered.ts. */
@@ -2727,6 +2748,11 @@ export class WebGPURenderer {
             f.set(this.layerFloats, this.materialField('uLayers'));
             if (layers !== null)
                 this.enableLit('LAYERED');
+            /* And which layer of shared arrays each reads, with its look: layerLooks.ts. */
+            packLayerLooks(layers, this.lookFloats);
+            f.set(this.lookFloats, this.materialField('uLayerLooks'));
+            if (asksLayerLooks(layers))
+                this.enableLit('LAYER_LOOKS');
             f.set(this.modelParams, this.materialField('uModelParams'));
         });
         /*
@@ -5078,15 +5104,24 @@ export class WebGPURenderer {
         const layers = material?.layers ?? null;
         if (layers === null || layers.repeats.length === 0)
             return null;
-        if ((material?.modelMap ?? null) === null)
+        if (layersFitBeside(layers, material?.modelMap))
             return layers;
         if (!this.warnedLayersModelMap) {
             this.warnedLayersModelMap = true;
-            console.warn("WebGPU: a material's layers are drawn as one: its mask is read where a model's map goes, " +
-                'and this material carries a `modelMap` too.');
+            console.warn("WebGPU: a material's layers are drawn as one: its mask is a map, read where a model's map " +
+                "goes, and this material carries a `modelMap` too. A mask in the ORM array (`mask: 'orm'`) " +
+                "or the vertex colour (`mask: 'vertex'`) leaves the slot free.");
         }
         return null;
     }
+    /** Says once that a layered material's triplanar projection is laid on the horizontal plane. */
+    warnLayersTriplanar() {
+        if (this.warnedLayersTriplanar)
+            return;
+        this.warnedLayersTriplanar = true;
+        console.warn("WebGPU: a layered material's triplanar projection is laid on the horizontal plane: every " +
+            "layer's maps on three planes would be three times the reads. See `SurfaceMaterial.layers`.");
+    }
     /**
      * What the sun's moving layer is read through: the matrix its shadow pass was last drawn with,
      * where the lit pipelines carry one (`MOVING_SUN`); the environment's otherwise, which every caller
@@ -7155,9 +7190,11 @@ export class WebGPURenderer {
         /* And no projection: maps follow the mesh's coordinates until a material asks otherwise. */
         f.fill(0, at('uWorldUv'), at('uWorldUv') + 4);
         /* Nor light through from behind. See `SurfaceMaterial.diffuseTransmission`. */
-        f[at('uGlassTint') + 3] = 0;
+        resolveTransmission(null, this.transmission);
+        f.set(this.transmission, at('uGlassTint'));
         /* Nor layers: one layer until a material asks for more. */
         f.fill(0, at('uLayers'), at('uLayers') + LAYER_FLOATS);
+        f.fill(0, at('uLayerLooks'), at('uLayerLooks') + LOOK_FLOATS);
         f[at('uCutout')] = 0;
         f[at('uCutout') + 1] = 0;
         this.cutoutResolveStaged = 'hard';
@@ -7880,6 +7917,153 @@ export class WebGPURenderer {
            `TranslucentMeshOptions.tint` for why, and for the fade it was added for. */
         this.submitMesh(mesh, model, options.tint ?? null, Math.min(opacity, 1), true, options);
     }
+    /**
+     * Compile off the main thread every pipeline a draw of `mesh` in `material` takes. **The other
+     * backend's `prepareMesh` carries the contract**; here a draw's key is `meshShape`'s, so a prepared
+     * key is exactly the one the draw asks for, and the compiles are started as a skipping draw starts
+     * them (`PipelineCache.lit`) whatever `pipelineCompile` says, into the frame's own caches.
+     */
+    prepareMesh(mesh, material, options = {}) {
+        if (this.surface.lost)
+            return;
+        this.preparing(material, (into, blend) => {
+            const skinned = mesh.isSkinned;
+            const eight = skinned && mesh.isSkinnedEight;
+            for (const morphed of mesh.morph === null ? NOT_MORPHED : MORPHED_OR_NOT) {
+                this.meshShape(mesh, blend, PREPARED_DRAW, skinned, morphed, eight, false);
+                this.meshPipeline(blend, false, skinned, morphed, eight, false, into);
+            }
+        }, options);
+    }
+    /** `prepareMesh` for an instanced batch. See the other backend's `prepareInstanced`. */
+    prepareInstanced(batch, material, options = {}) {
+        if (this.surface.lost)
+            return;
+        this.preparing(material, (into, blend) => {
+            const coverage = !blend && this.cutoutResolveStaged === 'coverage';
+            this.instancedPipeline(batch.mesh, batch.animation !== null, blend, false, PREPARED_DRAW, true, 0, coverage, into);
+        }, options);
+    }
+    /**
+     * `material` set, every cache a draw in it may build into passed to `start` with whether that draw
+     * blends, compiles started rather than built (`PipelineCache.lit`), and then no material set and
+     * each cache back to what `pipelineCompile` says.
+     */
+    preparing(material, start, options) {
+        this.setMaterial(material);
+        this.skipCompiling(true);
+        try {
+            start(this.pipelines, false);
+            if (options.translucent === true) {
+                start(this.pipelines, true);
+                /* A blended draw in a reconstructing frame lands in the late pass, whose cache is its own. */
+                if (this.latePipelines !== this.pipelines)
+                    start(this.latePipelines, true);
+            }
+        }
+        finally {
+            this.skipCompiling(this.quality.pipelineCompile === 'skip');
+            this.setMaterial(null);
+        }
+    }
+    /** What `meshShape` worked out for the mesh draw at hand. Reused, so a draw allocates no record. */
+    drawShape = {
+        base: '',
+        key: '',
+        depthWrite: true,
+        layer: 0,
+        adds: false,
+        coverage: false,
+        splits: false,
+        modelKind: null,
+    };
+    /**
+     * The key a mesh draw's pipeline is cached under, and the pipeline state that key encodes, under
+     * the current material and these options, into `drawShape`. **The one statement of it**:
+     * `submitMesh` draws by it and `prepareMesh` compiles by it, so the two cannot disagree about a key.
+     */
+    meshShape(mesh, blend, options, skinned, morphed, eight, clothed) {
+        const modelKind = this.materialModel?.kind ?? null;
+        const base = mesh.key ?? 'flat:s0:u0';
+        const keyed = `${base}${morphed ? '|morph' : ''}${skinned ? (eight ? '|skin8' : '|skin') : ''}` +
+            `${clothed ? '|cloth' : ''}`;
+        /*
+         * Depth writing and the overlay layer are pipeline state on this backend, so they belong in
+         * the key: two draws of one mesh differing only in these would otherwise share a cached
+         * pipeline and the second would silently take the first one's depth behaviour.
+         *
+         * **Both suffixes are empty for the defaults**, which is what keeps the keys `createMesh`
+         * warms — `fullKey` and `${'`'}${'$'}{fullKey}|blend${'`'}` — the ones an ordinary draw still asks for. A
+         * caller that opts in pays one compile on its first draw, the same bargain the overlay
+         * pipelines above already make.
+         */
+        const depthWrite = options.depthWrite ?? true;
+        const layer = Math.min(Math.max(Math.round(options.depthLayer ?? 0), 0), MAX_DEPTH_LAYER);
+        /* Added rather than blended over: its own blend state, so its own pipeline. */
+        const adds = blend && options.additive === true;
+        const coverage = !blend && this.cutoutResolveStaged === 'coverage';
+        /* Skin under the screen-space blur draws its two halves; see `keepSkinDiffuse`. */
+        const splits = modelKind === 'skin' && !blend && this.skinSplits();
+        const key = `${keyed}${blend ? (adds ? '|add' : '|blend') : ''}` +
+            `${depthWrite ? '' : '|nodepth'}${layer > 0 ? `|dl${layer}` : ''}` +
+            /* The two order-independent buffers are two formats and two blend states, so a draw into
+               one must never share a cached pipeline with the same mesh drawn into the other. */
+            `${this.oitMode === 'none' ? '' : `|oit${this.oitMode}`}` +
+            /* Culling is pipeline state here: a two-sided surface culls nothing. */
+            `${this.materialDoubleSided ? '|2s' : ''}` +
+            /* And so is alpha-to-coverage, for a dithered cutout in a multisampled frame. */
+            `${coverage ? '|a2c' : ''}` +
+            /* And the material's shading model, which is the fragment stage's own switch. */
+            `${modelKind === null ? '' : `|m:${modelKind}`}` +
+            /* And which half of a skin it draws, under the screen-space blur. */
+            `${splits ? '|ss' : ''}`;
+        const shape = this.drawShape;
+        shape.base = base;
+        shape.key = key;
+        shape.depthWrite = depthWrite;
+        shape.layer = layer;
+        shape.adds = adds;
+        shape.coverage = coverage;
+        shape.splits = splits;
+        shape.modelKind = modelKind;
+        return shape;
+    }
+    /**
+     * The pipeline `drawShape` names: the one built, one built here, or none where draws skip a
+     * compile and this one has not landed (`PipelineCache.lit`) — and none for a split skin until all
+     * of its halves have.
+     */
+    meshPipeline(blend, lands, skinned, morphed, eight, clothed, 
+    /** Which cache to build into: the one the draw's target reads, unless a preparation says. */
+    into = null) {
+        const { base, key, depthWrite, layer, adds, coverage, splits, modelKind } = this.drawShape;
+        /*
+         * **Asynchronous by default, synchronous if it has to be, and never absent.**
+         *
+         * `createMesh` compiles off the main thread, so a draw can legitimately arrive before the
+         * driver has finished — a consumer that awaits `ready()` never sees this, and one that
+         * draws immediately gets the old behaviour rather than an exception. Correctness cannot be
+         * allowed to depend on which of those happened, so the miss builds the pipeline here and
+         * pays the compile it was trying to avoid. That is a slow frame; the alternative is a
+         * thrown error in the middle of one.
+         */
+        const pipelines = into ?? (blend ? this.blendedPipelines(lands) : this.targetPipelines());
+        let pipeline = pipelines.peek(key) ?? null;
+        if (pipeline === null) {
+            const present = this.meshPresent.get(base);
+            if (present === undefined) {
+                throw new Error(`WebGPU: no pipeline for ${key}; createMesh builds it`);
+            }
+            pipeline = flatPipeline(pipelines, this.surface.device, this.flatLayoutFor(skinned, morphed), this.variant, key, present, adds ? 'additive' : blend, skinned, morphed, depthWrite, layer, false, this.oitMode, this.materialDoubleSided, coverage, eight, clothed, modelKind, splits ? 'scene' : 'whole');
+        }
+        /* A split skin draws its three halves or none of them. */
+        if (pipeline !== null &&
+            splits &&
+            !this.skinHalvesReady(key, base, skinned, morphed, layer, eight, clothed)) {
+            pipeline = null;
+        }
+        return pipeline;
+    }
     /**
      * @param blend Which of the two entry points above this came through, and **not** something to
      * infer from `opacity`.
@@ -7999,7 +8183,6 @@ export class WebGPURenderer {
         const modelKind = this.materialModel?.kind ?? null;
         if (modelKind === 'eye')
             this.writeEyeAxis(model, this.skinPaletteSlot >= 0 && mesh.isSkinned);
-        const base = mesh.key ?? 'flat:s0:u0';
         /*
          * A rigged mesh takes the skinned vertex variant, an unrigged one the plain variant, and the
          * key carries the flag so the two never share a cached pipeline. A rigged mesh whose caller
@@ -8014,38 +8197,6 @@ export class WebGPURenderer {
         /* A cloth set and a skinned draw: the pipeline built with CLOTH_BOUND on, warmed when the
            binding was made. See `createClothBinding`. */
         const clothed = skinned && this.cloth !== null;
-        const keyed = `${base}${morphed ? '|morph' : ''}${skinned ? (eight ? '|skin8' : '|skin') : ''}` +
-            `${clothed ? '|cloth' : ''}`;
-        /*
-         * Depth writing and the overlay layer are pipeline state on this backend, so they belong in
-         * the key: two draws of one mesh differing only in these would otherwise share a cached
-         * pipeline and the second would silently take the first one's depth behaviour.
-         *
-         * **Both suffixes are empty for the defaults**, which is what keeps the keys `createMesh`
-         * warms — `fullKey` and `${'`'}${'$'}{fullKey}|blend${'`'}` — the ones an ordinary draw still asks for. A
-         * caller that opts in pays one compile on its first draw, the same bargain the overlay
-         * pipelines above already make.
-         */
-        const depthWrite = options.depthWrite ?? true;
-        const layer = Math.min(Math.max(Math.round(options.depthLayer ?? 0), 0), MAX_DEPTH_LAYER);
-        /* Added rather than blended over: its own blend state, so its own pipeline. */
-        const adds = blend && options.additive === true;
-        const coverage = !blend && this.cutoutResolveStaged === 'coverage';
-        /* Skin under the screen-space blur draws its two halves; see `keepSkinDiffuse`. */
-        const splits = modelKind === 'skin' && !blend && this.skinSplits();
-        const key = `${keyed}${blend ? (adds ? '|add' : '|blend') : ''}` +
-            `${depthWrite ? '' : '|nodepth'}${layer > 0 ? `|dl${layer}` : ''}` +
-            /* The two order-independent buffers are two formats and two blend states, so a draw into
-               one must never share a cached pipeline with the same mesh drawn into the other. */
-            `${this.oitMode === 'none' ? '' : `|oit${this.oitMode}`}` +
-            /* Culling is pipeline state here: a two-sided surface culls nothing. */
-            `${this.materialDoubleSided ? '|2s' : ''}` +
-            /* And so is alpha-to-coverage, for a dithered cutout in a multisampled frame. */
-            `${coverage ? '|a2c' : ''}` +
-            /* And the material's shading model, which is the fragment stage's own switch. */
-            `${modelKind === null ? '' : `|m:${modelKind}`}` +
-            /* And which half of a skin it draws, under the screen-space blur. */
-            `${splits ? '|ss' : ''}`;
         /*
          * The morph uniforms, written only for a morphed draw and read from the *morphed* variant's
          * field table. `FLAT_VERT_FIELDS` is the plain variant's and does not name them at all — every
@@ -8058,31 +8209,9 @@ export class WebGPURenderer {
             this.perDraw.writeInt(slot, fields.uMorphTargetCount.offset, mesh.morph.targetCount);
             this.perDraw.writeInt(slot, fields.uMorphTextureWidth.offset, mesh.morph.width);
         }
-        /*
-         * **Asynchronous by default, synchronous if it has to be, and never absent.**
-         *
-         * `createMesh` compiles off the main thread, so a draw can legitimately arrive before the
-         * driver has finished — a consumer that awaits `ready()` never sees this, and one that
-         * draws immediately gets the old behaviour rather than an exception. Correctness cannot be
-         * allowed to depend on which of those happened, so the miss builds the pipeline here and
-         * pays the compile it was trying to avoid. That is a slow frame; the alternative is a
-         * thrown error in the middle of one.
-         */
-        const pipelines = blend ? this.blendedPipelines(lands) : this.targetPipelines();
-        let pipeline = pipelines.peek(key) ?? null;
-        if (pipeline === null) {
-            const present = this.meshPresent.get(base);
-            if (present === undefined) {
-                throw new Error(`WebGPU: no pipeline for ${key}; createMesh builds it`);
-            }
-            pipeline = flatPipeline(pipelines, this.surface.device, this.flatLayoutFor(skinned, morphed), this.variant, key, present, adds ? 'additive' : blend, skinned, morphed, depthWrite, layer, false, this.oitMode, this.materialDoubleSided, coverage, eight, clothed, modelKind, splits ? 'scene' : 'whole');
-        }
-        /* A split skin draws its three halves or none of them. */
-        if (pipeline !== null &&
-            splits &&
-            !this.skinHalvesReady(key, base, skinned, morphed, layer, eight, clothed)) {
-            pipeline = null;
-        }
+        /* Its pipeline, by the key a prepared draw compiled too: see `meshShape`. */
+        const { base, key, layer, depthWrite, splits } = this.meshShape(mesh, blend, options, skinned, morphed, eight, clothed);
+        let pipeline = this.meshPipeline(blend, lands, skinned, morphed, eight, clothed);
         /*
          * Guards the draw call only, not the restore below.
          *
@@ -8388,6 +8517,8 @@ export class WebGPURenderer {
         const seeAt = this.materialField('uSeeThrough');
         this.perFrameFloats[seeAt] = 0;
         this.perFrameFloats[seeAt + 2] = 0;
+        /* The material's light through, over the pane's tint: transmission.ts. */
+        this.perFrameFloats.set(this.transmission, this.materialField('uGlassTint'));
     }
     /**
      * One draw, one material slot, one uniform slot, however many instances.
@@ -8401,6 +8532,41 @@ export class WebGPURenderer {
      * **What it gives up** against `drawMesh` is skinning and morphing, refused where the variant
      * is built, and a per-instance opacity: `opacity` here dims the whole batch.
      */
+    /**
+     * An instanced draw's pipeline under the current material and these options: the one built, one
+     * built here, or none while it compiles (`PipelineCache.lit`), its key, base and model left in
+     * `drawShape`. **The one statement of an instanced key**: `submitInstanced` draws by it and
+     * `prepareInstanced` compiles by it.
+     */
+    instancedPipeline(mesh, animated, blend, lands, options, depthWrite, layer, coverage, 
+    /** Which cache to build into: the one the draw's target reads, unless a preparation says. */
+    into = null) {
+        /* A batch shades by its material's model too; an eye's axis is a placement's, not a batch's. */
+        const modelKind = this.materialModel?.kind ?? null;
+        const base = mesh.key ?? 'flat:s0:u0';
+        /* `|inst` in the key, for the reason every other suffix is there: an instanced pipeline binds
+           a third vertex buffer and a different vertex module, and sharing a cache entry with the
+           plain one would hand a draw the wrong layout. */
+        const adds = blend && options.additive === true;
+        const key = `${base}|inst${!animated ? '' : '|anim'}${blend ? (adds ? '|add' : '|blend') : ''}` +
+            `${depthWrite ? '' : '|nodepth'}${layer > 0 ? `|dl${layer}` : ''}` +
+            `${this.materialDoubleSided ? '|2s' : ''}${coverage ? '|a2c' : ''}` +
+            `${modelKind === null ? '' : `|m:${modelKind}`}`;
+        const shape = this.drawShape;
+        shape.base = base;
+        shape.key = key;
+        shape.modelKind = modelKind;
+        const pipelines = into ?? (blend ? this.blendedPipelines(lands) : this.targetPipelines());
+        let pipeline = pipelines.peek(key) ?? null;
+        if (pipeline === null) {
+            const present = this.meshPresent.get(base);
+            if (present === undefined) {
+                throw new Error(`WebGPU: no mesh attributes recorded for ${base}; createMesh records them`);
+            }
+            pipeline = flatPipeline(pipelines, this.surface.device, !animated ? this.flatLayoutFor(false, false) : this.animatedBindGroupLayout, this.variant, key, present, adds ? 'additive' : blend, false, false, depthWrite, layer, true, 'none', this.materialDoubleSided, coverage, false, false, modelKind, 'whole', false, animated);
+        }
+        return pipeline;
+    }
     /**
      * The next of a batch's cull slots this frame, with its cull queued against the current view; null
      * when the batch has drawn from `MAX_CULL_SLOTS` views already or the frame's job ring is full,
@@ -8504,26 +8670,9 @@ export class WebGPURenderer {
         const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting }, this.surfaceFog) || ditheredBlend;
         if (own)
             this.materials.dirty();
-        /* A batch shades by its material's model too; an eye's axis is a placement's, not a batch's. */
-        const modelKind = this.materialModel?.kind ?? null;
-        const base = mesh.key ?? 'flat:s0:u0';
-        /* `|inst` in the key, for the reason every other suffix is there: an instanced pipeline binds
-           a third vertex buffer and a different vertex module, and sharing a cache entry with the
-           plain one would hand a draw the wrong layout. */
-        const adds = blend && options.additive === true;
-        const key = `${base}|inst${animation === null ? '' : '|anim'}${blend ? (adds ? '|add' : '|blend') : ''}` +
-            `${depthWrite ? '' : '|nodepth'}${layer > 0 ? `|dl${layer}` : ''}` +
-            `${this.materialDoubleSided ? '|2s' : ''}${coverage ? '|a2c' : ''}` +
-            `${modelKind === null ? '' : `|m:${modelKind}`}`;
-        const pipelines = blend ? this.blendedPipelines(lands) : this.targetPipelines();
-        let pipeline = pipelines.peek(key) ?? null;
-        if (pipeline === null) {
-            const present = this.meshPresent.get(base);
-            if (present === undefined) {
-                throw new Error(`WebGPU: no mesh attributes recorded for ${base}; createMesh records them`);
-            }
-            pipeline = flatPipeline(pipelines, this.surface.device, animation === null ? this.flatLayoutFor(false, false) : this.animatedBindGroupLayout, this.variant, key, present, adds ? 'additive' : blend, false, false, depthWrite, layer, true, 'none', this.materialDoubleSided, coverage, false, false, modelKind, 'whole', false, animation !== null);
-        }
+        /* Its pipeline, by the key a prepared batch compiled too: see `instancedPipeline`. */
+        const pipeline = this.instancedPipeline(mesh, animation !== null, blend, lands, options, depthWrite, layer, coverage);
+        const { base, key, modelKind } = this.drawShape;
         /* A batch whose pipeline is still compiling is left out, as a mesh is. */
         const material = pipeline === null ? null : this.materialSlotForDraw();
         if (pipeline !== null && material !== null) {
@@ -11581,6 +11730,7 @@ export class WebGPURenderer {
         const f = this.aoFloats;
         const at = (name) => this.postField(AO_FRAG_FIELDS, name);
         f[at('uRadius')] = this.quality.ambientOcclusionRadius;
+        f.set(this.aoFade, at('uFade'));
         f.set(this.aoProjScale, at('uProjScale'));
         f.set(this.aoInvProjection, at('uInvProjection'));
         device.queue.writeBuffer(this.aoUniforms, 0, this.aoStaging);
@@ -14172,6 +14322,13 @@ export class WebGPURenderer {
         this.exposurePass = new ExposurePass(this.surface.device, this.pipelines, this.postSampler);
         this.rebuildRushBindGroup();
     }
+    /**
+     * Where ambient occlusion fades out with distance. **The other backend's
+     * `setAmbientOcclusionFade` carries the reasoning**; this is the same setter over the same state.
+     */
+    setAmbientOcclusionFade(distance, radius) {
+        resolveOcclusionFade(distance, radius, this.aoFade);
+    }
     /**
      * Where this frame's lens is focused, how deep the sharp zone is, and how much of the ceiling
      * to take. **The other backend's `setDepthOfField` carries the reasoning**, whole: the

package/dist/render/instances.d.ts

@@ -46,9 +46,16 @@ export interface MeshInstances {
      * read by a draw whose material is a `lightmapModel` — instances of one mesh in one material sit
      * in different regions of one page, each applied before the material's own region. **They ride
      * the tint and the opacity**, which a lightmapped instance gives up (see `lightmap.ts`): where
-     * these are given, those are not read. **A lightmapped batch needs them**, since a bake is
+     * these are given, the tints are not read. **A lightmapped batch needs them**, since a bake is
      * different light at each instance; one drawn without them reads its tints as its regions, and
      * either mismatch is said once on the console.
+     *
+     * **The opacity survives, in sixty-fourths**, so a lightmapped instance fades by
+     * `setDitherOpacity` as any other does: its transparency travels as whole steps of 2 added to the
+     * region's U offset, which is a place in a page and so under 1, and the vertex stage takes them
+     * back off (`LIGHTMAP_OPACITY_STEPS`). Sixty-four is the screen door's own resolution, an 8x8
+     * pattern. **What it gives up**: a fading instance's offset keeps 16 bits of fraction rather than
+     * 23, a sixteenth of a texel on a 4,096 page; an opaque one is written to the bit as before.
      */
     readonly lightmapRegions?: Float32Array;
     /**
@@ -98,6 +105,11 @@ export declare function createMeshInstances(capacity: number): MeshInstances;
  * as one four-float attribute, so the opacity cost no attribute and no byte.
  */
 export declare const INSTANCE_FLOATS = 20;
+/**
+ * How finely a lightmapped instance's opacity travels in its region: transparency in steps of
+ * 1/64, each 2 on the U offset. See `MeshInstances.lightmapRegions`; the vertex stage reads it back.
+ */
+export declare const LIGHTMAP_OPACITY_STEPS = 64;
 /** Bytes one instance occupies. See `INSTANCE_FLOATS`. */
 export declare const INSTANCE_STRIDE: number;
 /**

package/dist/render/instances.js

@@ -26,6 +26,11 @@ export function createMeshInstances(capacity) {
  * as one four-float attribute, so the opacity cost no attribute and no byte.
  */
 export const INSTANCE_FLOATS = 20;
+/**
+ * How finely a lightmapped instance's opacity travels in its region: transparency in steps of
+ * 1/64, each 2 on the U offset. See `MeshInstances.lightmapRegions`; the vertex stage reads it back.
+ */
+export const LIGHTMAP_OPACITY_STEPS = 64;
 /** Bytes one instance occupies. See `INSTANCE_FLOATS`. */
 export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
 /**
@@ -56,6 +61,11 @@ export function packInstances(instances, out) {
             /* The region in the tint's and the opacity's place. See `lightmapRegions`. */
             for (let c = 0; c < 4; c += 1)
                 out[at + 16 + c] = lightmapRegions[i * 4 + c];
+            /* And the opacity's transparency in whole steps of 2 on the U offset, none where opaque. */
+            const alpha = Math.min(Math.max(alphas?.[i] ?? 1, 0), 1);
+            const steps = Math.round((1 - alpha) * LIGHTMAP_OPACITY_STEPS);
+            if (steps > 0)
+                out[at + 18] = out[at + 18] + 2 * steps;
             continue;
         }
         const t = i * 3;

package/dist/render/occlusionFade.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Where ambient occlusion fades out with distance: `setAmbientOcclusionFade`'s two numbers as the
+ * estimate reads them, `uFade` in `shaders/ambientOcclusion.ts`.
+ *
+ * **Occlusion is whole up to `distance` metres from the eye and gone `radius` metres past it.** A
+ * screen-space estimate reaches as far as the depth does, and far off the depth buffer's steps are
+ * metres apart: a sky dome or a mountain range kilometres away is shaded in rings that follow
+ * those steps, and nothing there is in contact with anything the estimate could be right about.
+ * A pixel past the fade skips the estimate's walk, as the sky does, so it costs less as well.
+ *
+ * **What it gives up**: distant contact shade that is real — a doorway a hundred metres off — fades
+ * with the rest, and the distance is the eye's and not the subject's, so a long lens fades what it
+ * frames close up. What would make it wrong is a scene whose far depth is precise enough to shade,
+ * which is a reason to fade further, not to leave the fade off.
+ */
+/**
+ * `distance` and `radius` into `out`, `[distance, radius]`. A distance that is not a finite number
+ * at or above zero is no fade, `[−1, 0]`, so `Infinity` reads as "never fades". A radius below zero
+ * or not a number is 0, which is a cut at `distance` rather than a ramp.
+ */
+export declare function resolveOcclusionFade(distance: number, radius: number, out: Float32Array): void;

package/dist/render/occlusionFade.js

@@ -0,0 +1,27 @@
+/**
+ * Where ambient occlusion fades out with distance: `setAmbientOcclusionFade`'s two numbers as the
+ * estimate reads them, `uFade` in `shaders/ambientOcclusion.ts`.
+ *
+ * **Occlusion is whole up to `distance` metres from the eye and gone `radius` metres past it.** A
+ * screen-space estimate reaches as far as the depth does, and far off the depth buffer's steps are
+ * metres apart: a sky dome or a mountain range kilometres away is shaded in rings that follow
+ * those steps, and nothing there is in contact with anything the estimate could be right about.
+ * A pixel past the fade skips the estimate's walk, as the sky does, so it costs less as well.
+ *
+ * **What it gives up**: distant contact shade that is real — a doorway a hundred metres off — fades
+ * with the rest, and the distance is the eye's and not the subject's, so a long lens fades what it
+ * frames close up. What would make it wrong is a scene whose far depth is precise enough to shade,
+ * which is a reason to fade further, not to leave the fade off.
+ */
+/** `uFade` for no fade: a distance below zero, which the estimate reads as "never". */
+const NO_FADE = -1;
+/**
+ * `distance` and `radius` into `out`, `[distance, radius]`. A distance that is not a finite number
+ * at or above zero is no fade, `[−1, 0]`, so `Infinity` reads as "never fades". A radius below zero
+ * or not a number is 0, which is a cut at `distance` rather than a ramp.
+ */
+export function resolveOcclusionFade(distance, radius, out) {
+    const fades = Number.isFinite(distance) && distance >= 0;
+    out[0] = fades ? distance : NO_FADE;
+    out[1] = fades && Number.isFinite(radius) ? Math.max(radius, 0) : 0;
+}

package/dist/render/sceneTarget.d.ts

@@ -313,6 +313,8 @@ export declare class SceneTarget {
         /** The projection's x and y scales, which turn a world radius into a screen one. */
         readonly projScale: Float32Array;
         readonly invProjection: Float32Array;
+        /** Where it fades out with distance, `uFade`: see `occlusionFade.ts`. */
+        readonly fade: Float32Array;
         /** Where the frame's jitter put the occlusion, in uv: see the shader's `uAoOffset`. */
         readonly offset?: Float32Array;
     }, bloom?: {

package/dist/render/sceneTarget.js

@@ -771,7 +771,7 @@ export class SceneTarget {
         let aoTexture = null;
         if (ao !== undefined && !this.depthBlitRefused && this.depth !== null) {
             this.ao ??= new AmbientOcclusionPass(gl);
-            aoTexture = this.ao.run(this.depth, this.width, this.height, ao.radius, ao.projScale, ao.invProjection);
+            aoTexture = this.ao.run(this.depth, this.width, this.height, ao.radius, ao.projScale, ao.invProjection, ao.fade);
         }
         /*
          * Bloom beside occlusion rather than after the composite, because the composite is what

package/dist/render/shaders/ambientOcclusion.js

@@ -75,6 +75,11 @@ uniform vec2 uProjScale;
 uniform mat4 uInvProjection;
 /** How far the sampling reaches, in metres of the world. */
 uniform float uRadius;
+/**
+ * Where occlusion fades out: whole up to x metres from the eye, gone y metres past it, and no fade
+ * where x is below zero. See occlusionFade.ts.
+ */
+uniform vec2 uFade;
 
 out float fragColor;
 
@@ -167,6 +172,12 @@ void main() {
     fragColor = 1.0;
     return;
   }
+  /* How far past the caller's fade this pixel is, and open with no walk where it is all the way. */
+  float faded = uFade.x < 0.0 ? 0.0 : clamp((length(p) - uFade.x) / max(uFade.y, 1e-4), 0.0, 1.0);
+  if (faded >= 1.0) {
+    fragColor = AO_STORE;
+    return;
+  }
 
   /*
    * At a silhouette, the quad derivative above is replaced by the one-sided difference that
@@ -307,7 +318,7 @@ void main() {
     visible += projectedLength * gtaoArc(h0, h1, normalAngle);
   }
 
-  fragColor = clamp(visible / float(AO_SLICES) * AO_STORE, 0.0, 1.0);
+  fragColor = clamp(mix(visible / float(AO_SLICES), 1.0, faded) * AO_STORE, 0.0, 1.0);
 }
 `;
 /**