@driftengine/core 4.12.0 → 4.13.1

package/CHANGELOG.json

@@ -1,4 +1,81 @@
 [
+  {
+    "version": "4.13.1",
+    "date": "2026-10-11",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "A sprite slot can take one painted rectangle instead of its whole image, so an atlas painted a picture at a time stops sending all of itself: `SpritePass.updateTexture`.",
+        "text": "`SpritePass.updateTexture(slot, source, region)` copies one rectangle of an image into the slot's texture at the same place and keeps the rest of it. `setTexture` sends the whole image and, on WebGPU, makes the texture and its bind group again, so a 2D layer painted into atlases sent every texel of an atlas for each picture painted into it: a consumer measured about 100 ms for a 5120-texel side, on a frame whose new pictures covered about 6 of the atlas's 26 million texels, and a typical later frame changes a timer's digits. Now an upload grows with what was painted rather than with the atlas. The slot keeps the options it was made with; a slot that is empty, or was made from an image of another size, takes the whole image as `setTexture` would; the rectangle is clipped to the image; and a slot with a mip chain has the chain rebuilt. On WebGL2 it is `texSubImage2D` with the unpack state put back after, since every other upload on the context reads it. **Paint such an atlas into a 2D context made with `willReadFrequently: true`**: on WebGPU a canvas drawn on the GPU is transferred whole before any part of it is copied, measured at 66 ms for one 256 by 64 rectangle of a 5120-texel atlas against 0.4 ms from a canvas kept in memory. WebGL2 copies a rectangle quickly from either. `SpriteRegion` is the rectangle's type."
+      }
+    ]
+  },
+  {
+    "version": "4.13.0",
+    "date": "2026-10-10",
+    "entries": [
+      {
+        "kind": "changed",
+        "short": "The frame is encoded for the screen by default, every pass and the clear colour alike: `outputTransform` is `'srgb'`, so a model reads as it does elsewhere.",
+        "text": "`outputTransform` defaults to `'srgb'`. 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, which `'none'`, the default until now, did, reads every midtone far too dark: a textured model drawn from the manual with no quality options came out darker than the same file in any other engine, and the cause looks like lighting, so that is where people looked. **Every pass now grades where nothing after it will, and the clear colour with them**, so a colour handed to the renderer means one thing wherever it lands: the sky, water, scatter, the plumes, flocks, wind streaks, bolts, caustics, light volumes and film grade themselves, as the lit pass, particles, lines and world text already did; the decal multiply, the global medium, the skin blur's add and the resolve's occlusion work in the terms of a pixel already graded; and the gpu-driven pipeline's blit grades instead of warning. Until now, without `hdrScene`, those passes drew their colours as given beside a graded world, so a sky never met the fog fading into it. `'srgb'` is the display encoding with no tone curve; `'aces'` with an `outputExposure` still rolls highlights off. A world graded under `'none'` says so and draws exactly as it did, bit for bit, and a frame with `hdrScene` is graded once at the resolve exactly as before. What changes for a world on another curve without `hdrScene` is that its sky and water are graded with it, and its interface is encoded for the screen, as the next entry says."
+      },
+      {
+        "kind": "added",
+        "short": "Colours picked by eye are stated as such: `srgbColor(r, g, b)`, `MeshBuilder.build({ colorSpace: 'srgb' })` and `decodeSrgbInPlace`, each decoding to the linear values the renderer draws.",
+        "text": "A colour picked by eye, on a screen or in a paint program, is a display value, and the renderer draws linear ones, so typed in as it looks it comes out too light. Three ways say which it is. `srgbColor(r, g, b)` decodes one colour through the sRGB curve, so a surface lit at 1, a sky or a clear colour comes out as the colour picked. `MeshBuildOptions.colorSpace: 'srgb'` decodes every vertex colour and emissive colour of a built mesh once, at build, as a texture uploaded as sRGB is decoded at upload, so a world built from hand-picked colours changes one line. `decodeSrgbInPlace` decodes an array of them, leaving a negative sentinel alone, for a mesh written by hand. `srgbToLinear` decodes one channel, for a colour that arrives a number at a time, as a packed hex token does. A light's intensity is an amount rather than a look and stays as it is. The examples state their colours this way, and the starter, which a new project begins from, shows the default."
+      },
+      {
+        "kind": "changed",
+        "short": "Text, panels and the 2D layer are encoded for the screen and never tone mapped, so an interface comes out as picked under any transform and at any exposure.",
+        "text": "Screen text, `fillPanel` and `@driftengine/ui2d`'s 2D layer take the screen encode and never the curve or the exposure: `interfaceGrade` says which code that is, for a contributed pass that draws an interface. A caption or a panel is not light, and its colour was picked for the screen, so under `'aces'` a menu's white text came out grey, its dark panel crushed to black, and the whole interface brightened and darkened as the scene's exposure eased. Now every interface colour stated through `srgbColor`, or as a theme's hex token, comes out exactly as picked under every transform. Inside an `hdrScene` frame an interface is part of the picture the resolve tone maps, as it was; drawn after `endFrame`, it is not. Text drawn in the world at a model matrix is part of the world and keeps the curve."
+      },
+      {
+        "kind": "fixed",
+        "short": "A pass drawn after `endFrame` grades itself under an `hdrScene` composite too, where it drew its colours as display values beside a graded frame.",
+        "text": "With `hdrScene` the resolve grades the frame and every pass before it draws linear light. A pass drawn after `endFrame` lands on the canvas the resolve has already written, so nothing after it grades it, and it used to draw ungraded there: an interface drawn after the present, which is where the manual puts one to keep it out of the screen-space chain, was the one surface on screen reading its colours as display values. The decision is now one function both backends read, and past the present it answers the frame's own grade, composite or not."
+      },
+      {
+        "kind": "changed",
+        "short": "A colour picked for the screen is decoded where an interface takes one: ui2d's hex tokens, and a script's `ui.tint` and `sprites.tinted`.",
+        "text": "`unpackRgba` and `themeRgba` decode a packed `0xRRGGBBAA` token from the sRGB a hex colour is written in to the linear light a node holds, keeping its alpha as coverage. Read as linear, `0x336699` came out as `0x7caacb` under the new default, every panel a washed-out version of the one picked. DriftScript's `ui.tint` and `sprites.tinted` take a colour picked for the screen in the same terms and decode it, since a script has no `srgbColor` to say so, so a white sprite draws exactly the tint named. A renderer asked for `outputTransform: 'none'` draws these darker than picked, as it does every colour."
+      },
+      {
+        "kind": "changed",
+        "short": "A splat capture's colour is a display value, decoded after its view-dependent band, so a trained capture draws as it does in the tool that made it.",
+        "text": "A Gaussian capture is trained against photographs, so its colour terms reproduce their pixels drawn as they are. `SplatSource.colors` was documented as linear and drawn so, which under the new `'srgb'` default is a washed-out cloud. The splat shader now decodes a splat's colour after adding its l=1 band, which training added in the same space, and the eight bits a colour is packed into are spent where the eye sees them. What it gives up is the blend: splats compose in linear light rather than in the display values training composed them in, which moves a translucent edge a little. `@driftengine/capture` fits in linear light against decoded frames and now hands its colours over encoded, its l=1 band carried through the encode's slope at each colour, so a fitted capture draws as fitted."
+      },
+      {
+        "kind": "changed",
+        "short": "Sun shadows no longer dissolve past six metres or below 18° of sun: `directionalShadowMaxDistance` defaults to 1,000 and `directionalShadowMaxSlope` to 60.",
+        "text": "`directionalShadowMaxDistance` defaults to 1,000 metres and `directionalShadowMaxSlope` to 60. The old 6 and 3 were a tuning for short casters: any sun shadow longer than six metres along the ground dissolved, so a building's walls and arcades cast nothing on its floor under a high sun and the light read as random, and every sun shadow faded below about 18° of elevation, which is an evening without shadows. A shadow now reaches as far as its map holds, whose edge already fades it, and holds until the sun is about a degree above the horizon. The reach is a shadow's own length along the ground and not a distance from the camera, which its name suggests, and both options now say what their default gives up and what would make it wrong. A scene whose low sun streaks lowers the slope; one tuned around the old values sets them. The medium's shafts and a surface's shadows, which disagreed past six metres, now agree."
+      },
+      {
+        "kind": "added",
+        "short": "`DrftLoader` draws, casts and prepares its model: `draw()`, `casters` and `prepare()` apply every rule a container needs, and `PartDraws` does it for a chosen list.",
+        "text": "`DrftLoader.draw()` draws this frame's parts into the open mesh pass by every rule a baked container needs, each of which fails as a picture rather than an error when it is missed: a part's whole material, so foliage keeps its alpha test and a one-sided card its faces; its copies through one instanced draw, where a part drawn as a plain mesh shows one arch of a repeated row; a blended part translucent whatever its opacity and writing no depth, since its alpha is in its texture, where drawn opaque a grime decal is a black patch; a blended batch through the translucent instanced path; glass as glass, its options kept per pane so a frame allocates nothing; and each part's own reflectivity, with nothing left set for the caller's draws after it. `loader.casters` is a ready `ShadowCasters`: every part but a decal, which would shadow its own surface, each with its material so a cutout casts its shape, glass as glass and copies as copies. `await loader.prepare()` compiles every pipeline the parts draw with, off the frame, translucent where they will be drawn so. `PartDraws` is the same for any list of parts, several loaders' or a filtered one. The manual's chapter on importing models and the models example draw through them."
+      },
+      {
+        "kind": "added",
+        "short": "`computeLightMatrixForBounds` covers a box with the sun's map whole, and `DrftLoader.shadowFit` fits the map to a model as placed, from the bounds its file declares.",
+        "text": "`computeLightMatrixForBounds(lightDir, min, max, mapSize, out)` places a directional light's map around a box of known size: the sphere around the box, at its centre, widened by the half texel the centre's snap may move it, so a corner on the sphere stays inside. A focus and a radius chosen by eye around a guessed centre left part of a model outside the map, where it cast nothing. `DrftLoader.shadowFit(lightDir, mapSize, out)` does it for the model as fitted and returns the depth span for `shadowDepthSpan`, or null until `HEAD` has said how large the model is. What both give up is resolution on a large box, whose texels are spread over all of it; a world that follows a player keeps `computeLightMatrix` around the viewer."
+      },
+      {
+        "kind": "added",
+        "short": "`meshOcclusion` darkens the colour and the ambient light at once, each at its own strength: `colorStrength` beside `into: 'ambient'`, past 1 where a material asks.",
+        "text": "`SurfaceMeshOcclusion.colorStrength` is the colour's own strength: the blended colour times `max(0, 1 − colorStrength × (1 − occlusion))`, which up to 1 is the `mix` a strength always gave and past it darkens faster than the occlusion does. Named beside `into: 'ambient'`, one occlusion darkens the ambient light at `strength` and the colour at `colorStrength`, which is how a material that takes its ambient occlusion from a map and darkens its colour by the same map, at up to twice that, is drawn; with a single target it drew one of the two. Absent, it is `strength` where the colour is the target and 0 where the ambient light is, so every material written for 4.12.0 draws as it did. The two floats that carried a strength and a target now carry the two strengths."
+      },
+      {
+        "kind": "fixed",
+        "short": "A summed layer blend reflects the surface's own specular once where its layers name none, rather than its own times the sum of the layers' shares.",
+        "text": "Under `blend: 'sum'` a layer's share is its weight, and the shares add past 1 where the weights do, which is what a summed blend is for in colour. The specular took the same sum: a layer that named none gave the surface's own times its share, so a surface painted to weights adding to 2.5 or 3 reflected two and a half to three times its own specular, measured as a sandy floor 2.5% brighter across a frame than with its own. The layers that name no specular now give the surface's own at most once, whatever their shares add to, and named speculars still add as their colours do. A blend laid over, whose shares never pass 1, draws exactly as before, as does any layered material while no material has asked for looks."
+      },
+      {
+        "kind": "fixed",
+        "short": "A reflection probe stays ungraded when its bake's callback binds the mesh pass, so the frame no longer grades what it reads from the probe a second time.",
+        "text": "A probe stores radiance, so its bake holds the output transform at 0 while it draws the faces. `bindMeshPass`, which every bake's callback calls first, set the frame's grade again, so under any forward grade each face was graded as it was drawn and the frame graded what it read back from the cube a second time: reflections and probe ambient lifted and flattened. Every pass, the mesh pass among them, now asks one gate, which answers the frame's grade except in a probe's face or a capture. The same gate keeps particles, lines, text and contributed passes ungraded inside a bake."
+      }
+    ]
+  },
   {
     "version": "4.12.0",
     "date": "2026-10-10",

package/README.md

@@ -6,7 +6,7 @@ WebGL2 everywhere else, behind one API, and carries the fixed-step loop, the ren
 input, the scene graph, geometry, text and the whole of `@driftengine/physics`, which it re-exports.
 Everything else is a separate package a game adds when it reaches for it.
 
-**Cost: 910.1 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+**Cost: 920.9 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
 which fails the build if the figure drifts by more than 3%.
 
 The manual is at **[driftengine.dev/docs](https://driftengine.dev/docs)**, with an example running
@@ -35,6 +35,7 @@ import {
   SceneNode,
   createEnvironment,
   createRenderer,
+  srgbColor,
   startLoop,
 } from '@driftengine/core';
 import { bindModule } from '@driftengine/script';
@@ -60,15 +61,23 @@ if (readout !== null) readout.textContent = `${backend}: ${reason}`;
 renderer.resize();
 addEventListener('resize', () => renderer.resize());
 
-/** Light, air and ground bounce. Chosen once, because these are allocation-sized decisions. */
+/**
+ * Light, air and ground bounce. Chosen once, because these are allocation-sized decisions.
+ *
+ * Every colour here and below was picked by eye, so it goes through `srgbColor`: the renderer
+ * lights in linear values and encodes them for the screen at the end, and a colour typed as it
+ * looks would come out too light. The clear colour in the loop is one of them.
+ */
+const CLEAR = srgbColor(0.05, 0.06, 0.09);
+
 const ENV = createEnvironment({
   directionalDir: [0.4, 0.7, 0.35],
-  directionalColor: [1, 0.96, 0.88],
-  ambient: [0.2, 0.22, 0.28],
-  ambientGround: [0.08, 0.08, 0.1],
+  directionalColor: srgbColor(1, 0.96, 0.88),
+  ambient: srgbColor(0.2, 0.22, 0.28),
+  ambientGround: srgbColor(0.08, 0.08, 0.1),
   emissiveGain: 0,
   nightFactor: 0,
-  fogColor: [0.16, 0.18, 0.24],
+  fogColor: srgbColor(0.16, 0.18, 0.24),
   fogDensity: 0.004,
   fogHeightFalloff: 0.03,
   fogBaseY: 0,
@@ -80,11 +89,11 @@ const ENV = createEnvironment({
  * is two units on a side.
  */
 const shapes = new MeshBuilder();
-shapes.addBox([0, 1, 0], [1, 1, 1], [0.85, 0.45, 0.25]);
+shapes.addBox([0, 1, 0], [1, 1, 1], srgbColor(0.85, 0.45, 0.25));
 const cube = renderer.createMesh(shapes.build());
 
 const slab = new MeshBuilder();
-slab.addBox([0, -0.25, 0], [12, 0.25, 12], [0.3, 0.32, 0.36]);
+slab.addBox([0, -0.25, 0], [12, 0.25, 12], srgbColor(0.3, 0.32, 0.36));
 const ground = renderer.createMesh(slab.build());
 
 const spinner = new SceneNode();
@@ -136,7 +145,7 @@ startLoop({
 
     camera.updateMatrices(canvas.height > 0 ? canvas.width / canvas.height : 1);
 
-    renderer.beginFrame([0.05, 0.06, 0.09]);
+    renderer.beginFrame(CLEAR);
     renderer.bindMeshPass(camera, ENV);
     renderer.drawMesh(ground, stillness.worldMatrix);
     renderer.drawMesh(cube, spinner.worldMatrix);

package/dist/geometry/meshBuilder.d.ts

@@ -10,6 +10,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';
 }
 /**
  * CPU-side accumulator that merges axis-aligned boxes into one static mesh —

package/dist/geometry/meshBuilder.js

@@ -1,4 +1,5 @@
 import { GrowableF32, GrowableU32 } from './growable.js';
+import { decodeSrgbInPlace } from '../math/color.js';
 /**
  * The emissive colour of a vertex that has not been given one: negative, which no real
  * colour can be, so "inherit the surface's albedo" is representable without a second
@@ -914,14 +915,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/dist/index.d.ts

@@ -38,7 +38,7 @@ export type { CelestialSite, CelestialState } from './environment/celestialClock
 export { createDaylightPalette, createDaylightState, easeExposure, resolveDaylight, } from './environment/daylight.ts';
 export type { DaylightKey, DaylightPalette, DaylightState } from './environment/daylight.ts';
 export { TAU, DEG_TO_RAD, clamp, lerp, smoothstep, damp, dampTracking, angleDelta, dampAngle, 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';
 export { ThirdPersonCamera } from './render/thirdPersonCamera.ts';
@@ -250,7 +250,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';
@@ -264,6 +264,7 @@ export type { LoadTask, LoadSummary } from './core/loadTracker.ts';
 export { buildShellFill, shellSkin, shellFillMatrix, DEFAULT_SHELL_PROFILE, } from './geometry/shellFill.ts';
 export type { ShellStation, ShellFillOptions } from './geometry/shellFill.ts';
 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/dist/index.js

@@ -35,7 +35,7 @@ export { MessageQueue } from './core/messageQueue.js';
 export { celestialStateAt, createCelestialState, moonIllumination, } from './environment/celestialClock.js';
 export { createDaylightPalette, createDaylightState, easeExposure, resolveDaylight, } from './environment/daylight.js';
 export { TAU, DEG_TO_RAD, clamp, lerp, smoothstep, damp, dampTracking, angleDelta, dampAngle, wrapAngle, lerpAngle, } from './math/scalar.js';
-export { hslToRgb, mixColor, mixColorInto, scaleColor } from './math/color.js';
+export { decodeSrgbInPlace, hslToRgb, mixColor, mixColorInto, scaleColor, srgbColor, srgbToLinear, } from './math/color.js';
 export { Camera } from './render/camera.js';
 export { ThirdPersonCamera } from './render/thirdPersonCamera.js';
 export { CinematicCamera } from './render/cinematicCamera.js';
@@ -305,7 +305,7 @@ export { describeGpu } from './render/gpuCapability.js';
 export { DEFAULT_POINT_LIGHT_VIEW_RANGE, createPointLightBuffer, selectGridLights, selectPointLights, } from './render/pointLightSelection.js';
 export { LIGHT_GRID_MAX_CELLS, createLightGrid, gatherLights } from './render/lightGrid.js';
 export { createFlame, flameFrequencyHz, updateFlame } from './render/flameLight.js';
-export { computeLightMatrix } from './render/lightMatrix.js';
+export { computeLightMatrix, computeLightMatrixForBounds } from './render/lightMatrix.js';
 export { PlumeRenderer } from './render/plumeRenderer.js';
 export { createEnvironment } from './render/backend/webgl2/renderer.js';
 export { TrampleField, TRAMPLE_SLOTS } from './render/trample.js';
@@ -337,6 +337,7 @@ export { buildShellFill, shellSkin, shellFillMatrix, DEFAULT_SHELL_PROFILE, } fr
  * 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.js';
+export { interfaceGrade } from './render/passGrade.js';
 export { PLUME_VERT, FIRE_FRAG } from './render/shaders/fire.js';
 export { ARCANE_FRAG } from './render/shaders/arcane.js';
 export { SMOKE_FRAG } from './render/shaders/smoke.js';

package/dist/math/color.d.ts

@@ -6,3 +6,28 @@ export declare function mixColor(a: Vec3, b: Vec3, t: number): Vec3;
 /** In-place `mixColor` for per-frame use — allocating here would be a hot-path bug. */
 export declare function mixColorInto(out: Vec3, a: Vec3, b: Vec3, t: number): void;
 export declare function scaleColor(color: Vec3, factor: number): Vec3;
+/**
+ * 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 declare function srgbColor(r: number, g: number, b: number): Vec3;
+/**
+ * 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 declare function decodeSrgbInPlace(values: Float32Array): Float32Array;
+/**
+ * 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 declare function srgbToLinear(value: number): number;

package/dist/math/color.js

@@ -33,3 +33,40 @@ export function mixColorInto(out, a, b, t) {
 export function scaleColor(color, factor) {
     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, g, b) {
+    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) {
+    for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+        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) {
+    // 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/dist/render/backend/webgl2/renderer.d.ts

@@ -1304,6 +1304,8 @@ export declare class WebGL2Renderer implements RendererApi {
     private warnedOverlayBlocks;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
     private probePassActive;
+    /** `clearOf`'s scratch: a clear colour as the open target takes it. */
+    private readonly gradedClear;
     /**
      * 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.
@@ -2561,7 +2563,9 @@ export declare 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
@@ -2569,15 +2573,24 @@ export declare 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;
-    private gradeExposure;
+    private passGrade;
+    private passGradeExposure;
+    /** Whether the frame's resolve applies the transform, so the passes before it draw linear. */
+    private resolveGrades;
+    /**
+     * 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;
     drawSdfText(handle: SdfTextRenderer, model: Float32Array, color: Vec3, opacity: number): void;
     /** Release an SDF text label. Takes no context; see `disposeText`. */
     disposeSdfText(handle: SdfTextRenderer): void;