@driftengine/core 4.12.0 → 4.13.0

package/src/render/shaders/sky.ts

@@ -1,4 +1,5 @@
 import { glslFarDepth } from '../depthConvention.ts';
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
 /**
  * Procedural gradient sky drawn as a single attribute-less fullscreen triangle.
  * Ray direction is reconstructed per-fragment from the inverse view-projection,
@@ -77,6 +78,7 @@ uniform vec3 uUnderwaterColor;
 uniform float uUnderwaterFactor;
 
 out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
 
 float hash21(vec2 p) {
   return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
@@ -273,6 +275,8 @@ void main() {
   float waterLight = mix(0.62, 1.08, clamp(dir.y * 0.5 + 0.5, 0.0, 1.0));
   col = mix(col, uUnderwaterColor * waterLight, uUnderwaterFactor);
 
-  outColor = vec4(col, 1.0);
+  /* Graded where nothing after this will grade it, as every pass is: its colours are the same
+     light as the fog the world fades into. 0 in a probe's face, whose cube stores radiance. */
+  outColor = vec4(applyOutputTransform(col), 1.0);
 }
 `;

package/src/render/shaders/smoke.ts

@@ -1,4 +1,5 @@
 import { FOG_GLSL } from './fog.ts';
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
 
 /**
  * Smoke: a column that rises, expands and dissipates. Shares the plume
@@ -22,6 +23,7 @@ uniform vec4 uClipPlane;
 uniform int uClipEnabled;
 
 out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
 
 float hash21(vec2 p) {
   return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
@@ -84,6 +86,7 @@ void main() {
   float fog = mediumFog(vDistance, vWorldPos.y);
   col = mix(col, atmosphereColor, fog);
   float alpha = clamp(density * 0.95, 0.0, 1.0) * emerge * dissipate * 0.13;
-  outColor = vec4(col, alpha * (1.0 - fog));
+  /* Graded where nothing after this will grade it, as every pass is. The alpha is coverage. */
+  outColor = vec4(applyOutputTransform(col), alpha * (1.0 - fog));
 }
 `;

package/src/render/shaders/text.ts

