@driftengine/core 4.8.6 → 4.9.0

package/src/render/fog.ts

@@ -40,7 +40,10 @@ export interface FogOptions {
   readonly underwaterFactor: number;
   /** `MEDIUM_FOG` integrates a medium; `LINEAR_FOG` ramps between near and far. */
   readonly mode: number;
-  /** Linear mode only: where haze begins, and where it is total. */
+  /**
+   * Where haze begins: the ramp's start in linear mode, and in the medium the distance along the
+   * ray it is integrated from (`Atmosphere.fogStart`), 0 at the camera.
+   */
   readonly near: number;
   readonly far: number;
 }
@@ -88,13 +91,26 @@ export function mediumFog(fog: FogOptions, dist: number, pointY: number): number
     return mix(ramp, 1 - Math.pow(2, -wetLinear * wetLinear * 1.442695), fog.underwaterFactor);
   }
 
+  /*
+   * **Where the medium begins along the ray**, `near` — the linear mode's slot, which this mode
+   * never read before `Atmosphere.fogStart`. The ray is integrated from that point on: the density
+   * there, carried over what is left of the ray. At a start of 0 every term below is the one it
+   * always was, so a world that sets none draws the same bits.
+   */
+  const start = Math.min(fog.near, dist);
+  const before = dist > 0 ? start / dist : 0;
   const t = (pointY - fog.eyeY) * fog.heightFalloff;
+  const rest = t * (1 - before);
   /*
    * `(1 - e^-t)/t`, which tends to 1 as the ray levels out. **Guarded rather than branched**: at
    * `t = 0` the quotient is 0/0, and 1e-4 of a scale height is 8 mm.
    */
-  const denom = Math.abs(t) < 1e-4 ? 1e-4 : t;
-  const air = 1 - Math.exp((-fog.density * dist * (1 - Math.exp(-denom))) / denom);
+  const denom = Math.abs(rest) < 1e-4 ? 1e-4 : rest;
+  const air =
+    1 -
+    Math.exp(
+      (-fog.density * Math.exp(-t * before) * (dist - start) * (1 - Math.exp(-denom))) / denom,
+    );
   if (fog.underwaterFactor <= 0) return air;
   /* Water is its own medium and keeps its own curve, so crossing the surface changes nothing
      about how the water column reads. */

package/src/render/frame/resources.ts

@@ -30,6 +30,12 @@ export const FRAME_RESOURCES = [
   'aoTarget',
   'depthSnapshot',
   'inset',
+  /*
+   * The frame's colour as a registered pass reads it: a copy taken at that pass's draw, so reading
+   * it constrains no attachment's store, as `depthSnapshot` does not. Last, so no bit before it
+   * moved when it arrived.
+   */
+  'colorSnapshot',
 ] as const;
 
 export type FrameResource = (typeof FRAME_RESOURCES)[number];

package/src/render/frameReflections.ts

