@driftengine/core 4.11.0 → 4.12.0

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

@@ -37,8 +37,11 @@ import { compileProgram, finishProgram, startProgram, uniformLocations } from '.
 import { countUniformVectors, FULL_LIGHT_BUDGET, nextLightBudget, planLightBudget, } from '../../uniformVectorBudget.js';
 import { OVERLAY_FLOATS, overlayLays, packSurfaceOverlay, } from '../../surfaceOverlay.js';
 import { PROJECTION_FLOATS, packSurfaceProjection, projects } 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 { FILM_FRAG, FILM_VERT } from '../../shaders/film.js';
 import { SceneTarget } from '../../sceneTarget.js';
 import { FILM_LOOK_WITHOUT_COMPOSITE } from '../../shaders/filmLook.js';
@@ -785,6 +788,8 @@ export class WebGL2Renderer {
     aoProjScale = new Float32Array(2);
     /** Where this frame's jitter put the occlusion, in the composite's uv. See `uAoOffset`. */
     aoOffset = new Float32Array(2);
+    /** Where occlusion fades out with distance, `uFade`: none until a caller sets one. */
+    aoFade = new Float32Array([-1, 0]);
     /**
      * Whether this frame has already been resolved to the canvas.
      *
@@ -952,14 +957,23 @@ export class WebGL2Renderer {
     warnedProjectionRoom = false;
     /** `uWorldUv`, the current material's projection packed. See `surfaceProjection.ts`. */
     projection = new Float32Array(PROJECTION_FLOATS);
-    /** The current material's `diffuseTransmission`, `uGlassTint.w`, 0 to 1. */
-    diffuseTransmission = 0;
+    /**
+     * `uGlassTint` as the current material leaves it: its light from behind and that light's colour,
+     * which a pane overwrites for its own draw and `unbindSeeThrough` puts back. See `transmission.ts`.
+     */
+    transmission = new Float32Array([-1, -1, -1, 0]);
     /** `uLayers`, the current material's layers packed. See `surfaceLayers.ts`. */
     layerFloats = new Float32Array(LAYER_FLOATS);
+    /** `uLayerLooks`, the current material's layer picks and looks packed. See `surfaceLayerLooks.ts`. */
+    lookFloats = new Float32Array(LOOK_FLOATS);
     /** Whether the lit stage has room for layers' two vectors, and which refusals were said. */
     layersRoom = null;
     warnedLayersRoom = false;
+    /** Whether it has room for the layers' looks beside them, and whether the refusal was said. */
+    looksRoom = null;
+    warnedLooksRoom = false;
     warnedLayersModelMap = false;
+    warnedLayersTriplanar = false;
     warnedOverlayRoom = false;
     warnedOverlayBlocks = false;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
@@ -2861,6 +2875,57 @@ export class WebGL2Renderer {
      * `uScale`/`vScale` are repeats across the mesh's own UV range: geometry authored in
      * metres is textured at whatever density the material wants without rebuilding it.
      */
+    /**
+     * Compile, off the frame, every program a draw of `mesh` in `material` takes that making the mesh
+     * did not, so the first frame that draws it waits on none: the program of the material's shading
+     * model for each vertex variant the mesh can be drawn with (its rig, with a palette; its targets,
+     * with weights and without), a skin's halves under the screen-space blur, and the lit switches
+     * the material turns on. `ready()` resolves once they have.
+     *
+     * **For `pipelineCompile: 'skip'` above all**, where a draw whose program is new is left out until
+     * it lands: a figure brought on screen whole rather than without its face and hair for the frames
+     * those take. Where draws wait, the programs compile here, at the call, rather than in a frame.
+     * Two-sided and cut-out surfaces are draw state on this backend and need nothing; on WebGPU they
+     * are pipelines of their own, prepared the same way.
+     *
+     * **Call it between frames**: it sets `material` to read it and leaves no material set after, as
+     * `setMaterial(null)` does. `options` is the other backend's; blended draws share a program here.
+     */
+    prepareMesh(mesh, material, _options = {}) {
+        if (this.contextLost)
+            return;
+        this.setMaterial(material);
+        const kind = material?.model?.kind ?? null;
+        if (kind !== null) {
+            const eight = mesh.isSkinnedEight;
+            const morphs = mesh.morph !== null;
+            const plain = mesh.isSkinned ? (eight ? 'skinned8' : 'skinned') : 'plain';
+            const morphed = mesh.isSkinned ? (eight ? 'both8' : 'both') : 'morphed';
+            for (const variant of morphs ? [plain, morphed] : [plain]) {
+                this.modelProgram(variant, kind);
+                /* A skin under the screen-space blur draws three halves, each a program of its own. */
+                if (kind === 'skin' && this.skinScatter !== null && this.sceneTarget !== null) {
+                    for (const half of SPLIT_SKIN_HALVES)
+                        this.modelProgram(variant, kind, half);
+                }
+            }
+        }
+        this.setMaterial(null);
+    }
+    /** `prepareMesh` for an instanced batch: its own programs, and its model's for its variant. */
+    prepareInstanced(batch, material, _options = {}) {
+        if (this.contextLost)
+            return;
+        this.setMaterial(material);
+        const animated = batch.animation !== null;
+        this.ensureInstancedProgram();
+        if (animated)
+            this.ensureAnimatedProgram();
+        const kind = material?.model?.kind ?? null;
+        if (kind !== null)
+            this.modelProgram(animated ? 'animated' : 'instanced', kind);
+        this.setMaterial(null);
+    }
     /**
      * Choose the joint palette the following `drawMesh` calls skin by, or null for none.
      *
@@ -3197,9 +3262,9 @@ export class WebGL2Renderer {
          * and read neither — one decision for every program, as `setMaterial` says.
          */
         const modelMap = 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 boundMap = modelMap ?? layers?.mask ?? null;
+        const boundMap = modelMap ?? layerMaskMap(layers);
         gl.activeTexture(gl.TEXTURE0 + MODEL_MAP_TEXTURE_UNIT);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
         if (boundMap !== null)
@@ -3208,6 +3273,10 @@ export class WebGL2Renderer {
         if (layers !== null)
             this.askLit('LAYERED');
         gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
+        packLayerLooks(layers, this.lookFloats);
+        if (this.looksFit(layers))
+            this.askLit('LAYER_LOOKS');
+        gl.uniform4fv(u['uLayerLooks'] ?? null, this.lookFloats);
         gl.uniform1i(u['uModelMap'] ?? null, MODEL_MAP_TEXTURE_UNIT);
         packModel(material?.model ?? null, modelMap !== null, this.modelParams, material?.physicalSpecular === true);
         /* The first physical highlight asked for is when the lit programs start carrying one. */
@@ -3217,11 +3286,13 @@ export class WebGL2Renderer {
         /* The draw's overlay, which a program born mid-pass must wear too: see `setSurfaceOverlay`. */
         gl.uniform4fv(u['uOverlay'] ?? null, this.overlayFloats);
         gl.uniform4fv(u['uWorldUv'] ?? null, this.projection);
-        /* How much light from behind the surface lets through, in the glass tint's spare lane. */
-        this.diffuseTransmission = Math.min(Math.max(material?.diffuseTransmission ?? 0, 0), 1) || 0;
-        gl.uniform4f(u['uGlassTint'] ?? null, 1, 1, 1, this.diffuseTransmission);
+        /* How much light from behind the surface lets through, and its colour: transmission.ts. */
+        resolveTransmission(material, this.transmission);
+        this.writeTransmission(u);
         /* Maps placed by the world, where the material asks and the lit stage has room: worldUv.ts. */
-        const projection = material?.projection ?? null;
+        const projection = layeredProjection(material?.projection, layers);
+        if (projection !== (material?.projection ?? null))
+            this.warnLayersTriplanar();
         packSurfaceProjection(this.projectionFits(projection) ? projection : null, this.projection);
         if (this.projection[0] > 0)
             this.askLit('WORLD_UVS');
@@ -3455,14 +3526,15 @@ export class WebGL2Renderer {
      * no room for their two vectors each leave one layer, the last two said once each.
      */
     layersOf(material) {
-        const layers = material?.layers ?? null;
+        const layers = (material?.layers ?? null);
         if (layers === null || layers.repeats.length === 0)
             return null;
-        if ((material?.modelMap ?? null) !== null) {
+        if (!layersFitBeside(layers, material?.modelMap)) {
             if (!this.warnedLayersModelMap) {
                 this.warnedLayersModelMap = true;
-                console.warn("Renderer: 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("Renderer: 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;
         }
@@ -3471,15 +3543,49 @@ export class WebGL2Renderer {
             return layers;
         if (!this.warnedLayersRoom) {
             this.warnedLayersRoom = true;
-            console.warn("Renderer: a material's layers are refused on this device. They take two fragment uniform " +
+            console.warn("Renderer: a material's layers are refused on this device. They take four fragment uniform " +
                 'vectors the lit shader does not have; the material is drawn as its base layer. A lower ' +
                 '`maxLights` makes the room, or WebGPU has it.');
         }
         return null;
     }
-    /** Whether the lit shader with `feature` compiled in fits this GPU's fragment uniform vectors. */
-    switchFits(feature) {
+    /**
+     * Whether a layered material's picks and looks are drawn: asked for, and room for their fifteen
+     * vectors beside the layers' four. Refused, the layers are drawn reading layer `i` of their arrays
+     * as they are, said once — which on a material sharing its arrays reads the wrong textures, so
+     * the sentence names the way out.
+     */
+    looksFit(layers) {
+        if (!asksLayerLooks(layers))
+            return false;
+        this.looksRoom ??= this.switchFits('LAYER_LOOKS', 'LAYERED');
+        if (this.looksRoom)
+            return true;
+        if (!this.warnedLooksRoom) {
+            this.warnedLooksRoom = true;
+            console.warn("Renderer: a layered material's picks and looks are refused on this device. They take " +
+                'fifteen fragment uniform vectors the lit shader does not have, so its layers read layer ' +
+                'i of its arrays, untinted, at one repeat each. A lower `maxLights` makes the room, or ' +
+                'WebGPU has it.');
+        }
+        return false;
+    }
+    /** 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("Renderer: 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`.");
+    }
+    /**
+     * Whether the lit shader with `feature` compiled in, and `beside` with it where a switch means
+     * nothing alone, fits this GPU's fragment uniform vectors.
+     */
+    switchFits(feature, beside) {
         const asIf = { [feature]: true };
+        if (beside !== undefined)
+            asIf[beside] = true;
         return (countUniformVectors(this.flatFragAt(this.lightBudget, asIf)) <= this.fragmentVectorLimit());
     }
     /**
@@ -3635,7 +3741,8 @@ export class WebGL2Renderer {
      *
      * What it gives up: a fade reads as grain while it lasts, which a temporal resolve smooths and a
      * plain frame does not; a blended draw that asks spends its opacity here and blends none of it;
-     * and a lightmapped batch carries regions where the opacities would be, so it has none to fade.
+     * and a lightmapped batch's opacities ride its page regions, so they fade in steps of a
+     * sixty-fourth, which is the pattern's own resolution (`MeshInstances.lightmapRegions`).
      */
     setDitherOpacity(on) {
         if (this.contextLost)
@@ -4106,13 +4213,20 @@ export class WebGL2Renderer {
         const tint = options.refractTint ?? WHITE_TINT;
         gl.uniform4f(u['uRefractTint'] ?? null, tint[0] ?? 1, tint[1] ?? 1, tint[2] ?? 1, 1);
         /* The pane's colour; w is the material's light through from behind, which glass never reads. */
-        gl.uniform4f(u['uGlassTint'] ?? null, glass.tint[0] ?? 1, glass.tint[1] ?? 1, glass.tint[2] ?? 1, this.diffuseTransmission);
+        gl.uniform4f(u['uGlassTint'] ?? null, glass.tint[0] ?? 1, glass.tint[1] ?? 1, glass.tint[2] ?? 1, this.transmission[3]);
         return true;
     }
+    /** `uGlassTint` as the current material leaves it. See `transmission`. */
+    writeTransmission(u) {
+        const t = this.transmission;
+        this.gl.uniform4f(u['uGlassTint'] ?? null, t[0] ?? -1, t[1] ?? -1, t[2] ?? -1, t[3] ?? 0);
+    }
     /** Put back what `bindSeeThrough` bound: the binding outlives its frame (the 2026-08-27 rule). */
     unbindSeeThrough(u) {
         const { gl } = this;
         gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);
+        /* The material's light through, over the pane's tint: transmission.ts. */
+        this.writeTransmission(u);
         gl.activeTexture(gl.TEXTURE0 + REFRACT_SCENE_TEXTURE_UNIT);
         /* The overlay's atlas, where one is held: it shares the unit. See `setSurfaceOverlay`. */
         gl.bindTexture(gl.TEXTURE_2D, this.overlayTexture ?? this.emptyTexture2D);
@@ -5417,6 +5531,7 @@ export class WebGL2Renderer {
             worldUvs: asIf.WORLD_UVS ?? this.litOn.WORLD_UVS,
             movingSun: asIf.MOVING_SUN ?? this.litOn.MOVING_SUN,
             layered: asIf.LAYERED ?? this.litOn.LAYERED,
+            layerLooks: asIf.LAYER_LOOKS ?? this.litOn.LAYER_LOOKS,
             maxLights: budget.maxLights,
             maxAreaLights: budget.maxAreaLights,
         });
@@ -6177,6 +6292,19 @@ export class WebGL2Renderer {
         }
         this.sceneTarget.setLocalExposure(strength);
     }
+    /**
+     * Where ambient occlusion fades out with distance: whole up to `distance` metres from the eye and
+     * gone `radius` metres past it, so the far depth buffer's steps — a sky dome kilometres off, a
+     * mountain range — are not shaded in rings, and those pixels skip the occlusion's sampling.
+     *
+     * A distance that is not a finite number at or above zero is no fade, which is the default, and
+     * `Infinity` reads as "never fades"; a radius below zero is a cut at `distance`. Set before
+     * `endFrame` and held until changed, like `setDepthOfField`. Nothing at all when
+     * `ambientOcclusion` is 0. See `occlusionFade.ts` for what it gives up.
+     */
+    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.
@@ -6804,6 +6932,7 @@ export class WebGL2Renderer {
                 radius: this.quality.ambientOcclusionRadius,
                 projScale: this.aoProjScale,
                 invProjection: this.aoInvProjection,
+                fade: this.aoFade,
                 offset: this.aoOffset,
             };
         }
@@ -7256,9 +7385,10 @@ export class WebGL2Renderer {
         /* Nor a projection: maps follow the mesh's coordinates until a material asks otherwise. */
         this.projection.fill(0);
         /* Nor light through from behind. See `SurfaceMaterial.diffuseTransmission`. */
-        this.diffuseTransmission = 0;
+        resolveTransmission(null, this.transmission);
         /* Nor layers: one layer until a material asks for more. */
         this.layerFloats.fill(0);
+        this.lookFloats.fill(0);
         this.overlayMaps = null;
         this.overlayTexture = null;
         /* Nor an ambient of its own: the frame's, until a draw asks. See `setAmbientSH`. */
@@ -7402,12 +7532,14 @@ export class WebGL2Renderer {
         gl.uniform4fv(u['uOverlay'] ?? null, this.overlayFloats);
         gl.uniform4fv(u['uWorldUv'] ?? null, this.projection);
         gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
+        gl.uniform4fv(u['uLayerLooks'] ?? null, this.lookFloats);
         /* Neither refracting nor glass, which is every draw that does not say otherwise. See
            `bindSeeThrough` for the four numbers in the one vector. */
         gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);
         gl.uniform4f(u['uRefractTint'] ?? null, 1, 1, 1, 1);
-        /* White, and no light through from behind: no material at a pass's start. */
-        gl.uniform4f(u['uGlassTint'] ?? null, 1, 1, 1, this.diffuseTransmission);
+        /* No light through from behind: no material at a pass's start. See `writeTransmission`. */
+        const through = this.transmission;
+        gl.uniform4f(u['uGlassTint'] ?? null, through[0] ?? -1, through[1] ?? -1, through[2] ?? -1, through[3] ?? 0);
         gl.uniform3fv(u['uDirectionalDir'] ?? null, env.directionalDir);
         gl.uniform3fv(u['uDirectionalColor'] ?? null, env.directionalColor);
         gl.uniform3fv(u['uAmbient'] ?? null, env.ambient);

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

@@ -7,7 +7,7 @@ import type { PickHit, PickableSource } from '../../pickable.ts';
 import type { RendererApi } from '../api.ts';
 import { GpuTimestamps } from './gpuTimestamps.ts';
 import type { Environment, FilmOptions, InsetRect, LightVolumeDrawOptions, SkyColors, TranslucentMeshOptions } from '../webgl2/renderer.ts';
-import type { IncrementalMeshHandle, MeshOptions } from '../api.ts';
+import type { IncrementalMeshHandle, MeshOptions, PrepareOptions } from '../api.ts';
 import type { LightmapPage } from '../../lightmap.ts';
 import { type BloomResponse } from '../../bloomChain.ts';
 import type { WaterBody } from '../../waterRenderer.ts';
@@ -851,6 +851,8 @@ export declare class WebGPURenderer implements RendererApi {
     private temporalHistoryUsable;
     private readonly aoStaging;
     private readonly aoFloats;
+    /** Where occlusion fades out with distance, `uFade`: none until a caller sets one. */
+    private readonly aoFade;
     private aoBindGroup;
     private readonly aoBlurLayout;
     /**
@@ -1187,7 +1189,15 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly projection;
     /** `uLayers`, the material's layers packed by `packSurfaceLayers`. */
     private readonly layerFloats;
+    /** `uLayerLooks`, the material's layer picks and looks packed by `packLayerLooks`. */
+    private readonly lookFloats;
+    /**
+     * `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`.
+     */
+    private readonly transmission;
     private warnedLayersModelMap;
+    private warnedLayersTriplanar;
     /** Its numbers, `uModelParams`, packed by `packModel`. */
     private readonly modelParams;
     /**
@@ -2093,6 +2103,8 @@ export declare class WebGPURenderer implements RendererApi {
      * said once, leave one layer.
      */
     private layersOf;
+    /** Says once that a layered material's triplanar projection is laid on the horizontal plane. */
+    private warnLayersTriplanar;
     /**
      * 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
@@ -2478,6 +2490,35 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private refuseOitMultisampled;
     drawTranslucentMesh(mesh: GpuMesh, model: ReadonlyMat4, opacity: number, options?: TranslucentMeshOptions): void;
+    /**
+     * 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: GpuMesh, material: SurfaceMaterial<GpuSurfaceTexture> | null, options?: PrepareOptions): void;
+    /** `prepareMesh` for an instanced batch. See the other backend's `prepareInstanced`. */
+    prepareInstanced(batch: GpuInstancedBatch, material: SurfaceMaterial<GpuSurfaceTexture> | null, options?: PrepareOptions): void;
+    /**
+     * `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.
+     */
+    private preparing;
+    /** What `meshShape` worked out for the mesh draw at hand. Reused, so a draw allocates no record. */
+    private readonly drawShape;
+    /**
+     * 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.
+     */
+    private meshShape;
+    /**
+     * 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.
+     */
+    private meshPipeline;
     /**
      * @param blend Which of the two entry points above this came through, and **not** something to
      * infer from `opacity`.
@@ -2568,6 +2609,13 @@ export declare class WebGPURenderer implements RendererApi {
      * **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.
+     */
+    private instancedPipeline;
     /**
      * 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,
@@ -3994,6 +4042,11 @@ export declare class WebGPURenderer implements RendererApi {
     setLocalExposure(strength: number): void;
     /** The exposure pass, built once; the composite's group holds placeholders until it exists. */
     private ensureExposurePass;
+    /**
+     * 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: number, radius: number): void;
     /**
      * 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