@driftengine/core 4.8.5 → 4.8.7

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

@@ -1,4 +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. */
@@ -62,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[], 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,5 +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';
@@ -155,13 +157,46 @@ export class GpuSurfaceTexture {
     constructor(device, pipelines, source, options = {}, compressed = []) {
         this.device = device;
         this.pipelines = pipelines;
-        const listed = (Array.isArray(source) ? source : [source]);
+        /* 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 || 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 = srgb ? 'rgba8unorm-srgb' : 'rgba8unorm';
-        if (blocks !== 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.length;
+            this.blockFormat = null;
+            this.mipmapped = false;
+            this.width = baked.width;
+            this.height = baked.height;
+            this.levels = 1;
+            this.texture = this.allocate();
+            /* 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
                was asked for. See `compressedUpload.ts`. */
             const plan = planBlocks(blocks, srgb, compressed);
@@ -216,8 +251,9 @@ export class GpuSurfaceTexture {
                 ? Math.max(1, Math.floor(options.anisotropy ?? DEFAULT_ANISOTROPY))
                 : 1,
         });
-        if (blocks === 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 ?? [];
@@ -241,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/bloomChain.d.ts

@@ -57,6 +57,50 @@ export declare function bloomProfileWarning(quality: {
     readonly hdrScene: boolean;
     readonly bloomThreshold: number;
 }): string | null;
+/**
+ * How a frame's bloom answers the light it is given, beside the strength and threshold `setBloom`
+ * already takes. Absent, or a field absent, is the response every frame had before 4.8.6.
+ *
+ * **Why it exists: one band over the colour less the threshold washes a stage built for another
+ * engine.** Unreal's standard bloom keeps `saturate((L − threshold) / 2)` of a colour rather than
+ * the colour less the threshold, and spreads it over six bands, each in a tint of its own. A
+ * stage authored against that — a threshold of 0.1 and tints summing below one — came out white
+ * here, because subtracting so low a threshold keeps nearly every light in the frame at full
+ * strength. These are the two things that differ, as numbers.
+ */
+export interface BloomResponse {
+    /**
+     * Scene units over which a colour comes in, from none of it at the threshold to all of it this
+     * far past. **0, the default, subtracts instead**: a colour keeps what it has past the threshold,
+     * the response since bloom shipped. Unreal's is 2 after exposure, so a frame exposed by `e` that
+     * wants it passes `2 / e`, as it passes the threshold over the exposure.
+     *
+     * Brightness is still the largest channel rather than luminance, for the reason
+     * `shaders/bloom.ts` gives; on a neutral colour the two are equal.
+     */
+    readonly ramp?: number;
+    /**
+     * Each level's colour, three numbers a level, finest first: the halo at a few pixels first and
+     * at a twentieth of the frame last. **White, the default, is the identity**; a level not named
+     * takes white. Not clamped above one, which is how a tint carries a strength past the 0..1 the
+     * dial gives — a stage asking for twice the light names tints twice as bright.
+     *
+     * At most `BLOOM_LEVELS` levels. A frame too small for that many uses the first it has room for.
+     */
+    readonly tints?: ArrayLike<number>;
+}
+/** Floats `resolveBloomResponse` writes: the ramp, then a tint a level. */
+export declare const BLOOM_RESPONSE_FLOATS: number;
+/**
+ * A response as both backends bind it, into a caller-owned `out` of `BLOOM_RESPONSE_FLOATS`: the
+ * ramp, then `BLOOM_LEVELS` tints, white where none was named. Refuses a tint list that is not
+ * whole colours or names more levels than the pyramid has, naming the length — a caller error with
+ * one correct outcome. A ramp that is not a positive number is the subtraction; a tint channel
+ * that is not a number or is below zero is zero.
+ */
+export declare function resolveBloomResponse(response: BloomResponse | null | undefined, out: Float32Array): void;
+/** The response every frame had before 4.8.6: the subtraction, every level white. */
+export declare function defaultBloomResponse(): Float32Array;
 /** One level of the pyramid: level 0 is half the frame and each one after it half again. */
 export interface BloomLevelSize {
     readonly width: number;

package/dist/render/bloomChain.js

@@ -67,6 +67,34 @@ export function bloomProfileWarning(quality) {
     }
     return null;
 }
+/** Floats `resolveBloomResponse` writes: the ramp, then a tint a level. */
+export const BLOOM_RESPONSE_FLOATS = 1 + BLOOM_LEVELS * 3;
+/**
+ * A response as both backends bind it, into a caller-owned `out` of `BLOOM_RESPONSE_FLOATS`: the
+ * ramp, then `BLOOM_LEVELS` tints, white where none was named. Refuses a tint list that is not
+ * whole colours or names more levels than the pyramid has, naming the length — a caller error with
+ * one correct outcome. A ramp that is not a positive number is the subtraction; a tint channel
+ * that is not a number or is below zero is zero.
+ */
+export function resolveBloomResponse(response, out) {
+    const ramp = response?.ramp ?? 0;
+    out[0] = Number.isFinite(ramp) && ramp > 0 ? ramp : 0;
+    const tints = response?.tints;
+    if (tints !== undefined && (tints.length % 3 !== 0 || tints.length > BLOOM_LEVELS * 3)) {
+        throw new Error(`setBloom: ${tints.length} tint values is not up to ${BLOOM_LEVELS} whole colours, three ` +
+            'numbers a level, finest first');
+    }
+    for (let i = 0; i < BLOOM_LEVELS * 3; i++) {
+        const value = tints !== undefined && i < tints.length ? tints[i] : 1;
+        out[1 + i] = Number.isFinite(value) && value > 0 ? value : 0;
+    }
+}
+/** The response every frame had before 4.8.6: the subtraction, every level white. */
+export function defaultBloomResponse() {
+    const out = new Float32Array(BLOOM_RESPONSE_FLOATS);
+    resolveBloomResponse(null, out);
+    return out;
+}
 /**
  * The pyramid for a frame of this size, largest first, or an empty list where none would fit.
  *

package/dist/render/bloomPass.d.ts

@@ -46,7 +46,9 @@ export declare class BloomPass {
      * `threshold` is in scene units, so it only separates a light from white paint on a target
      * that kept the range. The caller owns that decision and the warning that goes with it.
      */
-    run(scene: WebGLTexture, width: number, height: number, threshold: number): WebGLTexture | null;
+    run(scene: WebGLTexture, width: number, height: number, threshold: number, 
+    /** The ramp, then each level's tint: `resolveBloomResponse`'s floats. */
+    response: Float32Array): WebGLTexture | null;
     /** One source texel in UV, which is what the thirteen taps are laid out in. */
     private uploadTexel;
     private release;

package/dist/render/bloomPass.js

@@ -130,7 +130,9 @@ export class BloomPass {
      * `threshold` is in scene units, so it only separates a light from white paint on a target
      * that kept the range. The caller owns that decision and the warning that goes with it.
      */
-    run(scene, width, height, threshold) {
+    run(scene, width, height, threshold, 
+    /** The ramp, then each level's tint: `resolveBloomResponse`'s floats. */
+    response) {
         if (!this.ensureSize(width, height))
             return null;
         const { gl } = this;
@@ -153,6 +155,7 @@ export class BloomPass {
         gl.bindTexture(gl.TEXTURE_2D, scene);
         gl.uniform1i(this.prefilterUniforms['uSource'] ?? null, 0);
         gl.uniform1f(this.prefilterUniforms['uThreshold'] ?? null, threshold);
+        gl.uniform1f(this.prefilterUniforms['uRamp'] ?? null, response[0] ?? 0);
         this.uploadTexel(this.prefilterUniforms, width, height);
         gl.drawArrays(gl.TRIANGLES, 0, 3);
         /* Down the chain. Each level reads the one above it, which was written a draw ago. */
@@ -174,8 +177,13 @@ export class BloomPass {
          * every octave at once. Additive blending rather than a second target to ping-pong through:
          * a level is only ever read while a *different* level is bound, so there is no feedback.
          */
+        /*
+         * Each level's tint rides the blend: the level being added onto is multiplied by its own as the
+         * octave below is added, and the deepest by `uScale` on the first draw, the only one reading it
+         * before anything has been added to it. White everywhere is `ONE, ONE` exactly.
+         */
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.ONE, gl.ONE);
+        gl.blendFunc(gl.ONE, gl.CONSTANT_COLOR);
         gl.useProgram(this.upsampleProgram);
         gl.uniform1i(this.upsampleUniforms['uSource'] ?? null, 0);
         gl.uniform1f(this.upsampleUniforms['uRadius'] ?? null, BLOOM_FILTER_RADIUS_UV);
@@ -184,11 +192,17 @@ export class BloomPass {
             const source = levels[index];
             if (target === undefined || source === undefined)
                 break;
+            const deepest = index === levels.length - 1;
+            const into = 1 + (index - 1) * 3;
+            const from = 1 + index * 3;
+            gl.blendColor(response[into] ?? 1, response[into + 1] ?? 1, response[into + 2] ?? 1, 1);
+            gl.uniform3f(this.upsampleUniforms['uScale'] ?? null, deepest ? (response[from] ?? 1) : 1, deepest ? (response[from + 1] ?? 1) : 1, deepest ? (response[from + 2] ?? 1) : 1);
             gl.bindFramebuffer(gl.FRAMEBUFFER, target.framebuffer);
             gl.viewport(0, 0, target.width, target.height);
             gl.bindTexture(gl.TEXTURE_2D, source.texture);
             gl.drawArrays(gl.TRIANGLES, 0, 3);
         }
+        gl.blendColor(0, 0, 0, 0);
         gl.disable(gl.BLEND);
         gl.bindVertexArray(null);
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);

package/dist/render/clusteredLights.d.ts

@@ -1,3 +1,4 @@
+import type { AreaLightBuffer } from './areaLights.ts';
 /**
  * The froxel table: what it looks like in memory, and the CPU binner that fills it.
  *
@@ -84,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`.
  *
@@ -114,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;
@@ -139,11 +144,36 @@ export declare const LIGHT_RECORD: {
     readonly iesAxisX: 16;
     readonly iesAxisY: 17;
     readonly iesAxisZ: 18;
+    /**
+     * The light's lighting channels, a mask (`PointLightSet.lightChannels`), in the slot that was
+     * spare. A light naming channels other than the default is read as carrying a fixture, so its
+     * 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;
+/**
+ * A light's channels as the shader compares them: a whole mask from 1 to 255, or the default where
+ * none was named or what was named is not one. The froxel record and the uniform path both write
+ * 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;
@@ -270,6 +300,18 @@ export interface ClusterLightSet {
     readonly cookies?: Float32Array;
     /** One per light: an index into the IES atlas, or −1. */
     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
+     * where a rectangle's shadow lives. Absent, there are none.
+     */
+    readonly areas?: AreaLightBuffer | null;
+    readonly areaFrom?: number;
+    readonly areaCount?: number;
 }
 /** Where `fillClusterLightSet` reads a frame's lights from: the arrays `Environment` carries. */
 export interface ClusterLightArrays {
@@ -284,6 +326,9 @@ export interface ClusterLightArrays {
     readonly lightIesProfiles?: Float32Array;
     readonly lightIesAxes?: Float32Array;
     readonly lightCookies?: Float32Array;
+    readonly lightChannels?: Float32Array;
+    readonly lightFalloffExponents?: Float32Array;
+    readonly areaLights?: AreaLightBuffer | null;
 }
 /** A `ClusterLightSet` a renderer refills every frame. */
 export type ClusterLightScratch = {
@@ -305,10 +350,12 @@ export declare function createClusterLightSet(): ClusterLightScratch;
  * radius in its place, an emitter as wide as the light reaches, which widened every lamp's
  * highlight on a specular surface on the clustered arm alone.
  */
-export declare function fillClusterLightSet(env: ClusterLightArrays, out: ClusterLightScratch): ClusterLightSet;
+export declare function fillClusterLightSet(env: ClusterLightArrays, out: ClusterLightScratch, 
+/** 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
@@ -343,6 +390,8 @@ export declare function clusteredMode(lights: ClusterLightSet, count: number, sh
  * is a light without a map, which is what a scene with two hundred lamps has anyway.
  */
 export declare function writeLightRecord(lights: ClusterLightSet, light: number, shadowSlots: number, out: Uint32Array, at: number): void;
+/** How many lights the table carries: the point lights and the clustered rectangles after them. */
+export declare function clusteredLightTotal(lights: ClusterLightSet): number;
 /**
  * Fill the table with this frame's light assignment, and answer how many lights it carried.
  *
@@ -389,3 +438,26 @@ export declare function writeLightRecord(lights: ClusterLightSet, light: number,
  * Fills a caller-owned table and allocates nothing.
  */
 export declare function buildLightClusters(lights: ClusterLightSet, view: Float32Array, near: number, far: number, tanHalfFovY: number, aspect: number, table: Uint32Array, shadowSlots: number): number;
+/**
+ * How far a froxel lies outside a spot's cone, in metres, or a negative number where the cone
+ * reaches it: positive is a froxel the light cannot shade. Everything in view space with depth
+ * positive, as the binner holds it; `axis` is unit length and `cosA`, `sinA` are the outer cone's.
+ *
+ * **The froxel's bounding sphere against the infinite cone**, after Wronski's cone test for
+ * clustered spots. With `V` from the apex to the sphere's centre at an angle `θ` from the axis and
+ * `A` the cone's half-angle, the centre's distance from the cone is `|V| sin(θ − A)` — which is
+ * `cosA |V⊥| − (V·axis) sinA` — while `θ − A` is under a right angle, and `|V|` past it, where the
+ * nearest point of the cone is its apex. Inside the cone it is negative. So the gap is exact for
+ * the sphere, and the sphere holds the froxel: the test can only keep a light, never drop one the
+ * shader would draw. The apex case is what drops a froxel behind a spot whose sphere reaches it,
+ * which the formula alone underestimates.
+ *
+ * **What it gives up** is tightness at the near end of the frustum, where a froxel is a long thin
+ * box whose sphere is much larger than it: a spot grazing such a froxel is kept. **What would make
+ * it wrong** is a profile showing those near froxels hold the cost; testing the box's corners is
+ * the tight version, at eight dot products a pair.
+ *
+ * Exported so the conformance page can tell a disagreement at the cone's edge from a real one; the
+ * GPU binner writes the same arithmetic in WGSL.
+ */
+export declare function coneBoxGap(px: number, py: number, pz: number, axisX: number, axisY: number, axisZ: number, cosA: number, sinA: number, box: Float32Array): number;