@@ -1,3 +1,4 @@
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
 /**
  * Screen-space 3D text.
  *
@@ -147,6 +148,7 @@ uniform float uGlow;
 uniform float uAlpha;
 
 out vec4 fragColor;
+${OUTPUT_TRANSFORM_GLSL}
 
 void main() {
   /*
@@ -161,5 +163,6 @@ void main() {
   vec3 lit = uColor * lambert;
   // The glow rides the arrival: brightest as a character lands, settling after.
   vec3 emissive = uColor * uGlow * (0.45 + 0.55 * vChar);
-  fragColor = vec4(lit + emissive, uAlpha);
+  /* Graded where nothing after this will grade it, as every pass is. The alpha is coverage. */
+  fragColor = vec4(applyOutputTransform(lit + emissive), uAlpha);
 }`;

package/src/render/shaders/water.ts

@@ -2,6 +2,7 @@ import { MAX_POINT_LIGHTS } from '../lightBudget.ts';
 import { MAX_WATER_REFLECTION_FILTER_TAPS } from '../renderQuality.ts';
 import { GERSTNER_GLSL } from './gerstner.ts';
 import { FOG_GLSL } from './fog.ts';
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
 
 /**
  * The sky-ocean, as an actual wave simulation rather than a tinted plane.
@@ -198,6 +199,7 @@ uniform sampler2D uReflectionMap;
 uniform int uReflectionEnabled;
 uniform vec2 uReflectionTexelSize;
 uniform int uReflectionFilterTaps;
+${OUTPUT_TRANSFORM_GLSL}
 
 const vec2 REFLECTION_FILTER[${MAX_WATER_REFLECTION_FILTER_TAPS}] = vec2[${MAX_WATER_REFLECTION_FILTER_TAPS}](
   vec2( 0.00,  0.00), vec2(-0.62, -0.31), vec2( 0.54,  0.43),
@@ -276,6 +278,14 @@ void main() {
   float dist = distance(vWorldPos, uCameraPos);
   float fog = mediumFog(dist, vWorldPos.y);
   col = mix(col, atmosphereColor, fog);
+  /*
+   * **Graded here, before the mirror is mixed in**, as every pass grades what it draws when
+   * nothing after it will: the mirror's own passes graded what it holds, so mixing first would put
+   * the curve on it twice. The air's colour, which stands in where the mirror shows nothing, is
+   * graded to meet it, as the sky behind it is.
+   */
+  col = applyOutputTransform(col);
+  vec3 gradedAir = applyOutputTransform(atmosphereColor);
 
   // Transparency is angle-dependent, like real water: looking down you see
   // straight through to the seabed, at grazing angles it turns reflective.
@@ -289,7 +299,7 @@ void main() {
   // Project the displaced surface into the mirrored camera. The Gerstner
   // displacement supplies broad distortion; the analytic normal adds the
   // smaller ripples that make reflected silhouettes move with each crest.
-  vec3 reflected = atmosphereColor;
+  vec3 reflected = gradedAir;
   float reflectionValid = 0.0;
   if (uReflectionEnabled != 0 && vReflectionClip.w > 0.0) {
     vec2 reflectionUv = vReflectionClip.xy / vReflectionClip.w * 0.5 + 0.5;
@@ -324,7 +334,7 @@ void main() {
       filterWeight += weight;
     }
     sceneReflection /= max(filterWeight, 0.001);
-    reflected = mix(atmosphereColor, sceneReflection, reflectionValid);
+    reflected = mix(gradedAir, sceneReflection, reflectionValid);
   }
   // The atmosphere-colour fallback preserves the old sky reflection when a
   // quality profile disables the extra scene pass. Foam scatters rather than

package/src/render/shaders/windStreaks.ts

@@ -1,3 +1,4 @@
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.ts';
 /**
  * Visible wind: streaks of dust and debris carried past the camera.
  *
@@ -117,6 +118,7 @@ in float vFade;
 in float vAlong;
 uniform vec3 uTint;
 out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
 
 void main() {
   // Tapered at both ends, so a streak reads as motion rather than as a stick.
@@ -125,6 +127,7 @@ void main() {
   float taper = sin(vAlong * 3.14159);
   float alpha = vFade * taper * taper * 0.13;
   if (alpha <= 0.002) discard;
-  outColor = vec4(uTint, alpha);
+  /* Graded where nothing after this will grade it, as every pass is. The alpha is coverage. */
+  outColor = vec4(applyOutputTransform(uTint), alpha);
 }
 `;

package/src/render/surfaceLayerLooks.ts

@@ -43,7 +43,7 @@ export interface SurfaceLayerLook {
 
 /** What an occlusion read at the mesh's own coordinates darkens, and how far. */
 export interface SurfaceMeshOcclusion {
-  /** 0 to 1: the surface times `mix(1, occlusion, strength)`. Absent: 1. */
+  /** 0 to 1: what `into` names times `mix(1, occlusion, strength)`. Absent: 1. */
   readonly strength?: number;
   /**
    * `'color'`, the default, darkens the blended colour, and so every light on it, the sun's too.
@@ -51,6 +51,18 @@ export interface SurfaceMeshOcclusion {
    * does, leaving the sun, the lamps and the reflections as they were.
    */
   readonly into?: 'color' | 'ambient';
+  /**
+   * The colour's own strength, from 0 up and past 1: the blended colour times
+   * `max(0, 1 − colorStrength × (1 − occlusion))`, which up to 1 is the `mix` above and past it
+   * darkens faster than the occlusion does. Absent: `strength` where `into` is the colour, and 0
+   * where it is the ambient light — so named beside `into: 'ambient'` it darkens both, each at its
+   * own strength, as a material taking its ambient occlusion and a darker colour from one map does.
+   *
+   * **What it gives up**: past 1 the colour is black wherever `1 − occlusion` reaches
+   * `1 / colorStrength`, and black under every light, the sun's too, which is what such a material
+   * asks for and what an ambient occlusion alone would never do.
+   */
+  readonly colorStrength?: number;
   /** The range the occlusion's red is spread over, from its 0 to its 1. Absent: `[0, 1]`. */
   readonly range?: readonly [number, number];
 }
@@ -75,7 +87,8 @@ export function asksLayerLooks<Texture>(
     layers.extrasAt !== undefined ||
     layers.looks !== undefined ||
     layers.repeats.some((repeat) => typeof repeat !== 'number') ||
-    occlusionOf(layers.meshOcclusion).strength > 0
+    colorOcclusion(layers.meshOcclusion) > 0 ||
+    ambientOcclusion(layers.meshOcclusion) > 0
   );
 }
 
