@driftengine/core 4.13.1 → 4.13.3

package/dist/render/mesh.js

@@ -92,6 +92,12 @@ export class Mesh {
      * this — two references, and only where a consumer asked.
      */
     deformable = null;
+    /** A dynamic mesh's position and normal buffers, for a pose written on the device; else null. */
+    get streams() {
+        return this.deformable;
+    }
+    /** The colour buffer, kept so `updateColors` can rewrite it. Null unless `dynamicColors`. */
+    recolourable = null;
     /** How many floats the position buffer holds, so an update of the wrong size is refused. */
     positionFloats;
     /**
@@ -191,8 +197,9 @@ export class Mesh {
      * and the default is the fast path: filling a buffer with `bufferData` in one call skips the
      * zero-fill that `bufferData(size)` then `bufferSubData` pays for, and every mesh in the
      * engine that does not need to be spread should keep skipping it.
+     * @param dynamicColors Colours as floats in a buffer kept for `updateColors`.
      */
-    constructor(gl, data, dynamic = false, spread = false) {
+    constructor(gl, data, dynamic = false, spread = false, dynamicColors = false) {
         validateMeshData(data);
         this.spread = spread;
         this.hasUvs = data.uvs !== undefined;
@@ -212,12 +219,17 @@ export class Mesh {
          */
         const usage = dynamic ? gl.DYNAMIC_DRAW : gl.STATIC_DRAW;
         /* How each attribute travels: sixteen-bit fixed point, or one value as a constant. */
-        const packing = vertexPackingOf(data, dynamic);
+        const packing = vertexPackingOf(data, dynamic, dynamicColors);
         const positions = this.attachAttribute(gl, ATTR_POSITION, data.positions, 3, usage);
         const normals = this.attachAttribute(gl, ATTR_NORMAL, data.normals, 3, usage, packing.normals);
         if (dynamic)
             this.deformable = { positions, normals };
-        this.attachShared(gl, ATTR_COLOR, data.colors, 3, packing.colors);
+        if (packing.colors === 'stream') {
+            this.recolourable = this.attachAttribute(gl, ATTR_COLOR, data.colors, 3, gl.DYNAMIC_DRAW);
+        }
+        else {
+            this.attachShared(gl, ATTR_COLOR, data.colors, 3, packing.colors);
+        }
         this.attachShared(gl, ATTR_EMISSIVE, data.emissive, 1, packing.emissive);
         /*
          * Absent means "not shiny", supplied as a constant rather than as a buffer of
@@ -418,9 +430,9 @@ export class Mesh {
     /**
      * Rewrite this mesh's positions, and its normals where the caller has them.
      *
-     * **Only the two attributes that move.** Colour, emissive and the rest describe what a surface
-     * *is* and do not change because it bent; rewriting them would be uploading unchanged bytes
-     * every frame. A caller with genuinely changing colour wants a second mesh or a tint.
+     * **Only the two attributes that move.** Emissive and the rest describe what a surface *is* and
+     * do not change because it bent; rewriting them would be uploading unchanged bytes every frame.
+     * A caller whose colours change has `updateColors`, on a mesh made `dynamicColors`.
      *
      * **The bounds are recomputed**, because everything that decides whether this is on screen
      * starts from them — a cloth that blew sideways out of its original box would be culled while
@@ -445,6 +457,25 @@ export class Mesh {
             gl.bufferSubData(gl.ARRAY_BUFFER, 0, normals);
         }
     }
+    /**
+     * Rewrite this mesh's colours, three floats a vertex, into the buffer they have to themselves.
+     *
+     * Nothing else moves, the bounds included: a colour does not change where a vertex is.
+     */
+    updateColors(gl, colors) {
+        if (this.recolourable === null) {
+            throw new Error('this mesh was not created with { dynamicColors: true }, so its colours are packed or are ' +
+                'one value with no buffer at all, and cannot be rewritten. Say so at `createMesh`: the ' +
+                'flag gives the colours a buffer of their own.');
+        }
+        if (colors.length !== this.positionFloats) {
+            throw new Error(`this mesh has ${this.positionFloats / 3} vertices and the colours have ` +
+                `${colors.length / 3}. A mesh's vertex count is fixed at creation: the index buffer, ` +
+                'the pipeline and every other attribute are sized against it.');
+        }
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.recolourable);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, colors);
+    }
     /**
      * One attribute's buffer, as floats or in its sixteen-bit fixed point (`vertexPacking.ts`), which
      * WebGL2 reads back through a normalised `SHORT` or `UNSIGNED_SHORT`: three lanes wide where
@@ -537,8 +568,8 @@ export class Mesh {
  * the allocations. The bounds are the deliberate one — a streamer places and culls a region from
  * them before a byte of it has landed.
  */
-export function createMeshIncremental(gl, data, dynamic = false) {
-    const mesh = new Mesh(gl, data, dynamic, true);
+export function createMeshIncremental(gl, data, dynamic = false, dynamicColors = false) {
+    const mesh = new Mesh(gl, data, dynamic, true, dynamicColors);
     return { mesh, upload: mesh.uploads(gl) };
 }
 /** Texture coordinates and layers interleaved as (u, v, layer), one row a vertex. */

package/dist/render/pointSkin.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A mesh posed on the device from weighted points in its joints' own spaces: the data, its checks,
+ * and the bounds a pose is culled by. Each backend's binding poses the vertices.
+ *
+ * **What it is for.** Some formats store a vertex as up to four points, each in the space of a
+ * joint, with a weight each and a normal in the space of the first: posed, the vertex is the
+ * weighted sum of each point moved by its joint. That is not ordinary skinning, which moves one
+ * bind-pose position by a blend of joints, so a rig of that kind had to be posed on the main thread
+ * and its positions uploaded every frame. Reported at 38% of the main thread's drawing time.
+ * Posed on the device into a dynamic mesh's own buffers, the main thread hands over the joints.
+ *
+ * **Into a dynamic mesh rather than in the vertex stage**, because a skinned vertex stage has no
+ * attribute left for four more points, and every pass that draws a mesh would need a variant that
+ * reads them: lit, cast, glass, motion. Posed once into the mesh's positions and normals, it is an
+ * ordinary dynamic mesh to every one of them, motion vectors included. What it costs is the mesh's
+ * two buffers, written a pose, and a pass that runs before the draws.
+ *
+ * **The bounds are a box of spheres, not the posed vertices**, which the CPU never sees. Each joint
+ * reaches as far as the farthest point a weighted influence holds in its space, scaled by its
+ * largest axis; a weighted sum of points inside those spheres lies inside their box, scaled by the
+ * least and greatest sums of a vertex's weights. Conservative, so it culls nothing visible; loose
+ * by the joints' reach where a mesh is long and thin, which culls a little less than it could.
+ */
+import type { Bounds } from '../math/bounds.ts';
+/** A point skin, one entry a vertex unless said otherwise. */
+export interface PointSkinData {
+    /** Four joint indices a vertex, as floats, as `MeshData.joints` is. */
+    readonly joints: Float32Array;
+    /** Four weights a vertex. An influence of weight 0 is skipped, whatever its joint and point. */
+    readonly weights: Float32Array;
+    /** Four points a vertex, three floats each: influence `k`'s point in joint `k`'s own space. */
+    readonly points: Float32Array;
+    /** One normal a vertex, in the space of its first joint. */
+    readonly normals: Float32Array;
+}
+/** How far a skin reaches from each joint, and what its weights sum to: what a pose's bounds need. */
+export interface PointSkinReach {
+    /** Joints a pose must hand over: one past the highest any vertex names and uses. */
+    readonly joints: number;
+    /** For each joint, the farthest point a weighted influence holds in its space; -1 where none. */
+    readonly reach: Float32Array;
+    /** The least and the greatest sum of one vertex's weights. */
+    readonly sums: readonly [number, number];
+}
+/** Refuse a skin whose arrays disagree with a mesh of `vertices`, or that names a joint past the rest. */
+export declare function validatePointSkin(data: PointSkinData, vertices: number): void;
+/** Measure a skin's reach once, at creation. */
+export declare function reachOf(data: PointSkinData): PointSkinReach;
+/**
+ * The bounds of a pose, into the mesh's own: `matrices` holds each joint's transform into the
+ * mesh's model space, sixteen floats, column-major. Allocates nothing.
+ */
+export declare function poseBounds(matrices: Float32Array, skin: PointSkinReach, out: Bounds): void;
+/** Refuse a pose that hands over fewer joints than the skin names. */
+export declare function validatePose(matrices: Float32Array, skin: PointSkinReach): void;

package/dist/render/pointSkin.js

@@ -0,0 +1,121 @@
+import { MAX_JOINTS } from './skinPalette.js';
+/** Refuse a skin whose arrays disagree with a mesh of `vertices`, or that names a joint past the rest. */
+export function validatePointSkin(data, vertices) {
+    const fail = (what) => {
+        throw new Error(`point skin: ${what}`);
+    };
+    for (const [name, values, width] of [
+        ['joints', data.joints, 4],
+        ['weights', data.weights, 4],
+        ['points', data.points, 12],
+        ['normals', data.normals, 3],
+    ]) {
+        if (values.length !== vertices * width) {
+            fail(`${name} holds ${values.length / width} vertices and the mesh has ${vertices}`);
+        }
+    }
+    for (let at = 0; at < data.joints.length; at++) {
+        const joint = data.joints[at];
+        if (!(Number.isInteger(joint) && joint >= 0 && joint < MAX_JOINTS)) {
+            fail(`vertex ${Math.floor(at / 4)} names joint ${joint}; a joint is 0 to ${MAX_JOINTS - 1}`);
+        }
+    }
+}
+/** Measure a skin's reach once, at creation. */
+export function reachOf(data) {
+    const reach = new Float32Array(MAX_JOINTS).fill(-1);
+    let joints = 0;
+    let least = Infinity;
+    let most = -Infinity;
+    const vertices = data.weights.length / 4;
+    for (let v = 0; v < vertices; v++) {
+        /* The first joint carries the normal, so it is named whatever its weight. */
+        joints = Math.max(joints, data.joints[v * 4] + 1);
+        let sum = 0;
+        for (let k = 0; k < 4; k++) {
+            const weight = data.weights[v * 4 + k];
+            if (weight === 0)
+                continue;
+            sum += weight;
+            const joint = data.joints[v * 4 + k];
+            joints = Math.max(joints, joint + 1);
+            const at = (v * 4 + k) * 3;
+            const x = data.points[at];
+            const y = data.points[at + 1];
+            const z = data.points[at + 2];
+            reach[joint] = Math.max(reach[joint], Math.sqrt(x * x + y * y + z * z));
+        }
+        least = Math.min(least, sum);
+        most = Math.max(most, sum);
+    }
+    return {
+        joints,
+        reach: reach.slice(0, joints),
+        sums: vertices === 0 ? [1, 1] : [least, most],
+    };
+}
+/**
+ * The bounds of a pose, into the mesh's own: `matrices` holds each joint's transform into the
+ * mesh's model space, sixteen floats, column-major. Allocates nothing.
+ */
+export function poseBounds(matrices, skin, out) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (let j = 0; j < skin.joints; j++) {
+        const reach = skin.reach[j];
+        if (reach < 0)
+            continue;
+        const m = j * 16;
+        const scale = Math.sqrt(Math.max(columnLength2(matrices, m), columnLength2(matrices, m + 4), columnLength2(matrices, m + 8)));
+        const r = reach * scale;
+        const x = matrices[m + 12];
+        const y = matrices[m + 13];
+        const z = matrices[m + 14];
+        minX = Math.min(minX, x - r);
+        minY = Math.min(minY, y - r);
+        minZ = Math.min(minZ, z - r);
+        maxX = Math.max(maxX, x + r);
+        maxY = Math.max(maxY, y + r);
+        maxZ = Math.max(maxZ, z + r);
+    }
+    if (minX > maxX) {
+        out.min.fill(0);
+        out.max.fill(0);
+        out.centre.fill(0);
+        out.radius = 0;
+        return;
+    }
+    /* A sum of weights other than one scales the box about the origin, by the least and the most. */
+    const [least, most] = skin.sums;
+    out.min[0] = Math.min(least * minX, most * minX);
+    out.min[1] = Math.min(least * minY, most * minY);
+    out.min[2] = Math.min(least * minZ, most * minZ);
+    out.max[0] = Math.max(least * maxX, most * maxX);
+    out.max[1] = Math.max(least * maxY, most * maxY);
+    out.max[2] = Math.max(least * maxZ, most * maxZ);
+    let radius2 = 0;
+    for (let axis = 0; axis < 3; axis++) {
+        const centre = (out.min[axis] + out.max[axis]) / 2;
+        out.centre[axis] = centre;
+        const half = out.max[axis] - centre;
+        radius2 += half * half;
+    }
+    out.radius = Math.sqrt(radius2);
+}
+/** The squared length of one column's first three components. */
+function columnLength2(m, at) {
+    const x = m[at];
+    const y = m[at + 1];
+    const z = m[at + 2];
+    return x * x + y * y + z * z;
+}
+/** Refuse a pose that hands over fewer joints than the skin names. */
+export function validatePose(matrices, skin) {
+    if (matrices.length % 16 !== 0 || matrices.length / 16 < skin.joints) {
+        throw new Error(`point skin: a pose of ${matrices.length / 16} joints for a skin that names ${skin.joints}`);
+    }
+}

package/dist/render/rendererHarness.js

@@ -77,6 +77,12 @@ export function recordingGl(options = {}) {
         ONE: 1,
         ONE_MINUS_SRC_ALPHA: 0x0303,
         TRIANGLES: 0x0004,
+        /* Transform feedback's, so a point skin's pose can be seen to discard, capture and undo both. */
+        POINTS: 0x0000,
+        RASTERIZER_DISCARD: 0x8c89,
+        TRANSFORM_FEEDBACK: 0x8e22,
+        TRANSFORM_FEEDBACK_BUFFER: 0x8c8e,
+        SEPARATE_ATTRIBS: 0x8c8d,
         /* The winding a pass names, so a test can tell which one it chose. */
         CW: 0x0900,
         CCW: 0x0901,

package/dist/render/shader.d.ts

@@ -1,5 +1,7 @@
 /** Shader compilation with fail-fast diagnostics (init-time only, never per-frame). */
-export declare function compileProgram(gl: WebGL2RenderingContext, vertexSource: string, fragmentSource: string, label: string): WebGLProgram;
+export declare function compileProgram(gl: WebGL2RenderingContext, vertexSource: string, fragmentSource: string, label: string, 
+/** Vertex outputs captured by transform feedback, one buffer each; named before the link. */
+feedback?: readonly string[]): WebGLProgram;
 /**
  * A program compiled and linked without asking whether that worked, since asking waits for the
  * driver to finish: for a context offering `KHR_parallel_shader_compile`, whose

package/dist/render/shader.js

@@ -1,5 +1,7 @@
 /** Shader compilation with fail-fast diagnostics (init-time only, never per-frame). */
-export function compileProgram(gl, vertexSource, fragmentSource, label) {
+export function compileProgram(gl, vertexSource, fragmentSource, label, 
+/** Vertex outputs captured by transform feedback, one buffer each; named before the link. */
+feedback) {
     const vs = compileStage(gl, gl.VERTEX_SHADER, vertexSource, `${label}.vert`);
     const fs = compileStage(gl, gl.FRAGMENT_SHADER, fragmentSource, `${label}.frag`);
     const program = gl.createProgram();
@@ -7,6 +9,9 @@ export function compileProgram(gl, vertexSource, fragmentSource, label) {
         throw new Error(`[${label}] createProgram failed`);
     gl.attachShader(program, vs);
     gl.attachShader(program, fs);
+    if (feedback !== undefined) {
+        gl.transformFeedbackVaryings(program, feedback, gl.SEPARATE_ATTRIBS);
+    }
     gl.linkProgram(program);
     gl.deleteShader(vs);
     gl.deleteShader(fs);

package/dist/render/shaders/flat/detail.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A material's tiled detail over whatever its maps made: `SurfaceMaterial.detail`, packed into
+ * `uDetail` by `surfaceDetail.ts`.
+ *
+ * **Each texel wears its own region's detail alone.** The region is read exactly from the ORM
+ * array's layer the material names, at the base coordinates, so an index is never blended with its
+ * neighbour's at a region's edge; then that region's normal map is read at its repeat and offset,
+ * turned through a frame built on the normal the base maps made — the construction a layered
+ * material lays its layers over a mesh normal with — and its occlusion multiplied into the
+ * surface's. A strength scales the detail's slopes as a layer's look does.
+ *
+ * **Read with explicit gradients**, the base coordinates' times the region's repeat, because the
+ * region is the pixel's own: a read whose level is implicit is legal only in uniform control flow
+ * (AGENTS.md 2026-08-07), and across a region's edge the repeated coordinates jump, which would
+ * read a level as coarse as the jump. The frame and the gradients are taken first, under the
+ * uniform branch that calls this.
+ *
+ * **A lit switch, `SURFACE_DETAIL`**, off until a material first asks, declared after `LAYERED` and
+ * `LAYER_LOOKS` so each keeps its id. Compiled out, its thirty-three vectors are not declared.
+ */
+export declare function detailGlsl(on: boolean): string;

package/dist/render/shaders/flat/detail.js

@@ -0,0 +1,74 @@
+/**
+ * A material's tiled detail over whatever its maps made: `SurfaceMaterial.detail`, packed into
+ * `uDetail` by `surfaceDetail.ts`.
+ *
+ * **Each texel wears its own region's detail alone.** The region is read exactly from the ORM
+ * array's layer the material names, at the base coordinates, so an index is never blended with its
+ * neighbour's at a region's edge; then that region's normal map is read at its repeat and offset,
+ * turned through a frame built on the normal the base maps made — the construction a layered
+ * material lays its layers over a mesh normal with — and its occlusion multiplied into the
+ * surface's. A strength scales the detail's slopes as a layer's look does.
+ *
+ * **Read with explicit gradients**, the base coordinates' times the region's repeat, because the
+ * region is the pixel's own: a read whose level is implicit is legal only in uniform control flow
+ * (AGENTS.md 2026-08-07), and across a region's edge the repeated coordinates jump, which would
+ * read a level as coarse as the jump. The frame and the gradients are taken first, under the
+ * uniform branch that calls this.
+ *
+ * **A lit switch, `SURFACE_DETAIL`**, off until a material first asks, declared after `LAYERED` and
+ * `LAYER_LOOKS` so each keeps its id. Compiled out, its thirty-three vectors are not declared.
+ */
+export function detailGlsl(on) {
+    if (!on) {
+        return /* glsl */ `
+const bool SURFACE_DETAIL = false;  // wgsl:override
+bool detailed() { return false; }
+void surfaceDetail(inout vec3 n, inout float occlusion, vec2 uv) {}
+`;
+    }
+    return /* glsl */ `
+/* Whether this program lays a material's detail. Off but where one has asked: detail.ts. */
+const bool SURFACE_DETAIL = true;  // wgsl:override
+/*
+ * Thirty-three vectors, as surfaceDetail.ts packs them: the region count (x) and the ORM array's
+ * layer holding the region map, or -1 for none (y); then two a region, the normal map's layer (x),
+ * the occlusion's or -1 (y), the normal strength (z) and the occlusion strength (w); its repeats
+ * across and down (x y) and its offset (z w).
+ */
+uniform vec4 uDetail[33]; // wgsl:material
+
+bool detailed() { return uDetail[0].x > 0.0; }
+
+/* The region a texel of the base maps is in, read exactly, held to the regions there are. */
+int detailRegion(vec2 uv) {
+  int last = int(uDetail[0].x) - 1;
+  if (uDetail[0].y < 0.0) return 0;
+  ivec2 size = textureSize(uOrmMap, 0).xy;
+  ivec2 texel = clamp(ivec2(floor(fract(uv) * vec2(size))), ivec2(0), size - 1);
+  int region = int(texelFetch(uOrmMap, ivec3(texel, int(uDetail[0].y)), 0).r * 255.0 + 0.5);
+  return clamp(region, 0, last);
+}
+
+void surfaceDetail(inout vec3 n, inout float occlusion, vec2 uv) {
+  /* In uniform control flow, before anything that depends on the pixel's region. */
+  mat3 frame = tangentFrame(n, vWorldPos, uv, vTangent, vHasTangents);
+  vec2 dx = dFdx(uv);
+  vec2 dy = dFdy(uv);
+  int region = detailRegion(uv);
+  vec4 picks = uDetail[1 + region * 2];
+  vec4 place = uDetail[2 + region * 2];
+  vec2 at = uv * place.xy + place.zw;
+  vec2 gx = dx * place.xy;
+  vec2 gy = dy * place.xy;
+  vec3 d = textureGrad(uModelMap, vec3(at, picks.x), gx, gy).xyz * 2.0 - 1.0;
+  /* z rebuilt where none is stored, as the base map's is: normalMap.ts. */
+  d.z = d.z > 0.0 ? d.z : sqrt(max(0.0, 1.0 - dot(d.xy, d.xy)));
+  d = normalize(vec3(d.xy * picks.z, max(d.z, 1e-4)));
+  n = normalize(frame * d);
+  if (picks.y >= 0.0) {
+    float held = textureGrad(uModelMap, vec3(at, picks.y), gx, gy).r;
+    occlusion *= mix(1.0, held, picks.w);
+  }
+}
+`;
+}

package/dist/render/shaders/flat/glassTint.d.ts

@@ -8,7 +8,7 @@ export declare function glassTintGlsl(glassShadows: boolean): string;
  * The lit stage's switches, by the name of the constant each is: the decision both backends make
  * about which optional code a lit program carries. See `litSwitchesGlsl`.
  */
-export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS' | 'WORLD_UVS' | 'MOVING_SUN' | 'LAYERED' | 'LAYER_LOOKS';
+export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS' | 'WORLD_UVS' | 'MOVING_SUN' | 'LAYERED' | 'LAYER_LOOKS' | 'SURFACE_DETAIL';
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export declare function noLitSwitches(): Record<LitSwitch, boolean>;
 /** Which of the lit stage's optional features a build reads. See `litSwitchesGlsl`. */

package/dist/render/shaders/flat/glassTint.js

@@ -38,6 +38,7 @@ export function noLitSwitches() {
         MOVING_SUN: false,
         LAYERED: false,
         LAYER_LOOKS: false,
+        SURFACE_DETAIL: false,
     };
 }
 /**

package/dist/render/shaders/flat/index.d.ts

@@ -145,6 +145,11 @@ export interface FlatShaderOptions {
      * \`uLayerLooks\` and all. True when absent; nothing without \`layered\`. See \`layerLooksGlsl\`.
      */
     readonly layerLooks?: boolean;
+    /**
+     * Whether it lays a material's tiled detail over its maps, \`uDetail\` and all
+     * (\`SurfaceMaterial.detail\`). True when absent. See \`detailGlsl\`.
+     */
+    readonly surfaceDetail?: boolean;
     /**
      * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
      *

package/dist/render/shaders/flat/index.js

@@ -24,6 +24,7 @@ import { overlayGlsl } from './overlay.js';
 import { reflectionSurfaceGlsl } from './reflectionSurface.js';
 import { worldUvGlsl } from './worldUv.js';
 import { movingSunGlsl } from './movingSun.js';
+import { detailGlsl } from './detail.js';
 import { layeredGlsl } from './layered.js';
 import { MAP_READS_GLSL } from './mapReads.js';
 import { CHANNEL_BEND, LIT_CHANNEL_ATTRIBUTE } from '../vertexChannel.js';
@@ -514,6 +515,8 @@ export function flatFrag(options) {
         worldUvGlsl(options.worldUvs ?? true),
         /* After the projection, so its switch takes the next id; the normal map below calls it. */
         layeredGlsl(options.layered ?? true, options.layerLooks ?? true),
+        /* After the layers, so its switch takes the next id; main calls it. See detail.ts. */
+        detailGlsl(options.surfaceDetail ?? true),
         /* Where each map is read, after both of the ways it can be read otherwise. See mapReads.ts. */
         MAP_READS_GLSL,
         /* After the frame and the projection it calls, unconditional for the same reason as the