@driftengine/core 4.8.6 → 4.9.0

package/dist/render/backend/webgpu/sceneCaptureTarget.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A scene capture's attachments on WebGPU: the depth and, above one sample, the multisampled colour
+ * its pass draws into and resolves from — the capture's own texture being the resolve, since **a
+ * texture cannot be both multisampled and sampled**. At the world's sample count and format, because
+ * a capture draws the world with the world's pipelines: a pipeline whose count or format disagrees
+ * with its attachment is rejected at `finish` and takes the whole capture with it. Remade only if
+ * either has changed since. See `sceneCapture.ts` for what a capture is.
+ */
+export declare class GpuSceneCaptureTarget {
+    private readonly device;
+    readonly width: number;
+    readonly height: number;
+    private depth;
+    private depthView;
+    private colorMsaa;
+    private colorMsaaView;
+    private key;
+    constructor(device: GPUDevice, width: number, height: number);
+    attachments(samples: number, format: GPUTextureFormat): {
+        depth: GPUTextureView;
+        colorMsaa: GPUTextureView | null;
+    };
+    dispose(): void;
+}

package/dist/render/backend/webgpu/sceneCaptureTarget.js

@@ -0,0 +1,59 @@
+import { DEPTH_FORMAT } from '../../depthConvention.js';
+/**
+ * A scene capture's attachments on WebGPU: the depth and, above one sample, the multisampled colour
+ * its pass draws into and resolves from — the capture's own texture being the resolve, since **a
+ * texture cannot be both multisampled and sampled**. At the world's sample count and format, because
+ * a capture draws the world with the world's pipelines: a pipeline whose count or format disagrees
+ * with its attachment is rejected at `finish` and takes the whole capture with it. Remade only if
+ * either has changed since. See `sceneCapture.ts` for what a capture is.
+ */
+export class GpuSceneCaptureTarget {
+    device;
+    width;
+    height;
+    depth = null;
+    depthView = null;
+    colorMsaa = null;
+    colorMsaaView = null;
+    key = '';
+    constructor(device, width, height) {
+        this.device = device;
+        this.width = width;
+        this.height = height;
+    }
+    attachments(samples, format) {
+        const key = `${samples}:${format}`;
+        if (this.depthView === null || key !== this.key) {
+            this.dispose();
+            this.key = key;
+            this.depth = this.device.createTexture({
+                label: 'capture.depth',
+                size: [this.width, this.height],
+                format: DEPTH_FORMAT,
+                sampleCount: samples,
+                usage: 0x10, // RENDER_ATTACHMENT
+            });
+            this.depthView = this.depth.createView();
+            this.colorMsaa =
+                samples > 1
+                    ? this.device.createTexture({
+                        label: 'capture.colorMsaa',
+                        size: [this.width, this.height],
+                        format,
+                        sampleCount: samples,
+                        usage: 0x10, // RENDER_ATTACHMENT
+                    })
+                    : null;
+            this.colorMsaaView = this.colorMsaa?.createView() ?? null;
+        }
+        return { depth: this.depthView, colorMsaa: this.colorMsaaView };
+    }
+    dispose() {
+        this.depth?.destroy();
+        this.colorMsaa?.destroy();
+        this.depth = null;
+        this.depthView = null;
+        this.colorMsaa = null;
+        this.colorMsaaView = null;
+    }
+}

package/dist/render/backend/webgpu/shaders/clusterBin.wgsl.d.ts

@@ -20,4 +20,4 @@
  * sort. `scripts/cluster-check.mjs` is what holds that, and the 2026-08-17 rule about two
  * implementations of one decision is why it exists at all.
  */