@@ -85,15 +98,15 @@ export function asksLayerLooks<Texture>(
  * `LAYER_LOOKS` on, so it must draw exactly as it did before.
  *
  * - **0 to 7**: the array layer each layer reads, base first (layer `i` where not given); where the
- *   maps beyond the layers start (the layer count where not given); the mesh occlusion's strength,
- *   and what it darkens, 0 the colour and 1 the ambient light.
+ *   maps beyond the layers start (the layer count where not given); the mesh occlusion's strength
+ *   on the colour, from 0 up, and on the ambient light, 0 to 1.
  * - **8 to 47**: two vectors a layer, base first: its tint and its normal strength, then its
  *   roughness range and its metalness range.
  * - **48 to 59**: each layer's specular (−1 for the surface's own), each layer's repeat down (its
  *   repeat across where it gave one number), and the range the occlusion is spread over.
  *
  * An array layer that is not a whole number at or above 0 reads layer `i`; a start that is not one
- * is the count; a strength is held to 0..1; a tint channel, a normal strength or a specular that is
+ * is the count; a strength is held to 0..1, but for the colour's own, which is held at or above 0; a tint channel, a normal strength or a specular that is
  * not a number at or above 0 is the identity; a repeat down that is not a positive number is the
  * repeat across; a range end that is not a number is the identity's end.
  */