@@ -0,0 +1,72 @@
+/**
+ * Reflections traced through the frame's own materials: `RenderQuality.screenSpaceReflections`.
+ *
+ * **Every opaque lit surface reflects the frame by its own material**, where `ReflectiveSurface`
+ * reflects it by a box's: the lit stage leaves, per pixel, how much of the environment it showed and
+ * at what roughness (`shaders/flat/reflectionSurface.ts`), and a ray marched against the frame's
+ * depth swaps that share for what it finds — so a glossy panel mirrors the figures on it and the
+ * matte panel beside it barely does, in one mesh with one material map. Past `maxRoughness` a
+ * surface keeps the probes' reflection alone, which is what a march cannot do better than: a rough
+ * lobe wants many rays, and one ray blurred is only a fair stand-in for a narrow one.
+ *
+ * **What a surface reflects is what the lit stage already reflected**: a metal by its metalness, a
+ * dielectric where `setSurfaceReflectivity` or its material asks for one. A surface that reflects
+ * no environment reflects no frame either, which is what keeps the two from disagreeing.
+ */
+
+/** How the frame's materials reflect it. Every field optional; see `DEFAULT_FRAME_REFLECTIONS`. */
+export interface FrameReflections {
+  /** The roughness past which a surface reflects the probes alone, faded over the last quarter. */
+  readonly maxRoughness?: number;
+  /** How far a ray travels before it gives up, in metres. */
+  readonly reachM?: number;
+  /** How deep a depth sample is believed to be, in metres. See `ScreenSpaceMarch.thicknessM`. */
+  readonly thicknessM?: number;
+  /** Samples along a ray, at most 32. */
+  readonly steps?: number;
+  /** How far a fully rough reflection is smeared, as a share of the frame's height. */
+  readonly blur?: number;
+}
+
+export type ResolvedFrameReflections = Required<FrameReflections>;
+
+/** The march `ReflectiveSurface` defaults to, a ceiling at satin, and a smear of 3% of the frame. */
+export const DEFAULT_FRAME_REFLECTIONS: ResolvedFrameReflections = Object.freeze({
+  maxRoughness: 0.6,
+  reachM: 8,
+  thicknessM: 0.25,
+  steps: 24,
+  blur: 0.03,
+});
+
+const finite = (value: number | undefined, fallback: number): number =>
+  value !== undefined && Number.isFinite(value) ? value : fallback;
+
+/**
+ * The option as the renderers read it: null where it is off, and every number held where the
+ * shader can use it — a ceiling above zero, a reach and a thickness above zero, a whole number of
+ * steps from 1 to 32, and a blur from none to a fifth of the frame. Clamped rather than refused,
+ * since a quality option is read at construction and a renderer that threw there would draw nothing.
+ */
+export function resolveFrameReflections(
+  asked: boolean | FrameReflections | undefined,
+): ResolvedFrameReflections | null {
+  if (asked === undefined || asked === false) return null;
+  const given = asked === true ? {} : asked;
+  const d = DEFAULT_FRAME_REFLECTIONS;
+  return {
+    maxRoughness: Math.min(Math.max(finite(given.maxRoughness, d.maxRoughness), 0.01), 1),
+    reachM: Math.max(finite(given.reachM, d.reachM), 0.01),
+    thicknessM: Math.max(finite(given.thicknessM, d.thicknessM), 0.001),
+    steps: Math.min(Math.max(Math.round(finite(given.steps, d.steps)), 1), 32),
+    blur: Math.min(Math.max(finite(given.blur, d.blur), 0), 0.2),
+  };
+}
+
+/** What a renderer says once where the frame cannot carry these reflections, and why. */
+export function frameReflectionsRefused(reason: string): string {
+  return (
+    `screenSpaceReflections is not drawn: ${reason}. Surfaces keep the probes' reflection; ` +
+    'the trace needs `screenEffects` and `hdrScene`, and a frame of one sample.'
+  );
+}

package/src/render/gi/bounceLights.ts

@@ -23,15 +23,20 @@
  */
 
 import type { PointLightSet } from '../lightBudget.ts';
-import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from '../clusteredLights.ts';
+import {
+  POINT_LIGHT_COS_INNER,
+  POINT_LIGHT_COS_OUTER,
+  lightFalloffExponentOf,
+} from '../clusteredLights.ts';
 
 /** Lights the probe bake shades a hit with. */
 export const MAX_BOUNCE_LIGHTS = 32;
 /**
  * Floats a light takes: where it is and how far it reaches; its colour at its weight and the cosine
- * of its inner cone; the way it points and the cosine of its outer cone.
+ * of its inner cone; the way it points and the cosine of its outer cone; and its own falloff
+ * exponent, 0 for the frame's, in a fourth row of its own (`PointLightSource.falloffExponent`).
  */
