@driftengine/core 4.12.0 → 4.13.0

package/src/geometry/meshBuilder.ts

@@ -1,6 +1,7 @@
 import { GrowableF32, GrowableU32 } from './growable.ts';
 import type { MeshData } from '../render/mesh.ts';
 import type { Vec3 } from '../math/color.ts';
+import { decodeSrgbInPlace } from '../math/color.ts';
 
 /**
  * The emissive colour of a vertex that has not been given one: negative, which no real
@@ -23,6 +24,16 @@ export interface MeshBuildOptions {
    * sample them. On, for a mesh that will be drawn with a `SurfaceTexture`.
    */
   planarUvs?: boolean;
+  /**
+   * The space the builder's colours were given in. `'linear'`, the default, is the renderer's own:
+   * light as a surface reflects it. `'srgb'` is a colour picked by eye, on a screen or in a paint
+   * program, and decodes every vertex's colour and emissive colour to linear here, once — as a
+   * texture of colours uploaded as sRGB is decoded — so a world built from hand-picked colours draws
+   * them as picked under the default `outputTransform`, where the same numbers taken as linear come
+   * out pale. What it gives up: nothing at the colour picked; a colour meant as light rather than as
+   * a look wants a linear number of its own.
+   */
+  colorSpace?: 'linear' | 'srgb';
 }
 
 /**
@@ -1083,14 +1094,22 @@ export class MeshBuilder {
     /* Same promise as `specular`: a mesh nothing bound uploads no skinning buffers, and
        `MeshData` requires both arrays or neither. */
     const skinned = this.anyJoint;
+    /* Colours picked by eye, decoded once here: see `MeshBuildOptions.colorSpace`. */
+    const picked = options.colorSpace === 'srgb';
     return {
       positions: this.positions.toTyped(),
       normals: this.normals.toTyped(),
-      colors: this.colors.toTyped(),
+      colors: picked ? decodeSrgbInPlace(this.colors.toTyped()) : this.colors.toTyped(),
       emissive: this.emissive.toTyped(),
       ...(shines ? { specular: this.specular.toTyped() } : {}),
       ...(textured ? { relief: this.relief.toTyped() } : {}),
-      ...(tinted ? { emissiveColor: this.emissiveColor.toTyped() } : {}),
+      ...(tinted
+        ? {
+            emissiveColor: picked
+              ? decodeSrgbInPlace(this.emissiveColor.toTyped())
+              : this.emissiveColor.toTyped(),
+          }
+        : {}),
       ...(rough ? { roughness: this.roughness.toTyped() } : {}),
       ...(mineral ? { grain: this.grain.toTyped() } : {}),
       ...(skinned ? { joints: this.expandedJoints(), weights: this.expandedWeights() } : {}),

package/src/index.ts

@@ -96,7 +96,15 @@ export {
   wrapAngle,
   lerpAngle,
 } from './math/scalar.ts';
-export { hslToRgb, mixColor, mixColorInto, scaleColor } from './math/color.ts';
+export {
+  decodeSrgbInPlace,
+  hslToRgb,
+  mixColor,
+  mixColorInto,
+  scaleColor,
+  srgbColor,
+  srgbToLinear,
+} from './math/color.ts';
 export type { Vec3 } from './math/color.ts';
 
 export { Camera } from './render/camera.ts';
@@ -707,7 +715,7 @@ export type { LightGrid } from './render/lightGrid.ts';
 export type { PointLightBuffer, PointLightSource } from './render/pointLightSelection.ts';
 export { createFlame, flameFrequencyHz, updateFlame } from './render/flameLight.ts';
 export type { Flame, FlameOptions } from './render/flameLight.ts';
-export { computeLightMatrix } from './render/lightMatrix.ts';
+export { computeLightMatrix, computeLightMatrixForBounds } from './render/lightMatrix.ts';
 export { PlumeRenderer } from './render/plumeRenderer.ts';
 export { createEnvironment } from './render/backend/webgl2/renderer.ts';
 export type { InsetRect } from './render/backend/webgl2/renderer.ts';
@@ -750,6 +758,7 @@ export type { ShellStation, ShellFillOptions } from './geometry/shellFill.ts';
  * this line the only way for it to comply was to copy, which is what the rule forbids.
  */
 export { OUTPUT_TRANSFORM_GLSL } from './render/shaders/outputTransform.ts';
+export { interfaceGrade } from './render/passGrade.ts';
 export { PLUME_VERT, FIRE_FRAG } from './render/shaders/fire.ts';
 export { ARCANE_FRAG } from './render/shaders/arcane.ts';
 export { SMOKE_FRAG } from './render/shaders/smoke.ts';

package/src/math/color.ts

@@ -35,3 +35,42 @@ export function mixColorInto(out: Vec3, a: Vec3, b: Vec3, t: number): void {
 export function scaleColor(color: Vec3, factor: number): Vec3 {
   return [color[0] * factor, color[1] * factor, color[2] * factor];
 }
+
+/**
+ * A colour picked by eye — on a screen, in a paint program, as a CSS colour — as the linear value
+ * the renderer lights, blends, fogs and grades: each channel through the sRGB curve, which the
+ * default `outputTransform`, `'srgb'`, applies the other way at the end, so a colour drawn as it is,
+ * a sky, a clear or a surface lit at exactly 1, comes out as the colour picked.
+ *
+ * **Why a colour needs it**: everything the renderer draws is linear and encoded at the end, so a
+ * colour typed as it looks comes out too light — a brown picked as `(0.55, 0.3, 0.15)` draws as
+ * tan. **What it gives up**: nothing at the colour picked. **What would make it wrong** is a number
+ * that is an amount rather than a look: a light's intensity, a multiplier, a strength, which are
+ * linear already. Allocates, so it is for building a world rather than for a frame.
+ */
+export function srgbColor(r: number, g: number, b: number): Vec3 {
+  return [srgbToLinear(r), srgbToLinear(g), srgbToLinear(b)];
+}
+
+/**
+ * Every value of `values` decoded from sRGB in place, but a negative one, which is a sentinel and
+ * not a colour (`MeshBuilder`'s emissive colour left to the albedo). For whole arrays of colours
+ * picked by eye; see `MeshBuildOptions.colorSpace`.
+ */
+export function decodeSrgbInPlace(values: Float32Array): Float32Array {
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i] as number;
+    if (value >= 0) values[i] = srgbToLinear(value);
+  }
+  return values;
+}
+
+/**
+ * One channel, 0 to 1, through the sRGB decode: the straight segment below 0.04045. For a colour
+ * that arrives as numbers per channel rather than as a triple, a packed hex token being the usual
+ * one; allocates nothing.
+ */
+export function srgbToLinear(value: number): number {
+  // determinism: build-time — a colour for drawing, which no tick reads
+  return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}

