@driftengine/core 4.11.1 → 4.13.0

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

@@ -36,6 +36,8 @@ export class SkinScatterPass {
     layout;
     uniforms;
     staging = new Float32Array((SLOT * 2) / 4);
+    /** The same blocks' ints: the frame's grade, which the second axis applies. */
+    stagingInts = new Int32Array(this.staging.buffer);
     linear;
     nearest;
     commands = createCommandPool(16);
@@ -182,7 +184,9 @@ export class SkinScatterPass {
      * attachment its pass draws into, `resolve` where a multisampled one resolves, `samples` its
      * count. `projection` is the frame's, `height` the frame's height in pixels.
      */
-    spread(encoder, pipelines, depth, frame, resolve, samples, projection, inverseProjection, timestampWrites) {
+    spread(encoder, pipelines, depth, frame, resolve, samples, projection, inverseProjection, timestampWrites, 
+    /** The frame's grade, which the second axis applies to the light it adds. */
+    outputTransform = 0, outputExposure = 1) {
         const diffuse = this.diffuse;
         if (diffuse === null || this.diffuseView === null || this.acrossView === null)
             return;
@@ -193,7 +197,7 @@ export class SkinScatterPass {
             this.groupDown = this.group('skin.blurDown', this.acrossView, depth);
             this.groupsDepth = depth;
         }
-        this.writeUniforms(diffuse.width, diffuse.height, projection, inverseProjection);
+        this.writeUniforms(diffuse.width, diffuse.height, projection, inverseProjection, outputTransform, outputExposure);
         const across = postPipeline(pipelines, this.device, this.layout, 'skin.blurAcross', SKIN_BLUR_FRAG_WGSL, SKIN_TARGET_FORMAT);
         const down = postPipelineTargets(pipelines, this.device, this.layout, `skin.blurDown:${pipelines.format}:${samples}`, SKIN_BLUR_FRAG_WGSL, [
             {
@@ -261,7 +265,7 @@ export class SkinScatterPass {
         });
     }
     /** Both axes' blocks: the step along each, and what they share. Column-major matrices. */
-    writeUniforms(width, height, projection, inverse) {
+    writeUniforms(width, height, projection, inverse, outputTransform, outputExposure) {
         const f = this.staging;
         const fields = BINDINGS.fields;
         for (let axis = 0; axis < 2; axis += 1) {
@@ -280,6 +284,8 @@ export class SkinScatterPass {
             f.set(this.profiles, base + fields.uProfiles.offset / 4);
             /* The colour is applied once, on the axis that adds into the frame. */
             f[base + fields.uApplyAlbedo.offset / 4] = axis;
+            this.stagingInts[base + fields.uOutputTransform.offset / 4] = outputTransform;
+            f[base + fields.uOutputExposure.offset / 4] = outputExposure;
         }
         this.device.queue.writeBuffer(this.uniforms, 0, f);
     }

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

@@ -88,8 +88,18 @@ export declare const SKY_FIELDS: {
         readonly size: 4;
         readonly type: "float";
     };
+    readonly uOutputTransform: {
+        readonly offset: 224;
+        readonly size: 4;
+        readonly type: "int";
+    };
+    readonly uOutputExposure: {
+        readonly offset: 228;
+        readonly size: 4;
+        readonly type: "float";
+    };
 };
-export declare const SKY_UNIFORM_SIZE: 224;
+export declare const SKY_UNIFORM_SIZE: 240;
 export declare function createSkyBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
 export declare function createSkyBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, uniforms: GPUBuffer): GPUBindGroup;
 /**

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

@@ -11,7 +11,7 @@ import type { UniformFields } from './scatterPass.ts';
 export declare const WATER_VERT_FIELDS: UniformFields;
 export declare const WATER_VERT_SIZE: 208;
 export declare const WATER_FRAG_FIELDS: UniformFields;
-export declare const WATER_FRAG_SIZE: 1504;
+export declare const WATER_FRAG_SIZE: 1520;
 /** The two meshes and the numbers the grid decided, behind the surface's opaque handle. */
 export interface GpuWater {
     /** The ocean: near sheet and far skirt in one buffer. */

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

@@ -14,7 +14,7 @@ import type { PipelineCache } from './pipelineCache.ts';
 export declare const WIND_STREAK_VERT_FIELDS: UniformFields;
 export declare const WIND_STREAK_VERT_SIZE: 128;
 export declare const WIND_STREAK_FRAG_FIELDS: UniformFields;
-export declare const WIND_STREAK_FRAG_SIZE: 16;
+export declare const WIND_STREAK_FRAG_SIZE: 32;
 /** A lattice on the device, behind the surface's opaque handle. */
 export interface GpuWindStreaks {
     readonly corners: GPUBuffer;

package/dist/render/causticsRenderer.d.ts

@@ -60,6 +60,8 @@ export declare class CausticsRenderer {
      *
      * Answers whether it drew, which the renderer counts on its frame budget.
      */
-    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, directionalDir: Vec3, directionalColor: Vec3, ambient: Vec3, atmosphere: Atmosphere, underwaterEnabled: boolean, windX?: number, windZ?: number, strength?: number): boolean;
+    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, directionalDir: Vec3, directionalColor: Vec3, ambient: Vec3, atmosphere: Atmosphere, underwaterEnabled: boolean, windX?: number, windZ?: number, strength?: number, 
+    /** The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+    outputTransform?: number, outputExposure?: number): boolean;
     dispose(gl: WebGL2RenderingContext): void;
 }

package/dist/render/causticsRenderer.js

@@ -66,11 +66,15 @@ export class CausticsRenderer {
      *
      * Answers whether it drew, which the renderer counts on its frame budget.
      */
-    draw(gl, camera, timeSeconds, directionalDir, directionalColor, ambient, atmosphere, underwaterEnabled, windX = 0, windZ = 0, strength = 1) {
+    draw(gl, camera, timeSeconds, directionalDir, directionalColor, ambient, atmosphere, underwaterEnabled, windX = 0, windZ = 0, strength = 1, 
+    /** The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+    outputTransform = 0, outputExposure = 1) {
         if (this.vertexCount === 0)
             return false;
         const u = this.uniforms;
         gl.useProgram(this.program);
+        gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
+        gl.uniform1f(u['uOutputExposure'] ?? null, outputExposure);
         gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, camera.viewProjection);
         gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
         gl.uniform1f(u['uTime'] ?? null, timeSeconds);

package/dist/render/decalPass.d.ts

@@ -29,6 +29,8 @@ export declare class DecalPass {
      * turns a stored depth back into the clip space that matrix was built in, and pairing it with
      * the corrected one applies the remap twice. `lightVolumeDraw.ts` carries that derivation.
      */
-    drawDecals(queue: DecalQueue, depth: WebGLTexture, viewProjection: ReadonlyMat4, eye: ArrayLike<number>, width: number, height: number): void;
+    drawDecals(queue: DecalQueue, depth: WebGLTexture, viewProjection: ReadonlyMat4, eye: ArrayLike<number>, width: number, height: number, 
+    /** The renderer's `passGrade`: how the frame under the marks was graded, 0 for not yet. */
+    outputTransform?: number): void;
     dispose(): void;
 }

package/dist/render/decalPass.js

@@ -42,7 +42,9 @@ export class DecalPass {
      * turns a stored depth back into the clip space that matrix was built in, and pairing it with
      * the corrected one applies the remap twice. `lightVolumeDraw.ts` carries that derivation.
      */
-    drawDecals(queue, depth, viewProjection, eye, width, height) {
+    drawDecals(queue, depth, viewProjection, eye, width, height, 
+    /** The renderer's `passGrade`: how the frame under the marks was graded, 0 for not yet. */
+    outputTransform = 0) {
         if (queue.length === 0)
             return;
         const { gl } = this;
@@ -50,6 +52,7 @@ export class DecalPass {
         mat4.invert(this.depthToWorld, viewProjection);
         mat4.multiply(this.depthToWorld, this.depthToWorld, DEPTH_01_TO_CLIP);
         gl.useProgram(this.program);
+        gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
         gl.bindVertexArray(this.vao);
         gl.disable(gl.DEPTH_TEST);
         gl.depthMask(false);

package/dist/render/flockRenderer.d.ts

@@ -32,6 +32,6 @@ export declare class FlockRenderer {
     private readonly buffers;
     private readonly vertexCount;
     constructor(gl: WebGL2RenderingContext, count: number);
-    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, params: FlockParams, tint: Vec3, windX?: number, windZ?: number): void;
+    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, params: FlockParams, tint: Vec3, windX?: number, windZ?: number, outputTransform?: number, outputExposure?: number): void;
     dispose(gl: WebGL2RenderingContext): void;
 }

package/dist/render/flockRenderer.js

@@ -34,9 +34,12 @@ export class FlockRenderer {
         attach(indices, 2, 1);
         gl.bindVertexArray(null);
     }
-    draw(gl, camera, timeSeconds, params, tint, windX = 0, windZ = 0) {
+    draw(gl, camera, timeSeconds, params, tint, windX = 0, windZ = 0, outputTransform = 0, outputExposure = 1) {
         const u = this.uniforms;
         gl.useProgram(this.program);
+        /* The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+        gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
+        gl.uniform1f(u['uOutputExposure'] ?? null, outputExposure);
         gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, camera.viewProjection);
         /*
          * No `uCameraPos` here, and the shader no longer declares one. It fed the banking that

package/dist/render/globalMediumPass.d.ts

@@ -97,6 +97,8 @@ export declare class GlobalMediumPass {
      * `(ONE, SRC_ALPHA)` on colour is `dst * transmittance + inscatter`; alpha is left alone with
      * `(ZERO, ONE)`, because the frame's own alpha is not the medium's to spend.
      */
-    compositeMedium(depth: WebGLTexture, frameWidth: number, frameHeight: number): void;
+    compositeMedium(depth: WebGLTexture, frameWidth: number, frameHeight: number, 
+    /** The renderer's `passGrade`: how the frame under the medium was graded. */
+    outputTransform?: number, outputExposure?: number): void;
     dispose(): void;
 }

package/dist/render/globalMediumPass.js

@@ -192,7 +192,9 @@ export class GlobalMediumPass {
      * `(ONE, SRC_ALPHA)` on colour is `dst * transmittance + inscatter`; alpha is left alone with
      * `(ZERO, ONE)`, because the frame's own alpha is not the medium's to spend.
      */
-    compositeMedium(depth, frameWidth, frameHeight) {
+    compositeMedium(depth, frameWidth, frameHeight, 
+    /** The renderer's `passGrade`: how the frame under the medium was graded. */
+    outputTransform = 0, outputExposure = 1) {
         if (this.target === null || this.unavailable)
             return;
         const { gl } = this;
@@ -215,6 +217,8 @@ export class GlobalMediumPass {
         this.mediumTexel[1] = 1 / Math.max(1, this.height);
         gl.uniform2fv(u['uMediumTexel'] ?? null, this.mediumTexel);
         gl.uniform4fv(u['uDepthToViewZ'] ?? null, this.depthToViewZ);
+        gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
+        gl.uniform1f(u['uOutputExposure'] ?? null, outputExposure);
         gl.drawArrays(gl.TRIANGLES, 0, 3);
         gl.bindVertexArray(null);
         gl.activeTexture(gl.TEXTURE1);

package/dist/render/gradeColor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The forward grade on the CPU: what `applyOutputTransform` in `shaders/outputTransform.ts` does to
+ * a colour, for a colour no shader draws — a clear colour, written to a target before any pass runs.
+ *
+ * **Why a clear colour is graded at all.** Every pass grades what it draws when nothing after it
+ * will, so a colour handed to the renderer means one thing wherever it lands: linear light. A clear
+ * left as it was given is the one colour in the frame read as a display value, so a scene whose fog
+ * fades to its background colour fades to a different colour than the background it meets; with
+ * `hdrScene` the resolve grades the clear with everything else, and a frame without it has to agree.
+ *
+ * **A second copy of the curve, and what holds the two together** is the hand-derived values in
+ * `gradeColor.test.ts`, the same ones the shader's own constants give: the sRGB encode's two
+ * segments, the ACES fit through its two matrices, and the highlight shoulder. Code 4, the filmic
+ * curve, is the composite's alone, so a forward code never carries it (`forwardTransformCode`).
+ */
+import type { Vec3 } from '../math/color.ts';
+/**
+ * `color` graded by forward code `code` at `exposure` into `out`, which may be `color`: 0 leaves it
+ * as it is, 1 encodes it as sRGB, 2 runs ACES first and 3 the highlight shoulder. Allocates nothing.
+ */
+export declare function gradeColorInto(code: number, exposure: number, color: Readonly<Vec3>, out: Vec3): Vec3;

package/dist/render/gradeColor.js

@@ -0,0 +1,64 @@
+/* Columns as the shader's `mat3` reads them, written here as rows of the product. */
+const IN_R = [0.59719, 0.35458, 0.04823];
+const IN_G = [0.076, 0.90834, 0.01566];
+const IN_B = [0.0284, 0.13383, 0.83777];
+const OUT_R = [1.60475, -0.53108, -0.07367];
+const OUT_G = [-0.10208, 1.10813, -0.00605];
+const OUT_B = [-0.00327, -0.07276, 1.07602];
+/**
+ * `color` graded by forward code `code` at `exposure` into `out`, which may be `color`: 0 leaves it
+ * as it is, 1 encodes it as sRGB, 2 runs ACES first and 3 the highlight shoulder. Allocates nothing.
+ */
+export function gradeColorInto(code, exposure, color, out) {
+    let r = color[0];
+    let g = color[1];
+    let b = color[2];
+    if (code === 0) {
+        out[0] = r;
+        out[1] = g;
+        out[2] = b;
+        return out;
+    }
+    if (code === 2) {
+        const x = r * exposure;
+        const y = g * exposure;
+        const z = b * exposure;
+        const ir = fit(dot(IN_R, x, y, z));
+        const ig = fit(dot(IN_G, x, y, z));
+        const ib = fit(dot(IN_B, x, y, z));
+        r = clamp01(dot(OUT_R, ir, ig, ib));
+        g = clamp01(dot(OUT_G, ir, ig, ib));
+        b = clamp01(dot(OUT_B, ir, ig, ib));
+    }
+    else if (code === 3) {
+        r *= exposure;
+        g *= exposure;
+        b *= exposure;
+        const m = Math.max(r, g, b);
+        if (m > 0.8) {
+            const e = m - 0.8;
+            const k = (0.8 + (0.2 * e) / (e + 0.2)) / m;
+            r *= k;
+            g *= k;
+            b *= k;
+        }
+    }
+    out[0] = encode(r);
+    out[1] = encode(g);
+    out[2] = encode(b);
+    return out;
+}
+function dot(row, x, y, z) {
+    return row[0] * x + row[1] * y + row[2] * z;
+}
+/** The RRT and ODT fit, `rrtAndOdtFit` in the shader. */
+function fit(v) {
+    return (v * (v + 0.0245786) - 0.000090537) / (v * (0.983729 * v + 0.432951) + 0.238081);
+}
+/** Linear to sRGB, the piecewise form the shader uses. */
+function encode(c) {
+    return c <= 0.0031308 ? c * 12.92 : 1.055 * Math.max(c, 0) ** (1 / 2.4) - 0.055;
+}
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}

package/dist/render/lightMatrix.d.ts

@@ -1,6 +1,19 @@
 import { mat4 } from 'gl-matrix';
 import type { Vec3 } from '../math/color.ts';
 export declare function computeLightMatrix(lightDir: Vec3, focusX: number, focusY: number, focusZ: number, radius: number, shadowMapSize: number, out: mat4): number;
+/**
+ * A directional light's matrix covering a box of known size whole: a model, a level, a room. The
+ * sphere around the box, at its centre, through `computeLightMatrix`, widened by the half texel the
+ * centre's snap may move it so a corner on the sphere stays inside. Returns the depth span, as that
+ * does.
+ *
+ * **For a scene whose extent is known rather than one that follows a viewer.** A radius chosen by
+ * eye around a guessed centre leaves part of the model outside the map, where it casts nothing; the
+ * bounds are the answer, and a loader has them. **What it gives up** is resolution where the box is
+ * large: the map's texels are spread over all of it, so a building's shadows are coarser than a
+ * focus on the viewer would draw them, which is what `computeLightMatrix` around the viewer is for.
+ */
+export declare function computeLightMatrixForBounds(lightDir: Vec3, min: Readonly<Vec3>, max: Readonly<Vec3>, shadowMapSize: number, out: mat4): number;
 /**
  * The depth an orthographic light matrix spans, in metres: what `computeLightMatrix` returns, read
  * back off any such matrix. Its depth row is the light's axis scaled by two over the span, so the

package/dist/render/lightMatrix.js

@@ -43,6 +43,23 @@ export function computeLightMatrix(lightDir, focusX, focusY, focusZ, radius, sha
     // to express its residual depth tolerance in stable world-space metres.
     return radius * 6;
 }
+/**
+ * A directional light's matrix covering a box of known size whole: a model, a level, a room. The
+ * sphere around the box, at its centre, through `computeLightMatrix`, widened by the half texel the
+ * centre's snap may move it so a corner on the sphere stays inside. Returns the depth span, as that
+ * does.
+ *
+ * **For a scene whose extent is known rather than one that follows a viewer.** A radius chosen by
+ * eye around a guessed centre leaves part of the model outside the map, where it casts nothing; the
+ * bounds are the answer, and a loader has them. **What it gives up** is resolution where the box is
+ * large: the map's texels are spread over all of it, so a building's shadows are coarser than a
+ * focus on the viewer would draw them, which is what `computeLightMatrix` around the viewer is for.
+ */
+export function computeLightMatrixForBounds(lightDir, min, max, shadowMapSize, out) {
+    const half = Math.hypot(max[0] - min[0], max[1] - min[1], max[2] - min[2]) / 2;
+    const radius = Math.max(half, 1e-3) * (1 + 2 / Math.max(shadowMapSize, 1));
+    return computeLightMatrix(lightDir, (min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2, radius, shadowMapSize, out);
+}
 /**
  * The depth an orthographic light matrix spans, in metres: what `computeLightMatrix` returns, read
  * back off any such matrix. Its depth row is the light's axis scaled by two over the span, so the

package/dist/render/passGrade.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The `uOutputTransform` a pass uploads: `storing` inside a probe's face or a capture, `presented`
+ * once the frame's resolve has run, `resolveGrades` where that resolve applies the transform.
+ */
+export declare function passGradeCode(storing: boolean, presented: boolean, resolveGrades: boolean, outputTransform: string): number;
+/** The `uOutputExposure` beside it: the frame's exposure wherever the pass grades, else one. */
+export declare function passGradeExposure(storing: boolean, presented: boolean, resolveGrades: boolean, exposure: number): number;
+/**
+ * The code an interface draws with, given the pass's: the screen encode wherever the pass grades at
+ * all, and nothing where it does not. Never a curve, so never an exposure either: a screen-space
+ * caption, a panel or a 2D layer keeps the colour it was picked as whatever the scene is graded by.
+ */
+export declare function interfaceGrade(passCode: number): number;

package/dist/render/passGrade.js

@@ -0,0 +1,47 @@
+/**
+ * Which grade a pass applies to what it draws, decided once for both backends.
+ *
+ * **Every pass grades where nothing after it will**, so a colour handed to the renderer means linear
+ * light wherever it lands. Three facts decide where that is:
+ *
+ * - **A probe's face or a capture stores radiance** for something else to light with or to show, so
+ *   it is never graded. The frame grades what it reads of one; graded at the bake as well, the curve
+ *   would be applied twice.
+ * - **A frame whose resolve grades** (`hdrScene` over a scene target) leaves every pass before the
+ *   resolve linear, because grading early throws away the range the float target exists to keep.
+ * - **Past the present, a pass lands on the canvas the resolve has already written**, so nothing
+ *   after it will grade it and it grades itself with the frame's forward code, composite or not. An
+ *   interface drawn after `endFrame` escapes the screen-space chain; it does not escape the grade.
+ *
+ * **An interface takes the screen encode and not the curve** (`interfaceGrade`). A tone curve and
+ * an exposure are how a scene's light is brought to the screen, and a caption or a panel is not
+ * light: its colour was picked for the screen, so it is encoded wherever the frame is and comes out
+ * as picked under every transform, at every exposure. What it gives up is an interface drawn inside
+ * a frame whose resolve grades (`hdrScene`): that one is part of the picture the resolve tone maps,
+ * and is drawn after `endFrame` to stay out of it. What would make any of this wrong is a composite
+ * step running after the present, which none does.
+ */
+import { forwardTransformCode } from './vertexDefaults.js';
+/**
+ * The `uOutputTransform` a pass uploads: `storing` inside a probe's face or a capture, `presented`
+ * once the frame's resolve has run, `resolveGrades` where that resolve applies the transform.
+ */
+export function passGradeCode(storing, presented, resolveGrades, outputTransform) {
+    if (storing)
+        return 0;
+    return presented || !resolveGrades ? forwardTransformCode(outputTransform) : 0;
+}
+/** The `uOutputExposure` beside it: the frame's exposure wherever the pass grades, else one. */
+export function passGradeExposure(storing, presented, resolveGrades, exposure) {
+    if (storing)
+        return 1;
+    return presented || !resolveGrades ? exposure : 1;
+}
+/**
+ * The code an interface draws with, given the pass's: the screen encode wherever the pass grades at
+ * all, and nothing where it does not. Never a curve, so never an exposure either: a screen-space
+ * caption, a panel or a 2D layer keeps the colour it was picked as whatever the scene is graded by.
+ */
+export function interfaceGrade(passCode) {
+    return passCode === 0 ? 0 : 1;
+}

package/dist/render/plumeRenderer.d.ts

@@ -89,7 +89,7 @@ export declare class PlumeRenderer {
      * the sky at depth 1.0 under LEQUAL would otherwise overwrite anything drawn
      * against open background.
      */
-    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, atmosphere: Atmosphere, underwaterEnabled: boolean, atmosphereCameraY: number, clipPlane: Float32Array | null, windX?: number, windZ?: number, originX?: number, originY?: number, originZ?: number): void;
+    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, atmosphere: Atmosphere, underwaterEnabled: boolean, atmosphereCameraY: number, clipPlane: Float32Array | null, windX?: number, windZ?: number, originX?: number, originY?: number, originZ?: number, outputTransform?: number, outputExposure?: number): void;
     dispose(gl: WebGL2RenderingContext): void;
     /** Uploads one attribute and returns its buffer, for the rare one a caller can change. */
     private attach;

package/dist/render/plumeRenderer.js

@@ -93,7 +93,7 @@ export class PlumeRenderer {
      * the sky at depth 1.0 under LEQUAL would otherwise overwrite anything drawn
      * against open background.
      */
-    draw(gl, camera, timeSeconds, atmosphere, underwaterEnabled, atmosphereCameraY, clipPlane, windX = 0, windZ = 0, originX = 0, originY = 0, originZ = 0) {
+    draw(gl, camera, timeSeconds, atmosphere, underwaterEnabled, atmosphereCameraY, clipPlane, windX = 0, windZ = 0, originX = 0, originY = 0, originZ = 0, outputTransform = 0, outputExposure = 1) {
         if (this.indexCount === 0)
             return;
         const u = this.uniforms;
@@ -121,6 +121,9 @@ export class PlumeRenderer {
         gl.uniform1i(u['uClipEnabled'] ?? null, clipPlane === null ? 0 : 1);
         if (clipPlane !== null)
             gl.uniform4fv(u['uClipPlane'] ?? null, clipPlane);
+        /* The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+        gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
+        gl.uniform1f(u['uOutputExposure'] ?? null, outputExposure);
         bindAtmosphere(gl, u, atmosphere, atmosphereCameraY, underwaterEnabled);
         gl.enable(gl.BLEND);
         if (this.blend === 'additive')

package/dist/render/renderQuality.d.ts

@@ -50,22 +50,35 @@ export type GlassShadows = 'full' | 'half' | 'off';
 export type SkinScattering = 'pre-integrated' | 'screen-space';
 export interface RenderQuality {
     /**
-     * The transfer curve applied at the end of every shaded pass.
-     *
-     * Construction-time, like every other quality control here, and `none` by default so
-     * no existing world changes by a single bit.
-     *
-     * **The symptom, written down because nobody searches for a transfer curve they do not know
-     * exists.** With `none`, values above 1 clip flat rather than rolling off, so a scene with
-     * bright sources against dark surroundings reads as crushed and desaturated: the highlights
-     * go to a hard white with no colour left in them and the midtones look muddy. That is
-     * reported by eye as "dark", "flat" or "not vivid", which sounds like a lighting problem, so
-     * that is where people look. A consumer built, tuned and shipped six worlds before anybody
-     * said the word. If a scene looks like that, try `outputTransform: 'aces'` with an
-     * `outputExposure` before touching a single light.
-     *
-     * The default stays `none`, and that is not the fault: a curve that changed every existing
-     * consumer's output would be far worse than one nobody found.
+     * The transfer curve applied at the end of every shaded pass. Construction-time, like every
+     * other quality control here.
+     *
+     * **`srgb` by default since 4.13.0, the encoding a display expects**: the light the renderer
+     * computes is linear, and a texture's colours are decoded to linear when they are read, so a
+     * frame written without encoding them back is a frame of linear values read as display values —
+     * every midtone far too dark. It is the encoding most renderers apply by default, so a model
+     * drawn here with no options reads as it does elsewhere. **What it gives up** is a highlight's
+     * colour: above 1 each channel clips on its own, so a bright saturated source goes to white
+     * rather than rolling off, which a curve with a shoulder (`aces`, `shoulder`) is for.
+     *
+     * **`none` was the default until 4.13.0, and it is the frame that reads as dark**: values
+     * written as they are computed, which is right only for a world whose colours were chosen by
+     * eye as display values and lit to match. It was reported by eye as "dark", "flat" or "not
+     * vivid", which sounds like a lighting problem, so that is where people looked; a consumer
+     * built, tuned and shipped six worlds under it before anybody said the word, and a model drawn
+     * from the manual came out darker than in any other engine. A world graded under it says
+     * `outputTransform: 'none'` and draws exactly as it did. **What would make `srgb` the wrong
+     * default** is a renderer whose colours are not linear, which this one's are not.
+     *
+     * **Every pass applies it where nothing after it will**, and the clear colour with them, so a
+     * colour handed to the renderer is linear wherever it lands: a frame with `hdrScene` is graded
+     * once at the resolve, and one without it is graded pass by pass to the same curve. A colour
+     * picked by eye is a display value, so it is stated through `srgbColor` (or a mesh built with
+     * `colorSpace: 'srgb'`), which gives back exactly the colour picked where a surface is lit at 1
+     * under `srgb`, and through the curve under a tone curve. **An interface** (screen text, a panel,
+     * the 2D layer) takes the screen encode and never the curve or the exposure, so its colours come
+     * out as picked under every transform; inside an `hdrScene` frame it is part of the picture the
+     * resolve grades, and is drawn after `endFrame` to stay out of the curve.
      */
     readonly outputTransform: OutputTransform;
     /**
@@ -259,9 +272,35 @@ export interface RenderQuality {
      * at a shadow's edge — that is what the blur is for.
      */
     readonly skinScattering: SkinScattering;
-    /** Horizontal world-space reach over which a directional shadow dissolves. */
+    /**
+     * How far a sun shadow may reach along the ground from its caster, in metres, before it
+     * dissolves. **Not a distance from the camera**: a shadow's own length, from where it leaves its
+     * caster to where it lands, fading from 35% of this to all of it.
+     *
+     * **1,000 since 4.13.0, so no building's shadow dissolves**: the fade starts at 350 m, past any
+     * wall, tower or canyon a shadow map covers at a useful resolution, so what bounds a shadow is
+     * its map, whose edge already fades. **What it gives up** is a way to hide a long shadow's
+     * stair-stepping at a low sun, which is what a short reach was for. It was 6 until 4.13.0: a
+     * tuning for short casters, which left a building's walls and arcades casting nothing on its
+     * floor under a high sun — the shadows vanished silently and read as random lighting. **What
+     * would make it wrong** is a scene whose shadows are too coarse to show at their full length;
+     * there a reach of the length that looks right is the setting, and the map around the viewer
+     * (`computeLightMatrix`) the better fix.
+     */
     readonly directionalShadowMaxDistance: number;
-    /** Maximum horizontal projection per vertical metre before low-angle shadows vanish. */
+    /**
+     * How low the sun may stand before its shadows fade, as the ground a metre of height may shadow:
+     * the sun's horizontal reach per vertical metre, so 1 is 45° of elevation and 60 about 1°. Every
+     * sun shadow fades from 65% of this to all of it.
+     *
+     * **60 since 4.13.0: shadows hold until the sun is about a degree above the horizon**, the
+     * stretch of a day when they are longest and most worth seeing. **What it gives up**: a sun on
+     * the horizon throws shadows kilometres long that a map can hold only as stripes, and the
+     * last degree is where they fade rather than show. It was 3 until 4.13.0, which dropped every
+     * sun shadow below about 18° — an evening without shadows. **What would make it wrong** is a
+     * scene whose low sun streaks; a smaller number here is the setting, at the cost of the
+     * shadows going earlier in the evening.
+     */
     readonly directionalShadowMaxSlope: number;
     /**
      * Metres a point light may drift from where its shadow was baked before re-baking.

package/dist/render/renderQuality.js

@@ -17,7 +17,7 @@ export const DIRECTIONAL_SHADOW_FADE_START = 0.65;
  * six times, while the directional map spends all of it on one focused area.
  */
 export const DEFAULT_RENDER_QUALITY = Object.freeze({
-    outputTransform: 'none',
+    outputTransform: 'srgb',
     outputExposure: 1,
     pointLightFalloff: 'smooth',
     /**
@@ -65,8 +65,8 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
     glassShadows: 'full',
     pipelineCompile: 'wait',
     skinScattering: 'pre-integrated',
-    directionalShadowMaxDistance: 6,
-    directionalShadowMaxSlope: 3,
+    directionalShadowMaxDistance: 1000,
+    directionalShadowMaxSlope: 60,
     pointShadowRebakeDistance: 0.001,
     pointShadowFacesPerFrame: 2,
     /*

package/dist/render/sceneTarget.d.ts

@@ -303,6 +303,8 @@ export declare class SceneTarget {
         readonly transform: number;
         readonly exposure: number;
         readonly film?: Float32Array;
+        /** Whether the forward passes graded the scene because this resolve does not. */
+        readonly sceneGraded?: boolean;
     }, motion?: {
         readonly reprojection: Float32Array;
         readonly strength: number;

package/dist/render/sceneTarget.js

@@ -819,6 +819,7 @@ export class SceneTarget {
         gl.uniform1f(this.uniforms['uReach'] ?? null, reachUv);
         gl.uniform1i(this.uniforms['uOutputTransform'] ?? null, grade.transform);
         gl.uniform1f(this.uniforms['uOutputExposure'] ?? null, grade.exposure);
+        gl.uniform1i(this.uniforms['uSceneGraded'] ?? null, grade.sceneGraded === true ? 1 : 0);
         if (grade.film !== undefined) {
             gl.uniform4fv(this.uniforms['uFilmA'] ?? null, grade.film, 0, 4);
             gl.uniform4fv(this.uniforms['uFilmB'] ?? null, grade.film, 4, 4);

package/dist/render/sdfTextRenderer.d.ts

@@ -65,7 +65,7 @@ export declare class SdfTextRenderer {
      */
     /**
      * `outputTransform` and `outputExposure` come from the renderer rather than from here, because
-     * whether this pass grades depends on whether anything after it will. See `Renderer.gradeCode`.
+     * whether this pass grades depends on whether anything after it will. See `passGrade.ts`.
      */
     draw(viewProj: ReadonlyMat4, model: Float32Array, color: Vec3, opacity: number, outputTransform: number, outputExposure: number): boolean;
     dispose(): void;

package/dist/render/sdfTextRenderer.js

@@ -103,7 +103,7 @@ export class SdfTextRenderer {
      */
     /**
      * `outputTransform` and `outputExposure` come from the renderer rather than from here, because
-     * whether this pass grades depends on whether anything after it will. See `Renderer.gradeCode`.
+     * whether this pass grades depends on whether anything after it will. See `passGrade.ts`.
      */
     draw(viewProj, model, color, opacity, outputTransform, outputExposure) {
         if (this.layout.quadCount === 0 || opacity <= 0 || this.font === null || this.atlas === null) {