-export const BOUNCE_LIGHT_FLOATS = 12;
+export const BOUNCE_LIGHT_FLOATS = 16;
 
 export function createBounceLights(): Float32Array {
   return new Float32Array(MAX_BOUNCE_LIGHTS * BOUNCE_LIGHT_FLOATS);
@@ -62,6 +67,10 @@ export function resolveBounceLights(lights: PointLightSet | null, out: Float32Ar
     out[at + 9] = lights.lightDirections?.[i * 3 + 1] ?? 0;
     out[at + 10] = lights.lightDirections?.[i * 3 + 2] ?? 0;
     out[at + 11] = lights.lightConeCos?.[i * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+    out[at + 12] = lightFalloffExponentOf(lights.lightFalloffExponents?.[i]);
+    out[at + 13] = 0;
+    out[at + 14] = 0;
+    out[at + 15] = 0;
     count++;
   }
   return count;

package/src/render/instanceCull.ts

@@ -76,6 +76,10 @@ export function cullInstances(
     if (regions !== undefined && out.lightmapRegions !== undefined) {
       for (let k = 0; k < 4; k++) out.lightmapRegions[kept * 4 + k] = regions[i * 4 + k] as number;
     }
+    const cells = data.uvRegions;
+    if (cells !== undefined && out.uvRegions !== undefined) {
+      for (let k = 0; k < 4; k++) out.uvRegions[kept * 4 + k] = cells[i * 4 + k] as number;
+    }
     kept++;
   }
   out.count = kept;

package/src/render/instances.ts

@@ -12,9 +12,9 @@
  *
  * **What it gives up** is a matrix per instance where a scatter spends five floats: 80 bytes
  * against 44, and no wind. **What would make it wrong** is a caller wanting per-instance
- * anything beyond an opacity — a morph weight, a texture cell — which wants another attribute,
- * and the sixteen WebGL2 guarantees are already spent. The opacity rides the float the stride was
- * padded with, which is why it costs nothing.
+ * anything beyond an opacity and a texture cell — a morph weight, say — which wants another
+ * attribute, and the sixteen WebGL2 guarantees are already spent. The opacity rides the float the
+ * stride was padded with and the cell the matrix's bottom row, which is why neither costs a byte.
  */
 export interface MeshInstances {
   /**
@@ -51,6 +51,20 @@ export interface MeshInstances {
    * either mismatch is said once on the console.
    */
   readonly lightmapRegions?: Float32Array;
+  /**
+   * Four floats each, the instance's cell of its texture: `[scaleU, scaleV, offsetU, offsetV]`,
+   * applied to the mesh's coordinates before the material's own scale and offset, in every pass
+   * that reads them — so one draw carries particles in different cells of a flipbook, or props
+   * wearing different tiles of one atlas. **Absent, or past `count`, is the whole texture**,
+   * `[1, 1, 0, 0]`, which is what every instance read before 4.8.7.
+   *
+   * **It rides the matrix's bottom row**, which an instance's placement — a turn, a scale and a
+   * move — leaves at `[0, 0, 0, 1]`, and which every stage drawing an instance rebuilds as that.
+   * So a placement must be affine, as every placement of a solid object is; a projective one is
+   * drawn as its affine part. A culled batch (`cullInstances`) carries the cells only into a
+   * target that has the array.
+   */
+  readonly uvRegions?: Float32Array;
   /** How many instances the arrays hold. Fixed at creation; the buffers are sized from it. */
   readonly capacity: number;
   /** How many are live. The rest of the buffer is neither uploaded nor drawn. */
@@ -75,8 +89,8 @@ export function createMeshInstances(capacity: number): MeshInstances {
 }
 
 /**
- * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, three of
- * tint, and the opacity.
+ * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, the bottom row
+ * of which carries the texture cell, three of tint, and the opacity.
  *
  * **Twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be a multiple
  * of four on both backends, which 76 already is — the twentieth float was padding for the
@@ -101,12 +115,18 @@ export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
  * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
  */
 export function packInstances(instances: MeshInstances, out: Float32Array): void {
-  const { models, tints, alphas, lightmapRegions } = instances;
+  const { models, tints, alphas, lightmapRegions, uvRegions } = instances;
   const count = Math.min(instances.count, instances.capacity);
   for (let i = 0; i < count; i += 1) {
     const at = i * INSTANCE_FLOATS;
     const m = i * 16;
     for (let c = 0; c < 16; c += 1) out[at + c] = models[m + c] as number;
+    /* The texture cell in the bottom row an affine placement leaves free. See `uvRegions`. */
+    const cell = i * 4;
+    out[at + 3] = uvRegions?.[cell] ?? 1;
+    out[at + 7] = uvRegions?.[cell + 1] ?? 1;
+    out[at + 11] = uvRegions?.[cell + 2] ?? 0;
+    out[at + 15] = uvRegions?.[cell + 3] ?? 0;
     if (lightmapRegions !== undefined) {
       /* The region in the tint's and the opacity's place. See `lightmapRegions`. */
       for (let c = 0; c < 4; c += 1) out[at + 16 + c] = lightmapRegions[i * 4 + c] as number;

package/src/render/lightBudget.ts

@@ -1,4 +1,5 @@
 /** Fixed point-light budget shared by CPU selection and the flat shader. */
+import { MAX_AREA_LIGHTS, packAreaSizesAndDoors } from './areaLights.ts';
 import type { AreaLightBuffer } from './areaLights.ts';
 import type { ResolvedAreaShadows } from './areaShadowSet.ts';
 import {
@@ -7,6 +8,7 @@ import {
   lampSourceRadius,
   lampWeight,
   lightChannelsOf,
+  lightFalloffExponentOf,
 } from './clusteredLights.ts';
 
 /**
@@ -401,11 +403,20 @@ export interface PointLightSet {
    * character's own key and rim lights, which the floor around the character must not take.
    */
   readonly lightChannels?: Float32Array;
+  /**
+   * One per light: its own falloff exponent, `(1 - (d/R)^2)^n` with no distance term, or 0 for the
+   * frame's falloff. **Absent, or a short array, is 0 for every light**, so a scene that names none
+   * falls off as it did. See `PointLightSource.falloffExponent`.
+   */
+  readonly lightFalloffExponents?: Float32Array;
 }
 
 /** Weights are optional per consumer; a short array means every light is fully present. */
 const FULLY_PRESENT: Float32Array = new Float32Array(MAX_POINT_LIGHTS).fill(1);
 
+/** The fixed arm's rectangles as `uAreaLightSize` holds them; refilled per bind, allocated once. */
+const AREA_SIZES_AND_DOORS = new Float32Array(MAX_AREA_LIGHTS * 4);
+
 /** No size at all, which is the behaviour every scene had before a light could have one. */
 const POINT_SOURCES: Float32Array = new Float32Array(MAX_POINT_LIGHTS);
 /**
@@ -504,7 +515,8 @@ export function bindPointLights(
    * every lamp switched off.
    */
   gl.uniform3fv(uniforms['uLightDir[0]'] ?? null, r.directions);
-  gl.uniform2fv(uniforms['uLightCone[0]'] ?? null, r.coneCos);
+  /* The cone and, in z, the light's own falloff exponent. See `conesAndFalloffs`. */
+  gl.uniform4fv(uniforms['uLightCone[0]'] ?? null, r.conesAndFalloffs);
   gl.uniform1fv(uniforms['uLightIesProfile[0]'] ?? null, r.iesProfiles);
   /* The azimuth and, in w, the channels. See `axesAndChannels`. */
   gl.uniform4fv(uniforms['uLightIesAxis[0]'] ?? null, r.axesAndChannels);
@@ -535,7 +547,9 @@ export function bindAreaLights(
   gl.uniform3fv(uniforms['uAreaLightColor[0]'] ?? null, lights.colors);
   gl.uniform3fv(uniforms['uAreaLightRight[0]'] ?? null, lights.right);
   gl.uniform3fv(uniforms['uAreaLightUp[0]'] ?? null, lights.up);
-  gl.uniform2fv(uniforms['uAreaLightSize[0]'] ?? null, lights.sizes);
+  /* The half extents and, in zw, the barn doors. See `packAreaSizesAndDoors`. */
+  packAreaSizesAndDoors(lights, AREA_SIZES_AND_DOORS);
+  gl.uniform4fv(uniforms['uAreaLightSize[0]'] ?? null, AREA_SIZES_AND_DOORS);
   gl.uniform1fv(uniforms['uAreaLightTwoSided[0]'] ?? null, lights.twoSided);
 }
 
@@ -589,6 +603,12 @@ export interface ResolvedPointLights {
    * array of their own, which would cost a row a light of a budget that has none to give.
    */
   readonly axesAndChannels: Float32Array;
+  /**
+   * Owned, four a light: the cone's two cosines, then the light's own falloff exponent, as
+   * `uLightCone` carries them — a `vec2` array costs a whole row a light on WebGL2 anyway, so the
+   * exponent rides the half it left rather than a row of its own.
+   */
+  readonly conesAndFalloffs: Float32Array;
   /**
    * Owned, `MAX_POINT_LIGHTS` long: the emitter sizes and weights as the froxel record carries
    * them, at half precision. `sourceRadii` and `weights` point here once a light set resolves, so
@@ -614,6 +634,7 @@ const glLights: ResolvedPointLights = {
   iesAxes: NO_IES_AXES,
   cookies: NO_COOKIES,
   axesAndChannels: new Float32Array(MAX_POINT_LIGHTS * 4),
+  conesAndFalloffs: new Float32Array(MAX_POINT_LIGHTS * 4),
   heldSourceRadii: new Float32Array(MAX_POINT_LIGHTS),
   heldWeights: new Float32Array(MAX_POINT_LIGHTS),
 };
@@ -649,6 +670,7 @@ export function resolvePointLights(
     out.iesAxes = NO_IES_AXES;
     out.cookies = NO_COOKIES;
     packAxesAndChannels(NO_IES_AXES, undefined, out.axesAndChannels);
+    packConesAndFalloffs(OPEN_CONES, undefined, out.conesAndFalloffs);
     return out;
   }
   /*
@@ -742,9 +764,25 @@ export function resolvePointLights(
   out.iesAxes = iesAxes;
   out.cookies = cookies;
   packAxesAndChannels(iesAxes, lights.lightChannels, out.axesAndChannels);
+  packConesAndFalloffs(coneCos, lights.lightFalloffExponents, out.conesAndFalloffs);
   return out;
 }
 
+/** The cone and the falloff exponent, four a light, as `uLightCone` holds them. */
+function packConesAndFalloffs(
+  cones: Float32Array,
+  exponents: Float32Array | undefined,
+  out: Float32Array,
+): void {
+  const named = (exponents?.length ?? 0) >= MAX_POINT_LIGHTS ? exponents : undefined;
+  for (let light = 0; light < MAX_POINT_LIGHTS; light++) {
+    out[light * 4] = cones[light * 2] ?? POINT_LIGHT_COS_INNER;
+    out[light * 4 + 1] = cones[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+    out[light * 4 + 2] = lightFalloffExponentOf(named?.[light]);
+    out[light * 4 + 3] = 0;
+  }
+}
+
 /** The azimuth and the channels, four a light, as `uLightIesAxis` holds them. */
 function packAxesAndChannels(
   axes: Float32Array,

package/src/render/lightmap.ts

@@ -30,17 +30,19 @@
  * regions no tint. **What it does not do**: the GPU-driven pipeline and splats read no page.
  */
 import type { MeshData } from '@driftengine/drft';
-import { toHalfFloats } from './halfFloat.ts';
+import { packRgb9e5 } from './rgb9e5.ts';
 
 /** One page as a consumer decoded it. */
 export interface LightmapPage {
   readonly width: number;
   readonly height: number;
   /**
-   * Linear irradiance, three floats a texel, row-major from the top, in the same units every other
-   * light here is in — a bake from another engine scaled by that engine's exposure, as its lights are.
+   * Linear irradiance, row-major from the top, in the same units every other light here is in — a
+   * bake from another engine scaled by that engine's exposure, as its lights are. Either three
+   * floats a texel, or one word a texel already packed as rgb9e5 (`rgb9e5.ts`), which is how such a
+   * bake usually arrives and which uploads with no conversion at all.
    */
-  readonly irradiance: Float32Array;
+  readonly irradiance: Float32Array | Uint32Array;
   /**
    * The direction the light arrives from, four bytes a texel: a first-order spherical harmonic in
    * this engine's world axes, each value stored as `v * 0.5 + 0.5` — xyz the axis, w the constant.
@@ -60,13 +62,25 @@ export type LightmapRegion = readonly [number, number, number, number];
 /** The whole page. */
 export const WHOLE_PAGE: LightmapRegion = [1, 1, 0, 0];
 
-/** A page as both backends upload it: `layers` images of half-float RGBA, row-major from the top. */
+/**
+ * A page as both backends upload it: two layers of four bytes a texel, row-major from the top. The
+ * first is the irradiance's rgb9e5 word, byte by byte from its lowest; the second is the direction.
+ *
+ * **Eight bytes a texel, and the shader filters it.** Half floats were sixteen: a stage of 49 pages
+ * and 21.8 million texels held 348 MB, where this holds 174. The price is that the irradiance cannot
+ * be filtered as it is stored — a bilinear blend of two words with different exponents is not the
+ * blend of the colours they hold — so the lit stage fetches a texel's four neighbours, decodes each
+ * and blends the colours (`modelBaked` in `shaders/flat/models.ts`): four fetches a layer where one
+ * filtered sample was, on lightmapped surfaces alone. **What would make it wrong** is every device
+ * a page reaches sampling `rgb9e5ufloat`, which WebGL2 does as `RGB9_E5` too; it would then be a
+ * texture of its own, filtered by the device, and a binding the lit stage has no room for.
+ */
 export interface LightmapTexels {
   readonly kind: 'lightmap-texels';
   readonly width: number;
   readonly height: number;
-  readonly layers: number;
-  readonly texels: Uint16Array;
+  /** Each layer's bytes, in layer order: the irradiance, then the direction. */
+  readonly layers: readonly Uint8Array[];
 }
 
 /** Whether a surface texture's source is a page's texels rather than an image or blocks. */
@@ -79,9 +93,9 @@ export function isLightmapTexels(source: unknown): source is LightmapTexels {
 }
 
 /**
- * A page as both backends upload it: two layers of half-float RGBA, the irradiance with an alpha of
- * one and the direction as the fractions its bytes are. Refuses a page whose arrays are not its
- * size, naming the one that is short.
+ * A page as both backends upload it (see `LightmapTexels`). Refuses a page whose arrays are not its
+ * size, naming the one that is short. Packed irradiance is read where it lies, with no copy; float
+ * irradiance is packed once, here.
  */
 export function lightmapTexels(page: LightmapPage): LightmapTexels {
   const { width, height } = page;
@@ -89,10 +103,14 @@ export function lightmapTexels(page: LightmapPage): LightmapTexels {
     throw new Error(`createLightmap: a ${width} by ${height} page has nothing in it`);
   }
   const texels = width * height;
-  if (page.irradiance.length !== texels * 3) {
+  const irradiance = page.irradiance;
+  const packed = irradiance instanceof Uint32Array;
+  const wanted = packed ? texels : texels * 3;
+  if (irradiance.length !== wanted) {
     throw new Error(
-      `createLightmap: ${page.irradiance.length} irradiance floats for a ${width} by ${height} ` +
-        `page, which wants ${texels * 3}: three a texel`,
+      `createLightmap: ${irradiance.length} irradiance ${packed ? 'words' : 'floats'} for a ` +
+        `${width} by ${height} page, which wants ${wanted}: ` +
+        (packed ? 'one rgb9e5 word a texel' : 'three a texel'),
     );
   }
   if (page.direction.length !== texels * 4) {
@@ -101,24 +119,47 @@ export function lightmapTexels(page: LightmapPage): LightmapTexels {
         `page, which wants ${texels * 4}: four a texel`,
     );
   }
-  const floats = new Float32Array(texels * 4 * LIGHTMAP_LAYERS);
-  for (let t = 0; t < texels; t++) {
-    floats[t * 4] = page.irradiance[t * 3] as number;
-    floats[t * 4 + 1] = page.irradiance[t * 3 + 1] as number;
-    floats[t * 4 + 2] = page.irradiance[t * 3 + 2] as number;
-    floats[t * 4 + 3] = 1;
-    const at = (texels + t) * 4;
-    for (let c = 0; c < 4; c++) floats[at + c] = (page.direction[t * 4 + c] as number) / 255;
+  let words: Uint32Array;
+  if (packed) {
+    words = irradiance;
+  } else {
+    words = new Uint32Array(texels);
+    for (let t = 0; t < texels; t++) {
+      words[t] = packRgb9e5(
+        irradiance[t * 3] as number,
+        irradiance[t * 3 + 1] as number,
+        irradiance[t * 3 + 2] as number,
+      );
+    }
   }
   return {
     kind: 'lightmap-texels',
     width,
     height,
-    layers: LIGHTMAP_LAYERS,
-    texels: toHalfFloats(floats),
+    layers: [littleEndianBytes(words), page.direction],
   };
 }
 
+/** Whether this platform lays a word out lowest byte first, which the shader's decode assumes. */
+const LITTLE_ENDIAN = new Uint8Array(new Uint32Array([1]).buffer)[0] === 1;
+
+/**
+ * A page's words as bytes, lowest first: a view of the same memory on every little-endian platform,
+ * which is every one a browser runs on, and a reordered copy anywhere else.
+ */
+function littleEndianBytes(words: Uint32Array): Uint8Array {
+  const bytes = new Uint8Array(words.buffer, words.byteOffset, words.length * 4);
+  if (LITTLE_ENDIAN) return bytes;
+  const swapped = new Uint8Array(bytes.length);
+  for (let i = 0; i < bytes.length; i += 4) {
+    swapped[i] = bytes[i + 3] as number;
+    swapped[i + 1] = bytes[i + 2] as number;
+    swapped[i + 2] = bytes[i + 1] as number;
+    swapped[i + 3] = bytes[i] as number;
+  }
+  return swapped;
+}
+
 /**
  * A mesh with its second coordinates moved onto the grain and relief streams they ride, or the
  * mesh itself where it has none. Called by both backends' `createMesh`, before anything records

package/src/render/particlePool.ts

@@ -53,6 +53,29 @@ export interface ParticleInstances {
   capacity: number;
 }
 
+/**
+ * Floats one particle takes in a buffer a caller's own compute writes (`DeviceParticles`), in this
+ * order: position 3, half-width 1, roll 1, colour 3, opacity 1, age 1, seed 1, velocity 3, a
+ * sprite's frame 1 and its half-height 1 — `ParticleInstances`' streams, interleaved as the pool's
+ * own upload interleaves them. 64 bytes a particle.
+ */
+export const DEVICE_PARTICLE_FLOATS = 16;
+
+/**
+ * Particles a caller's own compute shader wrote into a buffer of its own (`registerCompute`), drawn
+ * where they lie by `drawDeviceParticles` rather than read back and uploaded again. WebGPU only.
+ *
+ * **Not sorted**, as a pool's are where its batch asks: the device holds them, so an alpha-blended
+ * set that must be drawn far to near sorts itself. A slot with a half-width of 0 draws nothing, which
+ * is how a fixed-size buffer holds fewer live particles than it has room for.
+ */
+export interface DeviceParticles {
+  /** A buffer with `VERTEX` usage, `DEVICE_PARTICLE_FLOATS` floats a particle. */
+  readonly buffer: GPUBuffer;
+  /** How many particles from its start to draw; no more than the buffer holds. */
+  readonly count: number;
+}
+
 function createParticleInstances(capacity: number): ParticleInstances {
   return {
     positions: new Float32Array(capacity * 3),

package/src/render/pass.ts

@@ -119,7 +119,23 @@ export type PassContext = {
   /** The exposure that goes with it. 1 where the composite will apply the real one. */
   readonly outputExposure: number;
 } & (
-  | { readonly backend: 'webgl2'; readonly gl: WebGL2RenderingContext }
+  | {
+      readonly backend: 'webgl2';
+      readonly gl: WebGL2RenderingContext;
+      /**
+       * The frame's colour with everything drawn before this pass, for a pass declaring
+       * `reads: ['colorSnapshot']`, and null for one that does not or where the frame keeps no
+       * scene target (`screenEffects` off). A copy, never the attachment being drawn into, which
+       * WebGL2 cannot sample; taken afresh at each such pass's draw. WebGPU hands the same copy
+       * over in `PrepareContext.sceneColor`, where a bind group has to be built before the pass.
+       */
+      readonly sceneColor: WebGLTexture | null;
+      /**
+       * The frame's depth as it stands, for a pass declaring `reads: ['depthSnapshot']`: a copy, at
+       * the buffer's own values and reversed as it is (1 near, 0 far). Null as `sceneColor` is.
+       */
+      readonly sceneDepth: WebGLTexture | null;
+    }
   | {
       readonly backend: 'webgpu';
       readonly pass: GPURenderPassEncoder;
@@ -217,6 +233,42 @@ export type PrepareContext =
        * should not apply it either; the renderer's own verbs do not jitter a mirror.
        */
       readonly jitter: Float32Array;
+      /**
+       * The frame's single-sample copy of its depth, or null where the frame keeps none (no
+       * composite: `screenEffects` off).
+       *
+       * One `r32float` texel a pixel holding the depth buffer's own value, reversed as the
+       * buffer is (`REVERSED_DEPTH`: 1 at the near plane, 0 at the far one). Unfilterable, so a
+       * pass binds it as `'unfilterable-float'` and reads it with a non-filtering sampler or
+       * `textureLoad`.
+       *
+       * **Handed over here, filled at the draw.** The view is the one this frame's copy will be
+       * written into, so a pass builds its bind groups with it before the frame's pass opens; the
+       * copy itself is taken when a pass that declares `reads: ['depthSnapshot']` is drawn, with
+       * everything drawn before it, which is what the soft edge of a translucent particle
+       * needs. A pass that does not declare that read finds whatever the frame last wrote there.
+       */
+      readonly sceneDepth: GPUTextureView | null;
+      /**
+       * The frame's colour, for a pass that declares `reads: ['colorSnapshot']`, or null where no
+       * registered pass does or the frame keeps no composite (`screenEffects` off).
+       *
+       * At the scene's own size and format — under a reconstruction, the render's rather than the
+       * output's, since that is the picture a registered pass draws into — and filterable.
+       * **Handed over here, refilled at the draw**: the view is the texture each reading pass's
+       * draw copies the frame into, with everything drawn before it, so a distortion samples the
+       * scene behind it and a full-screen effect drawn last reads the whole frame and writes over
+       * it, in scene light, before the tone curve. A copy a reading pass, where `sceneDepth` is one
+       * a frame.
+       *
+       * **Under a reconstruction a pass that reads it is drawn after the upscale**, over the
+       * reconstructed picture and after every blended draw, whatever order it was asked in — at the
+       * output's size and the reconstruction's format, which `PassContext.format` names at that
+       * draw, so a pass drawn there keeps a pipeline for it. The view is then the output-size copy.
+       * `sceneDepth` stays the render's opaque depth: at a ratio above 1 its texels are coarser by
+       * the ratio, and a blended draw is in neither depth, as it never is.
+       */
+      readonly sceneColor: GPUTextureView | null;
     };
 
 /**

package/src/render/pointLightSelection.ts

@@ -1,6 +1,10 @@
 /** Allocation-free selection and packing of point lights for a fixed shader budget. */
 
-import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from './clusteredLights.ts';
+import {
+  POINT_LIGHT_COS_INNER,
+  POINT_LIGHT_COS_OUTER,
+  lightFalloffExponentOf,
+} from './clusteredLights.ts';
 import { MAX_POINT_LIGHTS, POINT_SHADOW_POOL } from './lightBudget.ts';
 import { gatherLights } from './lightGrid.ts';
 import type { LightGrid } from './lightGrid.ts';
@@ -198,6 +202,14 @@ export interface PointLightSource {
    * whose uniform budget has none to spare.
    */
   inLightField?: boolean;
+  /**
+   * How the light fades with distance when it names its own way: `(1 - (d/R)^2)^n` with no distance
+   * term, `R` its radius and `n` this. Unreal's falloff for a light without inverse-square falloff,
+   * so a rig authored there — a fill of brightness 160 across 164 m, a key at exponent 8 — lights
+   * the space it was authored for rather than one that ends a few metres out. Absent or 0, the
+   * frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
+   */
+  falloffExponent?: number;
 }
 
 export interface PointLightBuffer {
@@ -256,6 +268,11 @@ export interface PointLightBuffer {
   readonly directions: Float32Array;
   /** Two per slot: the cosine of the inner cone angle, then of the outer. */
   readonly coneCos: Float32Array;
+  /**
+   * One per slot: the light's own falloff exponent, or 0 for the frame's falloff. See
+   * `PointLightSource.falloffExponent`.
+   */
+  readonly falloffExponents: Float32Array;
   /** One per slot: a row of the photometric atlas, or −1 for a light with no profile. */
   readonly iesProfiles: Float32Array;
   /** Internal insertion-sort storage; exposed only to keep one flat object. */
@@ -307,6 +324,7 @@ export function createPointLightBuffer(capacity: number = MAX_POINT_LIGHTS): Poi
     weights: new Float32Array(shaded),
     directions: new Float32Array(shaded * 3),
     coneCos: new Float32Array(shaded * 2),
+    falloffExponents: new Float32Array(shaded),
     /* −1 rather than 0, because row 0 is a real fixture and a light that asked for none must not
        be shaped by whichever profile happened to load first. */
     iesProfiles: new Float32Array(shaded).fill(-1),
@@ -587,6 +605,7 @@ function choose(
      * Restricting it to spots would be a smaller feature for no saving.
      */
     out.iesProfiles[slot] = light.iesProfile ?? -1;
+    out.falloffExponents[slot] = lightFalloffExponentOf(light.falloffExponent);
   }
   out.count = chosen;