package/src/render/backend/webgl2/renderer.ts

@@ -340,7 +340,9 @@ import {
   RUSH_REACH_UV,
   clampMotionShare,
 } from '../../vertexDefaults.ts';
-import { OUTPUT_TRANSFORM_CODE, forwardTransformCode } from '../../vertexDefaults.ts';
+import { OUTPUT_TRANSFORM_CODE } from '../../vertexDefaults.ts';
+import { gradeColorInto } from '../../gradeColor.ts';
+import { interfaceGrade, passGradeCode, passGradeExposure } from '../../passGrade.ts';
 import type { DisplayRange } from '../../displayRange.ts';
 import {
   DEFAULT_FILMIC_CURVE,
@@ -1798,6 +1800,8 @@ export class WebGL2Renderer implements RendererApi {
   private warnedOverlayBlocks = false;
   /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
   private probePassActive = false;
+  /** `clearOf`'s scratch: a clear colour as the open target takes it. */
+  private readonly gradedClear: Vec3 = [0, 0, 0];
   /**
    * Whether a scene capture is being drawn (`captureScene`): an off-screen pass like a bake, so the
    * frame's own view, its refraction copy and skin's spread are left alone, but lit as the frame is.
@@ -2563,8 +2567,8 @@ export class WebGL2Renderer implements RendererApi {
       sceneDepth: null,
     };
     const context = this.passContext;
-    context.outputTransform = this.gradeCode();
-    context.outputExposure = this.gradeExposure();
+    context.outputTransform = this.passGrade();
+    context.outputExposure = this.passGradeExposure();
     /*
      * The copies a pass declared it reads, taken here with everything drawn before it: colour
      * afresh at each reading pass, as WebGPU's `takePassColour` does, so a full-screen effect drawn
@@ -3893,11 +3897,11 @@ export class WebGL2Renderer implements RendererApi {
     } finally {
       target.end(gl);
       gl.frontFace(gl.CCW);
+      this.capturePassActive = false;
       this.useFlatProgram();
-      gl.uniform1i(this.flatUniforms['uOutputTransform'] ?? null, this.gradeCode());
-      gl.uniform1f(this.flatUniforms['uOutputExposure'] ?? null, this.gradeExposure());
+      gl.uniform1i(this.flatUniforms['uOutputTransform'] ?? null, this.passGrade());
+      gl.uniform1f(this.flatUniforms['uOutputExposure'] ?? null, this.passGradeExposure());
       this.materials.dirty();
-      this.capturePassActive = false;
       this.temporalJittering = jittering;
       this.restoreViewport();
     }
@@ -5289,7 +5293,7 @@ export class WebGL2Renderer implements RendererApi {
      */
     if (!lit) gl.uniform1i(u['uLightingEnabled'] ?? null, 0);
     if (fog !== this.surfaceFog) gl.uniform1i(u['uFogEnabled'] ?? null, fog);
-    if (!toneMapped) gl.uniform1i(u['uOutputTransform'] ?? null, Math.min(this.gradeCode(), 1));
+    if (!toneMapped) gl.uniform1i(u['uOutputTransform'] ?? null, Math.min(this.passGrade(), 1));
 
     if (blend) {
       gl.enable(gl.BLEND);
@@ -5347,7 +5351,7 @@ export class WebGL2Renderer implements RendererApi {
     if (refracting) this.unbindSeeThrough(u);
     if (!lit) gl.uniform1i(u['uLightingEnabled'] ?? null, 1);
     if (fog !== this.surfaceFog) gl.uniform1i(u['uFogEnabled'] ?? null, this.surfaceFog);
-    if (!toneMapped) gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
+    if (!toneMapped) gl.uniform1i(u['uOutputTransform'] ?? null, this.passGrade());
     if (own) this.materials.dirty();
     this.useFlatProgram();
   }
@@ -5523,7 +5527,18 @@ export class WebGL2Renderer implements RendererApi {
     // raining dust into the sea.
     const surface = env.underwater?.surfaceY;
     const submerged = surface !== undefined && (camera.position[1] ?? 0) < surface;
-    if (streaks.draw(this.gl, this.frameViewFor(camera), wind, timeSeconds, tint, submerged)) {
+    if (
+      streaks.draw(
+        this.gl,
+        this.frameViewFor(camera),
+        wind,
+        timeSeconds,
+        tint,
+        submerged,
+        this.passGrade(),
+        this.passGradeExposure(),
+      )
+    ) {
       this.windStreakBudget.ask();
     }
   }
@@ -5563,7 +5578,18 @@ export class WebGL2Renderer implements RendererApi {
     timeSec: number,
   ): void {
     this.scatterSkin();
-    if (text.draw(viewportWidth, viewportHeight, originX, originY, style, timeSec)) {
+    if (
+      text.draw(
+        viewportWidth,
+        viewportHeight,
+        originX,
+        originY,
+        style,
+        timeSec,
+        interfaceGrade(this.passGrade()),
+        1,
+      )
+    ) {
       this.textBudget.ask();
     }
   }
@@ -5642,7 +5668,9 @@ export class WebGL2Renderer implements RendererApi {
    * real draw call touches the unit in the first place.
    */
   /**
-   * The output transform a forward pass should apply, and the exposure it should apply it at.
+   * The grade a pass applies to what it draws into the target open now, and the exposure it
+   * applies it at. The decision is `passGrade.ts`'s, for both backends; this only gathers the
+   * state it is taken from.
    *
    * **Only where that pass is genuinely the last one to touch the frame.** With a scene target
    * the resolve grades, so a pass that graded as well would be applying a curve to its own
@@ -5650,21 +5678,37 @@ export class WebGL2Renderer implements RendererApi {
    * `screenEffects` off there is no resolve at all and every pass writes straight to the canvas,
    * so each one has to grade itself or the frame comes out half converted: linear values in an
    * eight-bit buffer read as display values, which is a saturated, clipped version of the colour
-   * the caller asked for rather than a slightly different one.
+   * the caller asked for rather than a slightly different one. A probe's face or a capture is
+   * never graded, and past the present every pass grades itself, composite or not.
    *
    * One pair of accessors rather than the expression written out at each site, because that is
    * how the mesh pass and the particle pass came to disagree in the first place: the mesh pass
    * gated, and the particle pass uploaded the transform unconditionally to a stage that did not
    * yet declare it.
    */
-  private gradeCode(): number {
-    return this.sceneTarget === null || !this.quality.hdrScene
-      ? forwardTransformCode(this.quality.outputTransform)
-      : 0;
+  private passGrade(): number {
+    const storing = this.probePassActive || this.capturePassActive;
+    const transform = this.quality.outputTransform;
+    return passGradeCode(storing, this.framePresented, this.resolveGrades(), transform);
+  }
+
+  private passGradeExposure(): number {
+    const storing = this.probePassActive || this.capturePassActive;
+    return passGradeExposure(storing, this.framePresented, this.resolveGrades(), this.exposure);
   }
 
-  private gradeExposure(): number {
-    return this.sceneTarget === null || !this.quality.hdrScene ? this.exposure : 1;
+  /** Whether the frame's resolve applies the transform, so the passes before it draw linear. */
+  private resolveGrades(): boolean {
+    return this.sceneTarget !== null && this.quality.hdrScene;
+  }
+
+  /**
+   * A clear colour as the target open now takes it: graded as a pass would grade it, so a colour
+   * handed to the renderer is linear wherever it lands — the clear too, which the resolve grades
+   * with everything else under `hdrScene`. See `gradeColor.ts`. Into one scratch, read at once.
+   */
+  private clearOf(color: Readonly<Vec3>): Vec3 {
+    return gradeColorInto(this.passGrade(), this.passGradeExposure(), color, this.gradedClear);
   }
 
   drawSdfText(handle: SdfTextRenderer, model: Float32Array, color: Vec3, opacity: number): void {
@@ -5679,8 +5723,8 @@ export class WebGL2Renderer implements RendererApi {
         model,
         color,
         opacity,
-        this.gradeCode(),
-        this.gradeExposure(),
+        this.passGrade(),
+        this.passGradeExposure(),
       )
     ) {
       this.sdfTextBudget.ask();
@@ -5707,7 +5751,17 @@ export class WebGL2Renderer implements RendererApi {
     windZ = 0,
   ): void {
     this.flockBudget.ask();
-    flock.draw(this.gl, this.frameViewFor(camera), timeSeconds, params, tint, windX, windZ);
+    flock.draw(
+      this.gl,
+      this.frameViewFor(camera),
+      timeSeconds,
+      params,
+      tint,
+      windX,
+      windZ,
+      this.passGrade(),
+      this.passGradeExposure(),
+    );
   }
 
   /**
@@ -5808,8 +5862,8 @@ export class WebGL2Renderer implements RendererApi {
        the uniform at all, so it was a write to a location that did not exist; now that the
        stage grades itself it has to obey the same "only where this pass is last" rule the mesh
        pass does, or a scene with a composite grades its particles twice. */
-    gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
-    gl.uniform1f(u['uOutputExposure'] ?? null, this.gradeExposure());
+    gl.uniform1i(u['uOutputTransform'] ?? null, this.passGrade());
+    gl.uniform1f(u['uOutputExposure'] ?? null, this.passGradeExposure());
     gl.uniform3fv(u['uAmbient'] ?? null, env.ambient);
     gl.uniform3fv(u['uAmbientGround'] ?? null, env.ambientGround ?? env.ambient);
     gl.uniform1i(u['uNoiseOctaves'] ?? null, this.quality.plumeNoiseOctaves);
@@ -5917,6 +5971,8 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniform3fv(u['uCoreColor'] ?? null, core);
     gl.uniform3fv(u['uEdgeColor'] ?? null, edge);
     gl.uniform1f(u['uCoreGain'] ?? null, coreGain);
+    gl.uniform1i(u['uOutputTransform'] ?? null, this.passGrade());
+    gl.uniform1f(u['uOutputExposure'] ?? null, this.passGradeExposure());
     bindAtmosphere(
       gl,
       u,
@@ -5992,8 +6048,8 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniform3fv(u['uColor'] ?? null, color);
     gl.uniform1f(u['uOpacity'] ?? null, opacity);
     gl.uniform1f(u['uSoftness'] ?? null, softness);
-    gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
-    gl.uniform1f(u['uOutputExposure'] ?? null, this.gradeExposure());
+    gl.uniform1i(u['uOutputTransform'] ?? null, this.passGrade());
+    gl.uniform1f(u['uOutputExposure'] ?? null, this.passGradeExposure());
     bindAtmosphere(
       gl,
       u,
@@ -6042,6 +6098,8 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniform3fv(u['uDirectionalColor'] ?? null, env.directionalColor);
     gl.uniform3fv(u['uAmbient'] ?? null, env.ambient);
     gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
+    gl.uniform1i(u['uOutputTransform'] ?? null, this.passGrade());
+    gl.uniform1f(u['uOutputExposure'] ?? null, this.passGradeExposure());
     bindAtmosphere(
       gl,
       u,
@@ -6236,6 +6294,8 @@ export class WebGL2Renderer implements RendererApi {
       originX,
       originY,
       originZ,
+      this.passGrade(),
+      this.passGradeExposure(),
     );
   }
 
@@ -6265,6 +6325,8 @@ export class WebGL2Renderer implements RendererApi {
       this.quality.pointLightFalloff,
       windX,
       windZ,
+      this.passGrade(),
+      this.passGradeExposure(),
     );
   }
 
@@ -6295,6 +6357,8 @@ export class WebGL2Renderer implements RendererApi {
       windX,
       windZ,
       strength,
+      this.passGrade(),
+      this.passGradeExposure(),
     );
     if (drew) this.causticsBudget.ask();
   }
@@ -6337,7 +6401,7 @@ export class WebGL2Renderer implements RendererApi {
       this.canvas.height,
       source,
       planeY,
-      clearColor,
+      this.clearOf(clearColor),
     );
     this.gpuTimer.begin('reflection');
     this.reflectionPassActive = true;
@@ -7651,7 +7715,8 @@ export class WebGL2Renderer implements RendererApi {
       // scene rather than over a rectangle of flat colour.
       gl.clear(gl.DEPTH_BUFFER_BIT);
     } else {
-      gl.clearColor(clearColor[0], clearColor[1], clearColor[2], 1);
+      const clear = this.clearOf(clearColor);
+      gl.clearColor(clear[0], clear[1], clear[2], 1);
       gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
     }
     /*
@@ -7761,6 +7826,9 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniformMatrix4fv(this.panelUniforms['uClipCorrection'] ?? null, false, IDENTITY_MAT4);
     gl.uniform3fv(this.panelUniforms['uColor'] ?? null, color);
     gl.uniform1f(this.panelUniforms['uAlpha'] ?? null, alpha);
+    /* An interface: the screen encode, never the curve. See `interfaceGrade`. */
+    gl.uniform1i(this.panelUniforms['uOutputTransform'] ?? null, interfaceGrade(this.passGrade()));
+    gl.uniform1f(this.panelUniforms['uOutputExposure'] ?? null, 1);
 
     gl.drawArrays(gl.TRIANGLES, 0, 6);
 
@@ -8487,7 +8555,8 @@ export class WebGL2Renderer implements RendererApi {
     this.sceneTarget?.begin(this.canvas.width, this.canvas.height);
     /* The materials' maps on the scene's framebuffer, cleared and disabled: `reflectionKeeps`. */
     this.reflectionTargets?.begin(this.canvas.width, this.canvas.height);
-    gl.clearColor(clearColor[0], clearColor[1], clearColor[2], 1);
+    const clear = this.clearOf(clearColor);
+    gl.clearColor(clear[0], clear[1], clear[2], 1);
     gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
   }
 
@@ -8642,7 +8711,7 @@ export class WebGL2Renderer implements RendererApi {
           exposure: this.exposure,
           film: this.filmConstants,
         }
-      : { transform: 0, exposure: 1 };
+      : { transform: 0, exposure: 1, sceneGraded: this.passGrade() !== 0 };
     /*
      * Depth of field, on the same ceiling-and-dial split as bloom above: `depthOfField` decides
      * how far a defocused point may spread and this frame's `setDepthOfField` decides where the
@@ -8705,6 +8774,7 @@ export class WebGL2Renderer implements RendererApi {
           this.frameEye,
           this.canvas.width,
           this.canvas.height,
+          this.passGrade(),
         );
       }
     }
@@ -8902,7 +8972,13 @@ export class WebGL2Renderer implements RendererApi {
           /* The march finished on the default framebuffer, which is not where the frame is being
              drawn. See `resolveReflections`, which is the same two-step for the same reason. */
           this.sceneTarget.bind();
-          this.medium.compositeMedium(depthCopy, this.canvas.width, this.canvas.height);
+          this.medium.compositeMedium(
+            depthCopy,
+            this.canvas.width,
+            this.canvas.height,
+            this.passGrade(),
+            this.passGradeExposure(),
+          );
         }
       }
     }
@@ -9381,12 +9457,11 @@ export class WebGL2Renderer implements RendererApi {
      * exists to keep. With `screenEffects` off there is no resolve at all and the mesh pass
      * writes straight to the canvas, so it stays where it always was.
      *
-     * The consequence worth stating: full grading needs the composite. Without it the sky, the
-     * particles, the film and the water are still ungraded beside a world that is, which is the
-     * inconsistency that existed everywhere before this moved.
+     * Every other pass grades through the same gate, `passGrade`, so a frame without a composite
+     * is graded pass by pass to the curve a composite would have applied once.
      */
-    gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
-    gl.uniform1f(u['uOutputExposure'] ?? null, this.gradeExposure());
+    gl.uniform1i(u['uOutputTransform'] ?? null, this.passGrade());
+    gl.uniform1f(u['uOutputExposure'] ?? null, this.passGradeExposure());
     gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
     /*
      * Solid, every frame, before anything asks otherwise. A GL uniform starts at
@@ -9875,7 +9950,15 @@ export class WebGL2Renderer implements RendererApi {
     if (projection === null) return;
     const depth = scene.snapshotDepth(true);
     mat4.invert(this.skinInverseProjection, projection);
-    skin.spread(scene, depth, this.emptyTexture2D, projection, this.skinInverseProjection);
+    skin.spread(
+      scene,
+      depth,
+      this.emptyTexture2D,
+      projection,
+      this.skinInverseProjection,
+      this.passGrade(),
+      this.passGradeExposure(),
+    );
     this.useFlatProgram();
   }
 
@@ -10188,7 +10271,7 @@ export class WebGL2Renderer implements RendererApi {
     /* `1` is sRGB alone: the conversion without the curve, which is what dropping the tone map
        means rather than dropping the whole transform. `Math.min` rather than a literal, so a
        renderer asked for `none` stays at none and one asked for `srgb` is already there. */
-    if (!toneMapped) gl.uniform1i(u['uOutputTransform'] ?? null, Math.min(this.gradeCode(), 1));
+    if (!toneMapped) gl.uniform1i(u['uOutputTransform'] ?? null, Math.min(this.passGrade(), 1));
     /* Scoped and handed back like every other state here, so a tinted draw cannot leak its
        colour onto the next one. See `TranslucentMeshOptions.tint`. */
     const tint = options.tint ?? null;
@@ -10259,7 +10342,7 @@ export class WebGL2Renderer implements RendererApi {
        cannot inherit a material from the draw before it. */
     if (!lit) gl.uniform1i(u['uLightingEnabled'] ?? null, 1);
     if (fog !== this.surfaceFog) gl.uniform1i(u['uFogEnabled'] ?? null, this.surfaceFog);
-    if (!toneMapped) gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
+    if (!toneMapped) gl.uniform1i(u['uOutputTransform'] ?? null, this.passGrade());
     if (own) this.materials.dirty();
   }
 
@@ -10362,7 +10445,7 @@ export class WebGL2Renderer implements RendererApi {
     /*
      * **A probe stores radiance, not display pixels.**
      *
-     * `gradeCode()` is the ACES curve and the sRGB encode whenever the frame has no HDR target,
+     * `passGrade()` is the ACES curve and the sRGB encode whenever the frame has no HDR target,
      * so every face was baked through the whole output transform and the shader then sampled the
      * result as though it were light. Two things came of that and both read as "the reflection is
      * dull": the curve pulls everything bright toward 1 *before* it reaches the cube, so no
@@ -10418,16 +10501,17 @@ export class WebGL2Renderer implements RendererApi {
       }
     } finally {
       this.gl.frontFace(this.gl.CCW);
-      this.useFlatProgram();
-      this.gl.uniform1i(this.flatUniforms['uOutputTransform'] ?? null, this.gradeCode());
-      this.gl.uniform1f(this.flatUniforms['uOutputExposure'] ?? null, this.gradeExposure());
-      this.materials.dirty();
       /*
        * Cleared even if a caller's own draw threw, because leaving this set would keep every
-       * later frame reading the placeholder and quietly reflecting nothing.
+       * later frame reading the placeholder and quietly reflecting nothing. Before the grade is
+       * put back, which asks it.
        */
       this.probePassActive = false;
       this.probeBounce = false;
+      this.useFlatProgram();
+      this.gl.uniform1i(this.flatUniforms['uOutputTransform'] ?? null, this.passGrade());
+      this.gl.uniform1f(this.flatUniforms['uOutputExposure'] ?? null, this.passGradeExposure());
+      this.materials.dirty();
       /* Back to the canvas, or to the frame's own target if one is bound. See `SceneTarget`. */
       if (this.sceneTarget !== null && !this.framePresented) this.sceneTarget.bind();
       else {
@@ -10655,6 +10739,8 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniformMatrix4fv(u['uModel'] ?? null, false, model);
     gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
     gl.uniform1f(u['uStrength'] ?? null, Math.min(shown, 1));
+    gl.uniform1i(u['uOutputTransform'] ?? null, this.passGrade());
+    gl.uniform1f(u['uOutputExposure'] ?? null, this.passGradeExposure());
     gl.uniform1f(u['uLength'] ?? null, length);
     gl.uniform1f(u['uSpread'] ?? null, spread);
     gl.uniform1f(u['uDust'] ?? null, clamp(options.dust ?? 0, 0, 1));
@@ -10820,6 +10906,8 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
     gl.uniform1f(u['uTime'] ?? null, timeSeconds);
     gl.uniform1f(u['uSheen'] ?? null, sheen);
+    gl.uniform1i(u['uOutputTransform'] ?? null, this.passGrade());
+    gl.uniform1f(u['uOutputExposure'] ?? null, this.passGradeExposure());
     gl.uniform1f(u['uFilmRoughness'] ?? null, Math.min(1, Math.max(0, options.roughness ?? 0)));
     gl.uniform1f(
       u['uFilmRoughnessCycles'] ?? null,
@@ -10875,6 +10963,8 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniform1f(u['uMoonPhase'] ?? null, sky.moonPhase);
     gl.uniform1f(u['uNightFactor'] ?? null, sky.nightFactor);
     gl.uniform2f(u['uCloudOffset'] ?? null, sky.cloudOffsetX, sky.cloudOffsetZ);
+    gl.uniform1i(u['uOutputTransform'] ?? null, this.passGrade());
+    gl.uniform1f(u['uOutputExposure'] ?? null, this.passGradeExposure());
     bindAtmosphere(
       gl,
       u,

package/src/render/backend/webgl2/skinScatter.ts

@@ -147,6 +147,9 @@ export class GlSkinScatter {
     empty: WebGLTexture,
     projection: ArrayLike<number>,
     inverse: ArrayLike<number>,
+    /** The frame's grade, which the second axis applies to the light it adds. */
+    outputTransform = 0,
+    outputExposure = 1,
   ): void {
     const { gl } = this;
     if (this.multisampled !== null) {
@@ -163,6 +166,8 @@ export class GlSkinScatter {
     gl.uniform1i(u['uSkin'] ?? null, SKIN_BLUR_TEXTURE_UNIT);
     gl.uniform1i(u['uDepth'] ?? null, SKIN_BLUR_DEPTH_UNIT);
     gl.uniform1i(u['uAlbedo'] ?? null, SKIN_BLUR_ALBEDO_UNIT);
+    gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
+    gl.uniform1f(u['uOutputExposure'] ?? null, outputExposure);
     gl.activeTexture(gl.TEXTURE0 + SKIN_BLUR_ALBEDO_UNIT);
     gl.bindTexture(gl.TEXTURE_2D, this.albedo ?? empty);
     /* The four terms that carry a depth back to view-space metres: the occlusion blur's own. */

package/src/render/backend/webgpu/giFieldPass.ts

@@ -41,7 +41,9 @@ const STORAGE = 0x0080;
  * can look at, and looking is what a number cannot replace: if the geometry is in the right places
  * at the right sizes the composition is right, and if a cascade boundary shows as a seam the fade
  * is wrong. Wave 4A's own recorded failure — a phantom surface that passed 111,907 parity samples
- * and was found by looking at a picture — is why this exists at all.
+ * and was found by looking at a picture — is why this exists at all. **So it is not graded**, alone
+ * of the passes that draw into a frame: what it shows are the field's values, which a curve would
+ * bend into a picture of something else.
  *
  * **The field it marches is one frame old**, because the renderer composes at `endFrame` and
  * `prepare` runs at `beginFrame`. `PrepareContext.distanceField` says why that is right rather

package/src/render/backend/webgpu/gpuDrivenPass.ts

@@ -962,7 +962,16 @@ export class GpuDrivenPass implements PassDefinition {
     shadowed: true,
     blended: false,
   };
-  private gradeWarned = false;
+  /**
+   * The frame's grade for the blit, `PassContext.outputTransform` and its exposure, and the code it
+   * was last written with, so a frame writes it only when it changes. See `present.wgsl.ts`.
+   */
+  private gradeBuffer: GPUBuffer | null = null;
+  private readonly gradeStaging = new ArrayBuffer(16);
+  private readonly gradeInts = new Int32Array(this.gradeStaging);
+  private readonly gradeFloats = new Float32Array(this.gradeStaging);
+  private gradeWrittenCode = Number.NaN;
+  private gradeWrittenExposure = Number.NaN;
 
   constructor(
     scene: StreamingScene,
@@ -2410,10 +2419,17 @@ export class GpuDrivenPass implements PassDefinition {
       ],
     });
 
+    this.gradeBuffer ??= device.createBuffer({
+      label: 'gpu-driven blit grade',
+      size: this.gradeStaging.byteLength,
+      usage: UNIFORM | COPY_DST,
+    });
+    this.gradeWrittenCode = Number.NaN;
     this.blitGroup = device.createBindGroup({
       layout: (this.blitPipeline as GPURenderPipeline).getBindGroupLayout(0),
       entries: [
         { binding: 0, resource: this.colourView as GPUTextureView },
+        { binding: 2, resource: { buffer: this.gradeBuffer } },
         /* The depth the raster wrote, sampled so the blit can hand it to the frame. */
         ...(this.presentDepth
           ? [
@@ -3429,18 +3445,16 @@ export class GpuDrivenPass implements PassDefinition {
     /* The same gate as `prepare`: an unanswered or refused pipeline set encodes nothing at all. */
     if (!this.usable) return;
     if (this.blitPipeline === null || this.blitGroup === null) return;
-    if (ctx.outputTransform !== 0 && !this.gradeWarned) {
-      this.gradeWarned = true;
-      /*
-       * The pass writes linear light and expects a composite to grade it. A frame with no
-       * composite grades per pass, and applying the curve here would be a second copy of it —
-       * which is the thing `SHADE_MATERIAL_WGSL` is built to avoid. Said once, out loud, because
-       * a silently ungraded frame is a difference somebody would attribute to the pipeline.
-       */
-      console.warn(
-        '[driftengine] the gpu-driven pass writes linear light and this frame has no composite ' +
-          'to grade it, so the picture will be flat. Use a quality profile with a scene target.',
-      );
+    /* The frame's grade, written when it changes: 0 where the resolve grades. See present.wgsl.ts. */
+    const changed =
+      ctx.outputTransform !== this.gradeWrittenCode ||
+      ctx.outputExposure !== this.gradeWrittenExposure;
+    if (changed && this.device !== null && this.gradeBuffer !== null) {
+      this.gradeWrittenCode = ctx.outputTransform;
+      this.gradeWrittenExposure = ctx.outputExposure;
+      this.gradeInts[0] = ctx.outputTransform;
+      this.gradeFloats[1] = ctx.outputExposure;
+      this.device.queue.writeBuffer(this.gradeBuffer, 0, this.gradeStaging);
     }
     ctx.pass.setPipeline(this.blitPipeline);
     ctx.pass.setBindGroup(0, this.blitGroup);
@@ -3452,6 +3466,8 @@ export class GpuDrivenPass implements PassDefinition {
     this.scene.detach();
     if (device.backend !== 'webgpu') return;
     this.disposeTargets();
+    this.gradeBuffer?.destroy();
+    this.gradeBuffer = null;
     this.shadowTexture?.destroy();
     this.glassTintTexture?.destroy();
     this.glassTintNone?.destroy();