@@ -105,9 +118,9 @@ export function packLayerLooks<Texture>(
   const picks = layers?.arrayLayers;
   for (let i = 0; i < MAX_SURFACE_LAYERS; i++) out[i] = arrayLayer(picks?.[i], i);
   out[5] = arrayLayer(layers?.extrasAt, count);
-  const occlusion = occlusionOf(layers?.meshOcclusion);
-  out[6] = occlusion.strength;
-  out[7] = occlusion.into === 'ambient' ? 1 : 0;
+  const occlusion = layers?.meshOcclusion;
+  out[6] = colorOcclusion(occlusion);
+  out[7] = ambientOcclusion(occlusion);
   for (let i = 0; i < MAX_SURFACE_LAYERS; i++) {
     const look = layers?.looks?.[i] ?? null;
     const at = 8 + i * 8;
@@ -124,18 +137,36 @@ export function packLayerLooks<Texture>(
     const acrossIt = positiveOr(across(repeat), 1);
     out[53 + i] = typeof repeat === 'object' ? positiveOr(repeat[1], acrossIt) : acrossIt;
   }
-  out[58] = finiteOr(occlusion.range?.[0], 0);
-  out[59] = finiteOr(occlusion.range?.[1], 1);
+  const range = typeof occlusion === 'object' ? occlusion.range : undefined;
+  out[58] = finiteOr(range?.[0], 0);
+  out[59] = finiteOr(range?.[1], 1);
+}
+
+/** The strength `meshOcclusion` names, held to 0..1: a number's own, an object's or 1, and 0 for none. */
+function occlusionStrength(occlusion: number | SurfaceMeshOcclusion | undefined): number {
+  const strength =
+    typeof occlusion === 'number'
+      ? occlusion
+      : occlusion === undefined
+        ? 0
+        : (occlusion.strength ?? 1);
+  return Number.isFinite(strength) ? Math.min(Math.max(strength, 0), 1) : 0;
+}
+
+/** How hard the occlusion darkens the colour: its own strength where named, else `into`'s. */
+function colorOcclusion(occlusion: number | SurfaceMeshOcclusion | undefined): number {
+  if (typeof occlusion === 'object' && occlusion.colorStrength !== undefined)
+    return atLeastZero(occlusion.colorStrength, 0);
+  return typeof occlusion === 'object' && occlusion.into === 'ambient'
+    ? 0
+    : occlusionStrength(occlusion);
 }
 
-/** The number form of `meshOcclusion` as the object form, the strength held to 0..1. */
-function occlusionOf(
-  occlusion: number | SurfaceMeshOcclusion | undefined,
-): SurfaceMeshOcclusion & { readonly strength: number } {
-  const given =
-    typeof occlusion === 'number' ? { strength: occlusion } : (occlusion ?? { strength: 0 });
-  const strength = given.strength ?? 1;
-  return { ...given, strength: Number.isFinite(strength) ? Math.min(Math.max(strength, 0), 1) : 0 };
+/** How hard the occlusion darkens the ambient light: its strength where that is its target. */
+function ambientOcclusion(occlusion: number | SurfaceMeshOcclusion | undefined): number {
+  return typeof occlusion === 'object' && occlusion.into === 'ambient'
+    ? occlusionStrength(occlusion)
+    : 0;
 }
 
 function arrayLayer(value: number | undefined, otherwise: number): number {

package/src/render/surfaceLayers.ts

@@ -112,8 +112,8 @@ export interface SurfaceLayers<Texture> {
    * layers and any mask or added mask the array carries — darkening the surface by a strength from 0
    * to 1: the large shading of a cliff that layers repeating across it cannot carry, as
    * `meshNormal` carries its shape. A number is that strength, darkening the blended colour; the
-   * object form also chooses what it darkens and the range its red is spread over. Absent or 0:
-   * none.
+   * object form also chooses what it darkens, the colour and the ambient light at strengths of their
+   * own, and the range its red is spread over. Absent or 0: none.
    */
   readonly meshOcclusion?: number | SurfaceMeshOcclusion;
 }

package/src/render/textRenderer.ts

@@ -80,11 +80,17 @@ export class TextRenderer {
     originY: number,
     style: TextStyle,
     timeSec: number,
+    /** The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+    outputTransform = 0,
+    outputExposure = 1,
   ): boolean {
     if (this.layout.instanceCount === 0 || style.alpha <= 0) return false;
     const gl = this.gl;
 
     gl.useProgram(this.program);
+    const grade = this.uniforms['uOutputTransform'];
+    if (grade !== undefined) gl.uniform1i(grade, outputTransform);
+    setFloat(gl, this.uniforms['uOutputExposure'], outputExposure);
     gl.bindVertexArray(this.vao);
 
     /*

package/src/render/vertexDefaults.ts

@@ -119,7 +119,7 @@ export const OUTPUT_TRANSFORM_CODE: Readonly<Record<string, number>> = {
 /**
  * The code a **forward** pass grades with: the transform's own, except `filmic`, which only the
  * composite carries the constants for, and which a pass grading itself therefore draws as `aces`.
- * Both backends' `gradeCode` read this, so neither can hand a forward stage a code it lacks.
+ * `passGrade.ts` reads this for both backends, so neither can hand a forward stage a code it lacks.
  */
 export function forwardTransformCode(transform: string): number {
   return transform === 'filmic' ? 2 : (OUTPUT_TRANSFORM_CODE[transform] ?? 0);

package/src/render/waterRenderer.ts

@@ -253,10 +253,15 @@ export class WaterRenderer {
     lightFalloff: 'smooth' | 'inverseSquare' = 'smooth',
     windX = 0,
     windZ = 0,
+    outputTransform = 0,
+    outputExposure = 1,
   ): void {
     const u = this.uniforms;
     const reflectionReady = reflection?.isReadyFor(settings.level) ?? false;
     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);
     gl.uniformMatrix4fv(
       u['uReflectionViewProj'] ?? null,

package/src/render/windStreakRenderer.ts

@@ -86,6 +86,9 @@ export class WindStreakRenderer {
     tint: Vec3,
     /** True when the camera is below the waterline. */
     submerged = false,
+    /** The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+    outputTransform = 0,
+    outputExposure = 1,
   ): boolean {
     /* Chosen in `windStreakDraw.ts` so both backends show the same weather. */
     const settled = resolveWindStreaks(
@@ -111,6 +114,8 @@ export class WindStreakRenderer {
     gl.uniform1f(u['uCellSize'] ?? null, this.cellSize);
     gl.uniform1f(u['uTime'] ?? null, timeSeconds);
     gl.uniform3fv(u['uTint'] ?? null, tint);
+    gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
+    gl.uniform1f(u['uOutputExposure'] ?? null, outputExposure);
 
     gl.enable(gl.BLEND);
     blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);