@driftengine/core 4.13.3 → 4.13.5

package/src/render/shaders/localExposure.ts

@@ -26,7 +26,7 @@
  * whose drama is the contrast itself: a single shaft into a dark room wants the room dark, and the
  * strength is the caller's for that reason.
  */
-import { METER_GRID, METER_MAX_LOG2, METER_MIN_LOG2, METER_TAPS } from './exposure.ts';
+import { ADAPTED_KEY, METER_GRID, METER_MAX_LOG2, METER_MIN_LOG2, METER_TAPS } from './exposure.ts';
 
 /** Bands of log luminance, and how many stops each is wide. */
 export const LOCAL_BINS = 10;
@@ -82,15 +82,27 @@ void main() {
 `;
 
 /**
- * The composite's half. Needs `AUTO_EXPOSURE_GLSL` before it, for the held brightness.
+ * The composite's half. Needs `AUTO_EXPOSURE_GLSL` and `uOutputExposure` before it, for the held
+ * brightness and the frame's exposure.
  *
  * A block is read clamped half a texel inside its own tiles, so the filter never reaches into the
  * neighbouring band's block. Every fetch is at level zero: the grid has one level, and the branch
  * on the strength above them is uniform but the pixel's band is not.
  */
 export const LOCAL_EXPOSURE_GLSL = `
-/** How far each region is brought toward the frame, 0 to 1. 0 is off and the whole of the off path. */
+/** Above 0 when regions move at all: 0 is off and the whole of the off path. */
 uniform float uLocalExposure;
+/**
+ * How regions move, as \`resolveLocalExposure\` packs it: the share of a region's stops from the
+ * pivot it keeps above the pivot and below it, each less one; the share of a pixel's own stops
+ * from its region it keeps, less one; and how far a region's level leans toward its tile's mean.
+ */
+uniform vec4 uLocalShape;
+/**
+ * What they move about: 1 for the frame's held brightness, 0 for middle grey at the frame's
+ * exposure; stops added to it; and the furthest a region moves either way.
+ */
+uniform vec4 uLocalPivot;
 /** The bilateral grid: a block of tiles per band of brightness, and one of the tiles' means. */
 uniform highp sampler2D uExposureLocal;
 
@@ -109,9 +121,15 @@ float localExposureGain(vec2 uv, vec3 light) {
   vec2 banded = mix(localBlock(uv, lower), localBlock(uv, upper), clamp(b - lower, 0.0, 1.0));
   float tileMean = localBlock(uv, ${LOCAL_BINS.toFixed(1)}).r;
   float bilateral = banded.y > 1e-3 ? banded.x / banded.y : tileMean;
-  float local = mix(bilateral, tileMean, ${LOCAL_BLURRED_BLEND.toFixed(1)});
-  float stops = uLocalExposure * (held - local);
-  return exp2(clamp(stops, -${LOCAL_RANGE_STOPS.toFixed(1)}, ${LOCAL_RANGE_STOPS.toFixed(1)}));
+  float local = mix(bilateral, tileMean, uLocalShape.w);
+  /* Middle grey at the frame's exposure, in the scene light the grid measured. */
+  float pivot = uLocalPivot.x > 0.5
+    ? held
+    : ${Math.log2(ADAPTED_KEY).toFixed(6)} - log2(max(autoExposureGain() * uOutputExposure, 1e-8));
+  pivot += uLocalPivot.y;
+  float keep = local > pivot ? uLocalShape.x : uLocalShape.y;
+  float stops = (local - pivot) * keep + (pixel - local) * uLocalShape.z;
+  return exp2(clamp(stops, -uLocalPivot.z, uLocalPivot.z));
 }
 `;
 
@@ -148,6 +166,97 @@ export function localExposureGain(localLog2: number, heldLog2: number, strength:
   return 2 ** clamp(stops, -LOCAL_RANGE_STOPS, LOCAL_RANGE_STOPS);
 }
 
+/**
+ * Local exposure as a shape rather than one strength: each region turned about middle grey at the
+ * frame's exposure, the real-time form most engines expose.
+ *
+ * A region's level is its stops from that grey: it keeps `highlightContrast` of them where it is
+ * brighter and `shadowContrast` where it is darker, so 1 leaves it where it is and 0 brings it all
+ * the way to grey. A pixel keeps `detail` of its own stops from its region, so above 1 sharpens the
+ * texture inside a region a curve would have flattened. **What it gives up** is the held level the
+ * one-number form turns about: a frame metered far from grey, a night, is pulled toward grey rather
+ * than toward itself, which is what the form is for and what a caller holding a night dark leaves
+ * off.
+ */
+export interface LocalExposureOptions {
+  /** The share of a region's stops above middle grey it keeps. 1 is none moved. */
+  readonly highlightContrast: number;
+  /** The share it keeps below. */
+  readonly shadowContrast: number;
+  /** The share of a pixel's own stops from its region it keeps. Default 1. */
+  readonly detail?: number;
+  /** How far a region's level leans from its bilateral band toward its tile's mean. Default 0.4. */
+  readonly blurredBlend?: number;
+  /** Stops added to middle grey, the level regions turn about. Default 0. */
+  readonly middleGreyBias?: number;
+  /** The furthest a region moves either way, in stops. Default 8. */
+  readonly range?: number;
+}
+
+/** Floats `resolveLocalExposure` fills: `uLocalShape`, then `uLocalPivot`. */
+export const LOCAL_EXPOSURE_FLOATS = 8;
+
+/**
+ * Either form of `setLocalExposure` as the composite reads it, into `out`, and whether regions move
+ * at all. The one number is the shape it always was, both shares `1 − strength` about the held
+ * level, at most three stops: so a strength draws what it drew, to the bit.
+ */
+export function resolveLocalExposure(
+  setting: number | LocalExposureOptions,
+  out: Float32Array,
+): boolean {
+  if (typeof setting === 'number') {
+    const strength = clampLocalExposure(setting);
+    out[0] = -strength;
+    out[1] = -strength;
+    out[2] = 0;
+    out[3] = LOCAL_BLURRED_BLEND;
+    out[4] = 1;
+    out[5] = 0;
+    out[6] = LOCAL_RANGE_STOPS;
+    out[7] = 0;
+    return strength > 0;
+  }
+  const share = (value: number | undefined, fallback: number): number =>
+    value !== undefined && Number.isFinite(value) ? Math.max(0, value) : fallback;
+  const highlight = share(setting.highlightContrast, 1);
+  const shadow = share(setting.shadowContrast, 1);
+  const detail = share(setting.detail, 1);
+  out[0] = highlight - 1;
+  out[1] = shadow - 1;
+  out[2] = detail - 1;
+  out[3] = clamp(share(setting.blurredBlend, LOCAL_BLURRED_BLEND), 0, 1);
+  out[4] = 0;
+  const bias = setting.middleGreyBias;
+  out[5] = bias !== undefined && Number.isFinite(bias) ? bias : 0;
+  out[6] = share(setting.range, 8);
+  out[7] = 0;
+  return highlight !== 1 || shadow !== 1 || detail !== 1;
+}
+
+/**
+ * A pixel's gain from either form, as the composite computes it: `pixelLog2` its own level,
+ * `localLog2` its region's before the blend, `tileMean` its tile's, `heldLog2` the frame's held
+ * brightness and `exposure` the frame's exposure, gain and all; `shape` is `resolveLocalExposure`'s.
+ */
+export function localExposureShapedGain(
+  pixelLog2: number,
+  localLog2: number,
+  tileMean: number,
+  heldLog2: number,
+  exposure: number,
+  shape: ArrayLike<number>,
+): number {
+  const local = localLog2 + (tileMean - localLog2) * (shape[3] as number);
+  const pivot =
+    ((shape[4] as number) > 0.5 ? heldLog2 : Math.log2(ADAPTED_KEY) - Math.log2(exposure)) +
+    (shape[5] as number);
+  const keep = local > pivot ? (shape[0] as number) : (shape[1] as number);
+  const stops = (local - pivot) * keep + (pixelLog2 - local) * (shape[2] as number);
+  const range = shape[6] as number;
+  return 2 ** clamp(stops, -range, range);
+}
+
 /** A local exposure strength as the shader takes it: 0 to 1, anything else off. */
 export function clampLocalExposure(strength: number): number {
   return Number.isFinite(strength) ? clamp(strength, 0, 1) : 0;

package/src/render/shaders/particle.ts

@@ -334,8 +334,10 @@ void main() {
   }
 
   vec3 shaded = vColor * lit;
-  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
-  outColor = vec4(applyOutputTransform(mix(shaded, mediumColor(), fog)), mask * vAlpha);
+  float dist = distance(vWorldPos, uCameraPos);
+  float fog = mediumFog(dist, vWorldPos.y);
+  vec3 glow = mediumGlow(dist, vWorldPos.y, normalize(vWorldPos - uCameraPos));
+  outColor = vec4(applyOutputTransform(mix(shaded, mediumColor(), fog) + glow), mask * vAlpha);
 }
 `;
 
@@ -463,8 +465,9 @@ void main() {
 
   vec3 color = vColor;
   if (uFogEnabled != 0) {
-    float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
-    color = mix(color, mediumColor(), fog);
+    float dist = distance(vWorldPos, uCameraPos);
+    float fog = mediumFog(dist, vWorldPos.y);
+    color = mix(color, mediumColor(), fog) + mediumGlow(dist, vWorldPos.y, normalize(vWorldPos - uCameraPos));
   }
   /*
    * A real alpha blend (SRC_ALPHA, ONE_MINUS_SRC_ALPHA) rather than spark's energy-in-colour
@@ -563,8 +566,9 @@ void main() {
   if (alpha <= 0.001) discard;
   vec3 color = vColor * image.rgb;
   if (uFogEnabled != 0) {
-    float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
-    color = mix(color, mediumColor(), fog);
+    float dist = distance(vWorldPos, uCameraPos);
+    float fog = mediumFog(dist, vWorldPos.y);
+    color = mix(color, mediumColor(), fog) + mediumGlow(dist, vWorldPos.y, normalize(vWorldPos - uCameraPos));
   }
   outColor = vec4(applyOutputTransform(color), alpha);
 }

package/src/render/shaders/scatter.ts

@@ -206,9 +206,11 @@ void main() {
   float ndl = abs(dot(n, uDirectionalDir));
   vec3 lit = vColor * (uAmbient + uDirectionalColor * ndl);
 
-  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
+  float dist = distance(vWorldPos, uCameraPos);
+  float fog = mediumFog(dist, vWorldPos.y);
+  vec3 glow = mediumGlow(dist, vWorldPos.y, normalize(vWorldPos - uCameraPos));
 
   /* Graded where nothing after this will grade it, as every pass is: the same light as the ground. */
-  outColor = vec4(applyOutputTransform(mix(lit, mediumColor(), fog)), 1.0);
+  outColor = vec4(applyOutputTransform(mix(lit, mediumColor(), fog) + glow), 1.0);
 }
 `;

package/src/render/shaders/water.ts

@@ -277,7 +277,8 @@ void main() {
 
   float dist = distance(vWorldPos, uCameraPos);
   float fog = mediumFog(dist, vWorldPos.y);
-  col = mix(col, atmosphereColor, fog);
+  vec3 glow = mediumGlow(dist, vWorldPos.y, normalize(vWorldPos - uCameraPos));
+  col = mix(col, atmosphereColor, fog) + glow;
   /*
    * **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

package/src/render/surfaceModel.ts

@@ -28,12 +28,20 @@ export interface AnisotropicModel {
   readonly strength: number;
   /** Radians, turning the stretch's direction from the tangent toward the bitangent. */
   readonly rotation: number;
+  /**
+   * How far the highlight is lifted where it is bright: the distribution `D` becomes
+   * `D + min(3, D^1.5) · lift`, which is how a brushed finish that reads as polished along its
+   * streak is authored. Where a model map is bound its alpha scales it texel by texel, so a map
+   * storing a tenth of a region's lift takes `lift: 10`. 0, the default, is none.
+   */
+  readonly lift: number;
 }
 
 /**
  * Hair: three lobes along the strand, which is the mesh's tangent, running from root to tip
- * (`hairLobes.ts`). A model map's green turns each strand's tilt by up to half of it either way and
- * its blue is occlusion.
+ * (`hairLobes.ts`). A model map's red is the strand's specular, twice it scaling the reflected lobe
+ * (0.5 is the lobe as drawn), its green turns each strand's tilt by up to half of it either way and
+ * its blue is occlusion; `directionOffset` names a layer of it holding each strand's direction.
  */
 export interface HairModel {
   readonly kind: 'hair';
@@ -47,6 +55,15 @@ export interface HairModel {
   readonly scatter: number;
   /** How strongly light from behind glows through: the transmitted lobe. */
   readonly backlit: number;
+  /**
+   * Where the model map holds each strand's direction: this many layers past the layer the texel's
+   * other channels are read at, so a model map of one layer with its directions in the next takes
+   * 1. The direction is in the surface's tangent frame, red along the tangent, green along the
+   * bitangent and blue out of the surface along its normal, each −1 to 1 packed as a normal map
+   * packs them, and the strand runs along it rather than along the tangent: a card's strands can
+   * lean out of its plane. 0, the default, is none.
+   */
+  readonly directionOffset: number;
 }
 
 /** Skin: light scattered beneath the surface, reddening its terminator and its thin parts. */
@@ -137,10 +154,11 @@ function unit(model: string, name: string, v: Vec3): Vec3 {
 
 /** Brushed metal and the like, after glTF's `KHR_materials_anisotropy`: a strength and a turn. */
 export function anisotropicModel(
-  options: { strength?: number; rotation?: number } = {},
+  options: { strength?: number; rotation?: number; lift?: number } = {},
 ): AnisotropicModel {
   return Object.freeze({
     kind: 'anisotropic',
+    lift: check('anisotropicModel', 'lift', options.lift ?? 0, 0, 100),
     strength: check('anisotropicModel', 'strength', options.strength ?? 1, 0, 1),
     rotation: check(
       'anisotropicModel',
@@ -154,13 +172,26 @@ export function anisotropicModel(
 
 /** Hair, along the mesh's tangent from root to tip. A tilt of 3°, within the 2.5° to 5° measured. */
 export function hairModel(
-  options: { shift?: number; scatter?: number; backlit?: number } = {},
+  options: { shift?: number; scatter?: number; backlit?: number; directionOffset?: number } = {},
 ): HairModel {
+  const directionOffset = check(
+    'hairModel',
+    'directionOffset',
+    options.directionOffset ?? 0,
+    0,
+    255,
+  );
+  if (!Number.isInteger(directionOffset)) {
+    throw new Error(
+      `hairModel: directionOffset must be a whole number of layers, not ${directionOffset}`,
+    );
+  }
   return Object.freeze({
     kind: 'hair',
     shift: check('hairModel', 'shift', options.shift ?? (3 * Math.PI) / 180, -0.5, 0.5),
     scatter: check('hairModel', 'scatter', options.scatter ?? 0.7, 0, 1),
     backlit: check('hairModel', 'backlit', options.backlit ?? 1, 0, 4),
+    directionOffset,
   });
 }
 
@@ -246,8 +277,8 @@ export function lightmapModel(options: { region?: LightmapRegion } = {}): Lightm
  * models that read it leave free; skin, hair and the eye shade their own highlights and never do.
  *
  * - standard (null): − · −, −, physical, −
- * - anisotropic: strength, cos and sin of the rotation · −, −, physical, map
- * - hair: shift, scatter, backlit, − · −, −, −, map
+ * - anisotropic: strength, cos and sin of the rotation, lift · −, −, physical, map
+ * - hair: shift, scatter, backlit, direction offset · −, −, −, map
  * - skin: the scatter colour, radius / `SKIN_MEAN_EXIT` · transmission, profile, −, map
  * - eye: iris radius, iris depth, ior, cornea roughness · the axis, map
  * - lightmap: the region's scale and bias · −, −, physical, map
@@ -270,12 +301,16 @@ export function packModel(
       out[0] = model.strength;
       out[1] = Math.cos(model.rotation);
       out[2] = Math.sin(model.rotation);
+      /* The lift, which the map's alpha scales texel by texel; 0, and a missing field, is none. */
+      out[3] = model.lift ?? 0;
       out[6] = highlight;
       return;
     case 'hair':
       out[0] = model.shift;
       out[1] = model.scatter;
       out[2] = model.backlit;
+      /* A layer offset the shader adds to the texel's own; 0 is none, and so is a missing field. */
+      out[3] = model.directionOffset ?? 0;
       return;
     case 'skin':
       out[0] = model.scatterColor[0];