-export declare const CLUSTER_BIN_WGSL = "\nconst CLUSTER_X: u32 = 16u;\nconst CLUSTER_Y: u32 = 9u;\nconst CLUSTER_Z: u32 = 24u;\nconst CLUSTER_COUNT: u32 = 3456u;\nconst CLUSTER_TEXELS: u32 = 20u;\nconst MAX_LIGHTS_PER_CLUSTER: u32 = 76u;\nconst LIGHT_TEXELS: u32 = 5u;\nconst LIGHT_REGION_TEXELS: u32 = 1600u;\nconst TABLE_WIDTH: u32 = 320u;\n\nstruct Params {\n  view: mat4x4<f32>,\n  /** near, far, tan(fovY/2), aspect. */\n  frustum: vec4<f32>,\n  lightCount: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n/**\n * The records as `writeLightRecord` lays them out, as bits. **`u32`, not `f32`**, because one\n * slot holds two halves, and a zero weight read as a float would be a subnormal a GPU is free to\n * flush on the way through; read as bits, the copy into the table cannot change them.\n */\n@group(0) @binding(1) var<storage, read> lights: array<vec4<u32>>;\n/**\n * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.\n *\n * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason\n * a cluster owns a fixed run rather than appending into a shared one.\n */\n@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;\n\n/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */\nfn texelAt(texel: u32) -> vec2<i32> {\n  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));\n}\n\nfn sliceNearDepth(slice: f32) -> f32 {\n  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));\n}\n\n/** Squared distance from a point to an axis-aligned box, zero inside it. */\nfn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {\n  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));\n  return dot(d, d);\n}\n\n/** A light's view-space centre, with depth positive along the view direction. */\nfn viewOf(light: u32) -> vec3<f32> {\n  let world = bitcast<vec4<f32>>(lights[light * LIGHT_TEXELS]);\n  let v = params.view * vec4<f32>(world.xyz, 1.0);\n  return vec3<f32>(v.x, v.y, -v.z);\n}\n\n/**\n * Squared distance from a light's view-space centre to a point.\n *\n * **Squared, matching `centreDistanceSq` in `clusteredLights.ts` rather than taking a root.** The\n * ranking is identical either way, and a square root is one more operation for the two\n * implementations to round differently.\n */\nfn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {\n  let d = viewOf(light) - centre;\n  return dot(d, d);\n}\n\n/**\n * Whether a spot's cone misses this froxel: `coneBoxGap` in `clusteredLights.ts`, the same\n * arithmetic in the same order \u2014 the froxel's bounding sphere against the infinite cone, its apex\n * included, which can keep a light the shader would not draw and never drop one it would. A light\n * with no cone carries a cosine of -2 and never reaches the test.\n */\nfn outsideCone(light: u32, apex: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> bool {\n  let cosOuter = bitcast<f32>(lights[light * LIGHT_TEXELS + 3u].y);\n  if (cosOuter <= -1.0) {\n    return false;\n  }\n  let world = bitcast<vec3<f32>>(lights[light * LIGHT_TEXELS + 2u].yzw);\n  let a = (params.view * vec4<f32>(world, 0.0)).xyz;\n  let axis = vec3<f32>(a.x, a.y, -a.z);\n  let len = length(axis);\n  /* The shader measures the cone against the direction as given, so a long one is a wider cone. */\n  if (len <= 1e-6 || cosOuter / len <= -1.0) {\n    return false;\n  }\n  let cosA = cosOuter / len;\n  let sinA = sqrt(max(0.0, 1.0 - cosA * cosA));\n  let unit = axis / len;\n  let extent = (hi - lo) * 0.5;\n  let toCentre = (lo + hi) * 0.5 - apex;\n  let along = dot(toCentre, unit);\n  let lengthSq = dot(toCentre, toCentre);\n  let across = sqrt(max(lengthSq - along * along, 0.0));\n  let reach = sqrt(lengthSq);\n  var distance = cosA * across - along * sinA;\n  if (along < -sinA * reach) {\n    distance = reach;\n  }\n  return distance - length(extent) > 0.0;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let id = gid.x;\n\n  /*\n   * The light records, written by the first invocations that have one.\n   *\n   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture\n   * the clusters do, because the lit pass reads both through one texture unit; writing them from\n   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.\n   * There are always more clusters than lights, so every record has an invocation.\n   */\n  if (id < params.lightCount) {\n    let record = id * LIGHT_TEXELS;\n    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {\n      textureStore(table, texelAt(record + t), lights[record + t]);\n    }\n  }\n\n  if (id >= CLUSTER_COUNT) {\n    return;\n  }\n\n  let k = id / (CLUSTER_X * CLUSTER_Y);\n  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;\n  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;\n\n  /* The AABB of the froxel's eight corners, exactly as `clusterViewBounds` derives it. */\n  let zNear = sliceNearDepth(f32(k));\n  let zFar = sliceNearDepth(f32(k + 1u));\n  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);\n  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);\n  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);\n  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);\n  let halfHNear = zNear * params.frustum.z;\n  let halfHFar = zFar * params.frustum.z;\n  let halfWNear = halfHNear * params.frustum.w;\n  let halfWFar = halfHFar * params.frustum.w;\n\n  let lo = vec3<f32>(\n    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),\n    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),\n    zNear,\n  );\n  let hi = vec3<f32>(\n    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),\n    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),\n    zFar,\n  );\n  let centre = (lo + hi) * 0.5;\n\n  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;\n  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n    indices[n] = 0u;\n  }\n  var count: u32 = 0u;\n\n  /* Increasing light index, which is what makes the list sorted without a sort. */\n  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {\n    /* A rectangle carries its reach negated, which is how the lit pass tells it from a lamp. */\n    let signedRadius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);\n    let radius = abs(signedRadius);\n    let v = viewOf(light);\n    if (v.z + radius <= 0.0) {\n      continue;\n    }\n    if (distanceSqToBounds(v, lo, hi) > radius * radius) {\n      continue;\n    }\n    if (signedRadius >= 0.0 && outsideCone(light, v, lo, hi)) {\n      continue;\n    }\n\n    if (count < MAX_LIGHTS_PER_CLUSTER) {\n      indices[count] = light;\n      count = count + 1u;\n      continue;\n    }\n\n    /*\n     * Full. Drop the farthest from the cluster's centre if this one is nearer.\n     *\n     * **The only float comparison that decides anything here**, and the reason the *order* is an\n     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,\n     * so it is confined to membership, where the conformance script forgives a light sitting\n     * within epsilon of a boundary.\n     */\n    var worstSlot: i32 = -1;\n    var worst = centreDistanceSq(light, centre);\n    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let d = centreDistanceSq(indices[n], centre);\n      if (d > worst) {\n        worst = d;\n        worstSlot = i32(n);\n      }\n    }\n    if (worstSlot < 0) {\n      continue;\n    }\n    indices[u32(worstSlot)] = light;\n\n    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */\n    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let value = indices[n];\n      var m: i32 = i32(n) - 1;\n      while (m >= 0 && indices[u32(m)] > value) {\n        indices[u32(m) + 1u] = indices[u32(m)];\n        m = m - 1;\n      }\n      indices[u32(m + 1)] = value;\n    }\n  }\n\n  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;\n  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));\n  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {\n    textureStore(\n      table,\n      texelAt(base + 1u + t),\n      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),\n    );\n  }\n}\n";
+export declare const CLUSTER_BIN_WGSL = "\nconst CLUSTER_X: u32 = 16u;\nconst CLUSTER_Y: u32 = 9u;\nconst CLUSTER_Z: u32 = 24u;\nconst CLUSTER_COUNT: u32 = 3456u;\nconst CLUSTER_TEXELS: u32 = 20u;\nconst MAX_LIGHTS_PER_CLUSTER: u32 = 76u;\nconst LIGHT_TEXELS: u32 = 6u;\nconst LIGHT_REGION_TEXELS: u32 = 1920u;\nconst TABLE_WIDTH: u32 = 320u;\n\nstruct Params {\n  view: mat4x4<f32>,\n  /** near, far, tan(fovY/2), aspect. */\n  frustum: vec4<f32>,\n  lightCount: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n/**\n * The records as `writeLightRecord` lays them out, as bits. **`u32`, not `f32`**, because one\n * slot holds two halves, and a zero weight read as a float would be a subnormal a GPU is free to\n * flush on the way through; read as bits, the copy into the table cannot change them.\n */\n@group(0) @binding(1) var<storage, read> lights: array<vec4<u32>>;\n/**\n * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.\n *\n * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason\n * a cluster owns a fixed run rather than appending into a shared one.\n */\n@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;\n\n/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */\nfn texelAt(texel: u32) -> vec2<i32> {\n  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));\n}\n\nfn sliceNearDepth(slice: f32) -> f32 {\n  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));\n}\n\n/** Squared distance from a point to an axis-aligned box, zero inside it. */\nfn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {\n  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));\n  return dot(d, d);\n}\n\n/** A light's view-space centre, with depth positive along the view direction. */\nfn viewOf(light: u32) -> vec3<f32> {\n  let world = bitcast<vec4<f32>>(lights[light * LIGHT_TEXELS]);\n  let v = params.view * vec4<f32>(world.xyz, 1.0);\n  return vec3<f32>(v.x, v.y, -v.z);\n}\n\n/**\n * Squared distance from a light's view-space centre to a point.\n *\n * **Squared, matching `centreDistanceSq` in `clusteredLights.ts` rather than taking a root.** The\n * ranking is identical either way, and a square root is one more operation for the two\n * implementations to round differently.\n */\nfn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {\n  let d = viewOf(light) - centre;\n  return dot(d, d);\n}\n\n/**\n * Whether a spot's cone misses this froxel: `coneBoxGap` in `clusteredLights.ts`, the same\n * arithmetic in the same order \u2014 the froxel's bounding sphere against the infinite cone, its apex\n * included, which can keep a light the shader would not draw and never drop one it would. A light\n * with no cone carries a cosine of -2 and never reaches the test.\n */\nfn outsideCone(light: u32, apex: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> bool {\n  let cosOuter = bitcast<f32>(lights[light * LIGHT_TEXELS + 3u].y);\n  if (cosOuter <= -1.0) {\n    return false;\n  }\n  let world = bitcast<vec3<f32>>(lights[light * LIGHT_TEXELS + 2u].yzw);\n  let a = (params.view * vec4<f32>(world, 0.0)).xyz;\n  let axis = vec3<f32>(a.x, a.y, -a.z);\n  let len = length(axis);\n  /* The shader measures the cone against the direction as given, so a long one is a wider cone. */\n  if (len <= 1e-6 || cosOuter / len <= -1.0) {\n    return false;\n  }\n  let cosA = cosOuter / len;\n  let sinA = sqrt(max(0.0, 1.0 - cosA * cosA));\n  let unit = axis / len;\n  let extent = (hi - lo) * 0.5;\n  let toCentre = (lo + hi) * 0.5 - apex;\n  let along = dot(toCentre, unit);\n  let lengthSq = dot(toCentre, toCentre);\n  let across = sqrt(max(lengthSq - along * along, 0.0));\n  let reach = sqrt(lengthSq);\n  var distance = cosA * across - along * sinA;\n  if (along < -sinA * reach) {\n    distance = reach;\n  }\n  return distance - length(extent) > 0.0;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let id = gid.x;\n\n  /*\n   * The light records, written by the first invocations that have one.\n   *\n   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture\n   * the clusters do, because the lit pass reads both through one texture unit; writing them from\n   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.\n   * There are always more clusters than lights, so every record has an invocation.\n   */\n  if (id < params.lightCount) {\n    let record = id * LIGHT_TEXELS;\n    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {\n      textureStore(table, texelAt(record + t), lights[record + t]);\n    }\n  }\n\n  if (id >= CLUSTER_COUNT) {\n    return;\n  }\n\n  let k = id / (CLUSTER_X * CLUSTER_Y);\n  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;\n  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;\n\n  /* The AABB of the froxel's eight corners, exactly as `clusterViewBounds` derives it. */\n  let zNear = sliceNearDepth(f32(k));\n  let zFar = sliceNearDepth(f32(k + 1u));\n  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);\n  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);\n  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);\n  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);\n  let halfHNear = zNear * params.frustum.z;\n  let halfHFar = zFar * params.frustum.z;\n  let halfWNear = halfHNear * params.frustum.w;\n  let halfWFar = halfHFar * params.frustum.w;\n\n  let lo = vec3<f32>(\n    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),\n    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),\n    zNear,\n  );\n  let hi = vec3<f32>(\n    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),\n    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),\n    zFar,\n  );\n  let centre = (lo + hi) * 0.5;\n\n  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;\n  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n    indices[n] = 0u;\n  }\n  var count: u32 = 0u;\n\n  /* Increasing light index, which is what makes the list sorted without a sort. */\n  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {\n    /* A rectangle carries its reach negated, which is how the lit pass tells it from a lamp. */\n    let signedRadius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);\n    let radius = abs(signedRadius);\n    let v = viewOf(light);\n    if (v.z + radius <= 0.0) {\n      continue;\n    }\n    if (distanceSqToBounds(v, lo, hi) > radius * radius) {\n      continue;\n    }\n    if (signedRadius >= 0.0 && outsideCone(light, v, lo, hi)) {\n      continue;\n    }\n\n    if (count < MAX_LIGHTS_PER_CLUSTER) {\n      indices[count] = light;\n      count = count + 1u;\n      continue;\n    }\n\n    /*\n     * Full. Drop the farthest from the cluster's centre if this one is nearer.\n     *\n     * **The only float comparison that decides anything here**, and the reason the *order* is an\n     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,\n     * so it is confined to membership, where the conformance script forgives a light sitting\n     * within epsilon of a boundary.\n     */\n    var worstSlot: i32 = -1;\n    var worst = centreDistanceSq(light, centre);\n    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let d = centreDistanceSq(indices[n], centre);\n      if (d > worst) {\n        worst = d;\n        worstSlot = i32(n);\n      }\n    }\n    if (worstSlot < 0) {\n      continue;\n    }\n    indices[u32(worstSlot)] = light;\n\n    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */\n    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let value = indices[n];\n      var m: i32 = i32(n) - 1;\n      while (m >= 0 && indices[u32(m)] > value) {\n        indices[u32(m) + 1u] = indices[u32(m)];\n        m = m - 1;\n      }\n      indices[u32(m + 1)] = value;\n    }\n  }\n\n  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;\n  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));\n  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {\n    textureStore(\n      table,\n      texelAt(base + 1u + t),\n      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),\n    );\n  }\n}\n";

package/dist/render/backend/webgpu/surfaceTexturePass.d.ts

@@ -1,5 +1,6 @@
 import type { SurfaceTextureOptions } from '../../surfaceTexture.ts';
 import type { LightmapTexels } from '../../lightmap.ts';
+import type { SceneCaptureTexels } from '../../sceneCapture.ts';
 import type { CompressedTextureFormat, SurfaceSource } from '../../compressedSource.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 /** How many levels an image of this size has, counting the one it arrives with. */
@@ -63,11 +64,13 @@ export declare class GpuSurfaceTexture {
     effectsView: GPUTextureView | null;
     /** The block format a compressed texture holds, or null for one uploaded from images. */
     private readonly blockFormat;
-    constructor(device: GPUDevice, pipelines: PipelineCache, source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels, options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
+    constructor(device: GPUDevice, pipelines: PipelineCache, source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels | SceneCaptureTexels, options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
     /** A view of every layer, as the shaders' `texture_2d_array` bindings read it. */
     private arrayView;
     /** The view every binding of this image holds. A new one when `update` changes the size. */
     get view(): GPUTextureView;
+    /** The only layer as a plain 2D view, which a scene capture's pass resolves into. */
+    layerView(): GPUTextureView | null;
     /**
      * Replace the pixels, keeping the handle and its sampler.
      *

package/dist/render/backend/webgpu/surfaceTexturePass.js

@@ -1,6 +1,7 @@
 import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from '../../surfaceEffects.js';
 import { toHalfFloats } from '../../halfFloat.js';
 import { isLightmapTexels } from '../../lightmap.js';
+import { isSceneCaptureTexels } from '../../sceneCapture.js';
 import { layerSize, refuseArrayUpdate, sourceSize } from '../../textureSource.js';
 import { compressedLayers, planBlocks, refuseBlockUpdate } from '../../compressedSource.js';
 import { createCompressedTexture } from './compressedUpload.js';
@@ -156,24 +157,44 @@ export class GpuSurfaceTexture {
     constructor(device, pipelines, source, options = {}, compressed = []) {
         this.device = device;
         this.pipelines = pipelines;
-        /* A lightmap's page: half floats, uploaded as they are. See `lightmap.ts`. */
+        /* A scene capture's target: one empty layer the world is drawn into. See `sceneCapture.ts`. */
+        const capture = isSceneCaptureTexels(source) ? source : null;
+        /* A lightmap's page: two layers of bytes, uploaded as they are. See `lightmap.ts`. */
         const baked = isLightmapTexels(source) ? source : null;
-        const listed = (baked !== null ? [] : Array.isArray(source) ? source : [source]);
+        const listed = (baked !== null || capture !== null ? [] : Array.isArray(source) ? source : [source]);
         const blocks = compressedLayers(listed);
         const srgb = (options.colorSpace ?? 'linear') === 'srgb';
         /* `SRGB8_ALPHA8`'s equivalent. Decoded in the sampler, before filtering, which is the only
-           place it is correct — `surfaceTexture.ts` makes the argument in full. */
-        this.format = baked !== null ? 'rgba16float' : srgb ? 'rgba8unorm-srgb' : 'rgba8unorm';
-        if (baked !== null) {
+           place it is correct — `surfaceTexture.ts` makes the argument in full. A capture takes the
+           world's own format, which its pass resolves into. */
+        this.format =
+            capture !== null
+                ? pipelines.format
+                : srgb && baked === null
+                    ? 'rgba8unorm-srgb'
+                    : 'rgba8unorm';
+        if (capture !== null) {
+            this.layers = 1;
+            this.blockFormat = null;
+            this.mipmapped = false;
+            this.width = capture.width;
+            this.height = capture.height;
+            this.levels = 1;
+            this.texture = this.allocate();
+        }
+        else if (baked !== null) {
             /* No chain: a page is read at its own resolution, and a level of it would blend regions. */
-            this.layers = baked.layers;
+            this.layers = baked.layers.length;
             this.blockFormat = null;
             this.mipmapped = false;
             this.width = baked.width;
             this.height = baked.height;
             this.levels = 1;
             this.texture = this.allocate();
-            device.queue.writeTexture({ texture: this.texture }, baked.texels, { bytesPerRow: baked.width * 8, rowsPerImage: baked.height }, { width: baked.width, height: baked.height, depthOrArrayLayers: baked.layers });
+            /* A layer at a time, so a page's arrays are uploaded where they lie rather than joined. */
+            for (let layer = 0; layer < this.layers; layer++) {
+                device.queue.writeTexture({ texture: this.texture, origin: [0, 0, layer] }, baked.layers[layer], { bytesPerRow: baked.width * 4, rowsPerImage: baked.height }, { width: baked.width, height: baked.height, depthOrArrayLayers: 1 });
+            }
         }
         else if (blocks !== null) {
             /* Refused before anything is allocated; the stored chain, or level 0 alone where no chain
@@ -230,8 +251,9 @@ export class GpuSurfaceTexture {
                 ? Math.max(1, Math.floor(options.anisotropy ?? DEFAULT_ANISOTROPY))
                 : 1,
         });
-        if (blocks === null && baked === null)
+        if (blocks === null && baked === null && capture === null) {
             this.upload(listed);
+        }
         /* Half floats, as `renderer.ts` uploads it: filterable, so the ordinary float layout takes it,
            and read by `textureLoad` alone, so the filter never runs. */
         const effects = options.effects ?? [];
@@ -255,6 +277,10 @@ export class GpuSurfaceTexture {
     get view() {
         return this.current;
     }
+    /** The only layer as a plain 2D view, which a scene capture's pass resolves into. */
+    layerView() {
+        return (this.texture?.createView({ dimension: '2d', baseArrayLayer: 0, arrayLayerCount: 1 }) ?? null);
+    }
     /**
      * Replace the pixels, keeping the handle and its sampler.
      *

package/dist/render/backend/webgpu/waterPass.d.ts

@@ -11,7 +11,7 @@ import type { UniformFields } from './scatterPass.ts';
 export declare const WATER_VERT_FIELDS: UniformFields;
 export declare const WATER_VERT_SIZE: 208;
 export declare const WATER_FRAG_FIELDS: UniformFields;
-export declare const WATER_FRAG_SIZE: 1248;
+export declare const WATER_FRAG_SIZE: 1504;
 /** The two meshes and the numbers the grid decided, behind the surface's opaque handle. */
 export interface GpuWater {
     /** The ocean: near sheet and far skirt in one buffer. */

package/dist/render/clusteredLights.d.ts

@@ -85,7 +85,7 @@ export declare const MAX_CLUSTERED_LIGHTS = 320;
  * it cannot. That is what lets a light index the shadow uniforms by a number read from a texture,
  * and it is the same fact the octahedral array texture was built on.
  */
-export declare const LIGHT_TEXELS = 5;
+export declare const LIGHT_TEXELS = 6;
 /**
  * Where each field of a light's record sits, as an offset in `uint`s from `lightBase`.
  *
@@ -115,7 +115,11 @@ export declare const LIGHT_TEXELS = 5;
  * **Reordered 2026-10-02 so a plain light's fields are the first eight**, which is what lets the
  * shader stop after two texels. Nine values are needed by every light and eight fit in two
  * texels, so the emitter size and the weight share slot 7 as two halves; see `packSizeAndWeight`.
- * Slot 19 is spare.
+ *
+ * **A sixth texel arrived in 4.8.7 for a light's own falloff exponent**, the fifth's last slot
+ * having gone to the channels: 6 KB more of a table near 300, read only for a light whose record
+ * carries a fixture, which a light with an exponent does. Slots 21 and 22 are a rectangle's barn
+ * doors and spare on a lamp; slot 23 is spare.
  */
 export declare const LIGHT_RECORD: {
     readonly positionX: 0;
@@ -146,6 +150,11 @@ export declare const LIGHT_RECORD: {
      * last texels are fetched; a plain light's are not, and the shader takes the default for it.
      */
     readonly channels: 19;
+    /** The light's own falloff exponent, or 0 for the frame's falloff. `PointLightSource.falloffExponent`. */
+    readonly falloffExponent: 20;
+    /** A rectangle's barn doors: the cosine of their angle from its normal, then their length in metres. */
+    readonly barnDoorCos: 21;
+    readonly barnDoorLength: 22;
 };
 /** The lighting channel every light and every surface is on unless it says otherwise. */
 export declare const DEFAULT_LIGHT_CHANNELS = 1;
@@ -155,10 +164,16 @@ export declare const DEFAULT_LIGHT_CHANNELS = 1;
  * this, so a light named badly is on channel 1 in both rather than on two different guesses.
  */
 export declare function lightChannelsOf(value: number | undefined): number;
+/**
+ * A light's own falloff exponent as the shader reads it: a positive finite number, or 0 for the
+ * frame's falloff where none was named or what was named is not one. The record and the uniform
+ * path both write this, so a light named badly falls off by the frame's rule in both.
+ */
+export declare function lightFalloffExponentOf(value: number | undefined): number;
 /** Texels the lit pass reads for a light whose record carries no fixture. */
 export declare const PLAIN_LIGHT_TEXELS = 2;
 /**
- * The bit of `sizeAndWeight` that says the record's last three texels hold something: the sign of
+ * The bit of `sizeAndWeight` that says the record's last four texels hold something: the sign of
  * the emitter size's half, which a size never needs.
  */
 export declare const LIGHT_FIXTURE_FLAG = 32768;
@@ -287,6 +302,8 @@ export interface ClusterLightSet {
     readonly iesProfiles?: Float32Array;
     /** One per light: its lighting channels. See `PointLightSet.lightChannels`. */
     readonly channels?: Float32Array;
+    /** One per light: its own falloff exponent, or 0. See `PointLightSource.falloffExponent`. */
+    readonly falloffExponents?: Float32Array;
     /**
      * The rectangles shaded through the table, after the `count` point lights: those of `areas` from
      * `areaFrom` on, `areaCount` of them. The ones before `areaFrom` are the fixed arm's, which is
@@ -310,6 +327,7 @@ export interface ClusterLightArrays {
     readonly lightIesAxes?: Float32Array;
     readonly lightCookies?: Float32Array;
     readonly lightChannels?: Float32Array;
+    readonly lightFalloffExponents?: Float32Array;
     readonly areaLights?: AreaLightBuffer | null;
 }
 /** A `ClusterLightSet` a renderer refills every frame. */
@@ -336,8 +354,8 @@ export declare function fillClusterLightSet(env: ClusterLightArrays, out: Cluste
 /** How many rectangles the fixed arm shades; the rest of the buffer is clustered. */
 areaFrom?: number): ClusterLightSet;
 /**
- * Whether a light's record needs its last three texels: it holds a shadow slot, a cone, a profile
- * or a cookie. Everything else is a plain light, read in `PLAIN_LIGHT_TEXELS`.
+ * Whether a light's record needs its last four texels: it holds a shadow slot, a cone, a profile,
+ * a cookie, channels of its own or a falloff exponent of its own. Everything else is a plain light, read in `PLAIN_LIGHT_TEXELS`.
  *
  * **`shadowSlots` is zero where the lit shader has no point shadows**, and both binners are handed
  * it that way: a slot is only read under `POINT_SHADOWS`, so a light holding one in a build without

package/dist/render/clusteredLights.js

@@ -84,7 +84,7 @@ export const MAX_CLUSTERED_LIGHTS = 320;
  * it cannot. That is what lets a light index the shadow uniforms by a number read from a texture,
  * and it is the same fact the octahedral array texture was built on.
  */
-export const LIGHT_TEXELS = 5;
+export const LIGHT_TEXELS = 6;
 /**
  * Where each field of a light's record sits, as an offset in `uint`s from `lightBase`.
  *
@@ -114,7 +114,11 @@ export const LIGHT_TEXELS = 5;
  * **Reordered 2026-10-02 so a plain light's fields are the first eight**, which is what lets the
  * shader stop after two texels. Nine values are needed by every light and eight fit in two
  * texels, so the emitter size and the weight share slot 7 as two halves; see `packSizeAndWeight`.
- * Slot 19 is spare.
+ *
+ * **A sixth texel arrived in 4.8.7 for a light's own falloff exponent**, the fifth's last slot
+ * having gone to the channels: 6 KB more of a table near 300, read only for a light whose record
+ * carries a fixture, which a light with an exponent does. Slots 21 and 22 are a rectangle's barn
+ * doors and spare on a lamp; slot 23 is spare.
  */
 export const LIGHT_RECORD = {
     positionX: 0,
@@ -145,6 +149,11 @@ export const LIGHT_RECORD = {
      * last texels are fetched; a plain light's are not, and the shader takes the default for it.
      */
     channels: 19,
+    /** The light's own falloff exponent, or 0 for the frame's falloff. `PointLightSource.falloffExponent`. */
+    falloffExponent: 20,
+    /** A rectangle's barn doors: the cosine of their angle from its normal, then their length in metres. */
+    barnDoorCos: 21,
+    barnDoorLength: 22,
 };
 /** The lighting channel every light and every surface is on unless it says otherwise. */
 export const DEFAULT_LIGHT_CHANNELS = 1;
@@ -159,10 +168,18 @@ export function lightChannelsOf(value) {
     }
     return value;
 }
+/**
+ * A light's own falloff exponent as the shader reads it: a positive finite number, or 0 for the
+ * frame's falloff where none was named or what was named is not one. The record and the uniform
+ * path both write this, so a light named badly falls off by the frame's rule in both.
+ */
+export function lightFalloffExponentOf(value) {
+    return value !== undefined && Number.isFinite(value) && value > 0 ? value : 0;
+}
 /** Texels the lit pass reads for a light whose record carries no fixture. */
 export const PLAIN_LIGHT_TEXELS = 2;
 /**
- * The bit of `sizeAndWeight` that says the record's last three texels hold something: the sign of
+ * The bit of `sizeAndWeight` that says the record's last four texels hold something: the sign of
  * the emitter size's half, which a size never needs.
  */
 export const LIGHT_FIXTURE_FLAG = 0x8000;
@@ -392,6 +409,7 @@ areaFrom = 0) {
     out.iesAxes = env.lightIesAxes;
     out.cookies = env.lightCookies;
     out.channels = env.lightChannels;
+    out.falloffExponents = env.lightFalloffExponents;
     return out;
 }
 /*
@@ -436,8 +454,8 @@ function distanceSqToBounds(x, y, z, b) {
     return dx * dx + dy * dy + dz * dz;
 }
 /**
- * Whether a light's record needs its last three texels: it holds a shadow slot, a cone, a profile
- * or a cookie. Everything else is a plain light, read in `PLAIN_LIGHT_TEXELS`.
+ * Whether a light's record needs its last four texels: it holds a shadow slot, a cone, a profile,
+ * a cookie, channels of its own or a falloff exponent of its own. Everything else is a plain light, read in `PLAIN_LIGHT_TEXELS`.
  *
  * **`shadowSlots` is zero where the lit shader has no point shadows**, and both binners are handed
  * it that way: a slot is only read under `POINT_SHADOWS`, so a light holding one in a build without
@@ -453,7 +471,8 @@ export function lightHasFixture(lights, light, shadowSlots) {
         (cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER) !== POINT_LIGHT_COS_OUTER ||
         (lights.iesProfiles?.[light] ?? NO_IES_PROFILE) >= 0 ||
         (lights.cookies?.[light] ?? NO_IES_PROFILE) >= 0 ||
-        lightChannelsOf(lights.channels?.[light]) !== DEFAULT_LIGHT_CHANNELS);
+        lightChannelsOf(lights.channels?.[light]) !== DEFAULT_LIGHT_CHANNELS ||
+        lightFalloffExponentOf(lights.falloffExponents?.[light]) > 0);
 }
 /**
  * The value of `uClustered` for a frame: 0 with clustering off, 1 when every light is plain, 2 when
@@ -525,6 +544,10 @@ export function writeLightRecord(lights, light, shadowSlots, out, at) {
     out[at + LIGHT_RECORD.iesAxisY] = floatBits(axes?.[light * 3 + 1] ?? 0);
     out[at + LIGHT_RECORD.iesAxisZ] = floatBits(axes?.[light * 3 + 2] ?? 0);
     out[at + LIGHT_RECORD.channels] = floatBits(lightChannelsOf(lights.channels?.[light]));
+    out[at + LIGHT_RECORD.falloffExponent] = floatBits(lightFalloffExponentOf(lights.falloffExponents?.[light]));
+    out[at + LIGHT_RECORD.barnDoorCos] = 0;
+    out[at + LIGHT_RECORD.barnDoorLength] = 0;
+    out[at + LIGHT_RECORD.barnDoorLength + 1] = 0;
 }
 /**
  * Which rectangle of the area buffer clustered light `light` is, for a light past the point
@@ -535,9 +558,9 @@ function areaSlot(lights, light) {
 }
 /**
  * A rectangle's record, which the shader tells from a lamp's by its **negative radius** — its
- * reach, negated — and reads to its fifth texel: sidedness where a lamp keeps its shadow slot,
+ * reach, negated — and reads to its sixth texel: sidedness where a lamp keeps its shadow slot,
  * the right axis where a spot keeps its direction, the half extents where its cone is, the up
- * axis where the azimuth is, and the channels last. Never shadowed: a rectangle's occlusion is
+ * axis where the azimuth is, the channels, and the barn doors in the sixth. Never shadowed: a rectangle's occlusion is
  * the fixed arm's, which is why the first `maxAreaLights` stay there.
  */
 function writeAreaRecord(lights, light, out, at) {
@@ -568,6 +591,10 @@ function writeAreaRecord(lights, light, out, at) {
     out[at + LIGHT_RECORD.iesAxisY] = floatBits(up?.[a * 3 + 1] ?? 1);
     out[at + LIGHT_RECORD.iesAxisZ] = floatBits(up?.[a * 3 + 2] ?? 0);
     out[at + LIGHT_RECORD.channels] = floatBits(DEFAULT_LIGHT_CHANNELS);
+    out[at + LIGHT_RECORD.falloffExponent] = 0;
+    out[at + LIGHT_RECORD.barnDoorCos] = floatBits(areas?.barnDoors?.[a * 2] ?? 0);
+    out[at + LIGHT_RECORD.barnDoorLength] = floatBits(areas?.barnDoors?.[a * 2 + 1] ?? 0);
+    out[at + LIGHT_RECORD.barnDoorLength + 1] = 0;
 }
 /** A clustered rectangle's reach, which its record carries negated. See `AreaLightSource.range`. */
 function areaReach(lights, light) {

package/dist/render/displayRange.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Which dynamic range the frame goes out in, and why: the one decision behind
+ * `RenderQuality.highDynamicRange`, made here so both backends answer it in the same words.
+ *
+ * **A high range is asked for, found, and held, or it is not had.** Three things must all be true:
+ * the profile asked; the frame has a composite holding light past white (`screenEffects` and
+ * `hdrScene`), since every other pass writes display values already clipped; and the display says
+ * it can show more than paper white. The backend then has to be able to configure such a canvas,
+ * which only it knows, and it may still answer standard after this says high.
+ *
+ * **What a high range gives up** is nothing a standard frame had: paper white stays where it is,
+ * and only what was above it — a lamp, a flash, a sunlit edge — goes on rising to the display's
+ * peak instead of rolling off at white. **What would make it wrong** is a display that reports a
+ * high range it cannot show, which a page cannot detect and the platform owns.
+ */
+export type DisplayRange = 'high' | 'standard';
+export interface DisplayRangeChoice {
+    readonly range: DisplayRange;
+    /** A sentence saying why, for `RendererApi.displayRangeReason`. */
+    readonly reason: string;
+}
+/** The display's own answer, as the browser gives it. A host without a DOM supplies its own. */
+export declare function browserHighDynamicRange(): boolean;
+/** The range a profile gets on a display, before the backend has tried to configure it. */
+export declare function chooseDisplayRange(asked: boolean, composite: boolean, displayIsHigh: boolean): DisplayRangeChoice;
+/**
+ * The display's peak over the frame's paper white, as `setDisplayLuminance` is handed it: at
+ * least 1, and 1 where the range is standard or a number is not one. Capped at 64, a thousand nits
+ * over a sixteen-nit white, which no display reaches and no curve should be asked to.
+ */
+export declare function displayHeadroom(range: DisplayRange, paperWhite: number, peak: number): number;

package/dist/render/displayRange.js

@@ -0,0 +1,47 @@
+/**
+ * Which dynamic range the frame goes out in, and why: the one decision behind
+ * `RenderQuality.highDynamicRange`, made here so both backends answer it in the same words.
+ *
+ * **A high range is asked for, found, and held, or it is not had.** Three things must all be true:
+ * the profile asked; the frame has a composite holding light past white (`screenEffects` and
+ * `hdrScene`), since every other pass writes display values already clipped; and the display says
+ * it can show more than paper white. The backend then has to be able to configure such a canvas,
+ * which only it knows, and it may still answer standard after this says high.
+ *
+ * **What a high range gives up** is nothing a standard frame had: paper white stays where it is,
+ * and only what was above it — a lamp, a flash, a sunlit edge — goes on rising to the display's
+ * peak instead of rolling off at white. **What would make it wrong** is a display that reports a
+ * high range it cannot show, which a page cannot detect and the platform owns.
+ */
+/** The display's own answer, as the browser gives it. A host without a DOM supplies its own. */
+export function browserHighDynamicRange() {
+    // platform: browser default — `CreateRendererOptions.highDynamicRangeDisplay` replaces it
+    return typeof matchMedia === 'function' && matchMedia('(dynamic-range: high)').matches;
+}
+/** The range a profile gets on a display, before the backend has tried to configure it. */
+export function chooseDisplayRange(asked, composite, displayIsHigh) {
+    if (!asked)
+        return { range: 'standard', reason: 'highDynamicRange was not asked for' };
+    if (!composite) {
+        return {
+            range: 'standard',
+            reason: 'highDynamicRange needs screenEffects and hdrScene: without a composite holding light ' +
+                'past white, every pass writes values already clipped to it',
+        };
+    }
+    if (!displayIsHigh) {
+        return { range: 'standard', reason: 'the display reports a standard dynamic range' };
+    }
+    return { range: 'high', reason: 'an extended-range canvas on a high dynamic range display' };
+}
+/**
+ * The display's peak over the frame's paper white, as `setDisplayLuminance` is handed it: at
+ * least 1, and 1 where the range is standard or a number is not one. Capped at 64, a thousand nits
+ * over a sixteen-nit white, which no display reaches and no curve should be asked to.
+ */
+export function displayHeadroom(range, paperWhite, peak) {
+    if (range !== 'high')
+        return 1;
+    const ratio = peak / paperWhite;
+    return Number.isFinite(ratio) ? Math.min(Math.max(ratio, 1), 64) : 1;
+}

package/dist/render/driftLight/bake.d.ts

@@ -26,6 +26,8 @@ export interface FieldLight extends LightReach {
     readonly b: number;
     /** The emitter's physical radius, which widens its penumbra. */
     readonly sourceRadius: number;
+    /** Its own falloff exponent, overriding the frame's above zero. See `pointLightShape`. */
+    readonly falloffExponent?: number;
 }
 /**
  * Fill `light` and `direction`, `BRICK_TEXELS * 4` floats each, x fastest, for brick `brick`.

package/dist/render/driftLight/bake.js

@@ -66,7 +66,7 @@ export function sampleFieldLight(px, py, pz, lights, candidates, first, last, fa
         const dist = Math.hypot(dx, dy, dz);
         if (dist >= source.radius)
             continue;
-        const shape = pointLightShape(dist, source.radius, falloff);
+        const shape = pointLightShape(dist, source.radius, falloff, source.falloffExponent);
         if (shape <= 0)
             continue;
         const seen = distance === null

package/dist/render/driftLight/falloff.d.ts

@@ -9,8 +9,10 @@
  *
  * Both of the renderer's falloffs: `smooth`, the default, is a linear ramp squared, reaching zero at
  * the radius; `inverseSquare` is physical, windowed so it still reaches zero at the radius, and
- * floored at ten centimetres so a surface touching a light is not infinitely bright.
+ * floored at ten centimetres so a surface touching a light is not infinitely bright. And a light's
+ * own, which overrides both: `(1 - (d/R)^2)^n` with no distance term, for an exponent `n` above zero
+ * (`PointLightSource.falloffExponent`).
  */
 export type PointLightFalloff = 'smooth' | 'inverseSquare';
 /** The shader's `shape` for an unshaped point light: no cone, no photometric profile. */
-export declare function pointLightShape(dist: number, radius: number, falloff: PointLightFalloff): number;
+export declare function pointLightShape(dist: number, radius: number, falloff: PointLightFalloff, exponent?: number): number;

package/dist/render/driftLight/falloff.js

@@ -9,10 +9,16 @@
  *
  * Both of the renderer's falloffs: `smooth`, the default, is a linear ramp squared, reaching zero at
  * the radius; `inverseSquare` is physical, windowed so it still reaches zero at the radius, and
- * floored at ten centimetres so a surface touching a light is not infinitely bright.
+ * floored at ten centimetres so a surface touching a light is not infinitely bright. And a light's
+ * own, which overrides both: `(1 - (d/R)^2)^n` with no distance term, for an exponent `n` above zero
+ * (`PointLightSource.falloffExponent`).
  */
 /** The shader's `shape` for an unshaped point light: no cone, no photometric profile. */
-export function pointLightShape(dist, radius, falloff) {
+export function pointLightShape(dist, radius, falloff, exponent = 0) {
+    if (exponent > 0) {
+        const reach = dist / Math.max(radius, 1e-4);
+        return Math.min(1, Math.max(0, 1 - reach * reach)) ** exponent;
+    }
     if (falloff === 'inverseSquare') {
         const ratio = dist / Math.max(radius, 1e-4);
         const window = Math.min(1, Math.max(0, 1 - ratio ** 4));