@woosh/meep-engine 3.37.0 → 3.39.0

package/src/engine/physics/vehicle/RaycastVehicle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RaycastVehicle.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/vehicle/RaycastVehicle.js"],"names":[],"mappings":"AA+EA;;;;GAIG;AACH;IAEI,8DAA8D;IAC9D,eAD8C,YAAY,CACtB;IAEpC,8EAA8E;IAC9E,oBAD8D,YAAY,CACvB;IAEnD,sEAAsE;IACtE,cADsD,YAAY,CACtB;IAE5C,4BAA0B;IAC1B,0BAAuB;IACvB,2BAA8B;IAC9B,eAAa;IACb,iBAAe;IACf,iBAAgB;IAChB,gBAAe;IAGf,mBAAkB;IAElB,oBAAgB;IAEhB,gDAAgD;IAChD,cADgC,YAAY,CACT;IAEnC,iDAAiD;IACjD,eADiC,YAAY,CACA;IAE7C,qDAAqD;IACrD,sBAAmB;IAEnB,gFAAgF;IAChF,iBAAa;IAEb,kDAAkD;IAClD,iBAAa;IAEb,iDAAiD;IACjD,qBAAiB;IAEjB,yDAAyD;IACzD,wBAAoB;IAGhB,6BAA+B;IAC/B,yBAAiD;CAExD;AAED;IAoBI;;;;OAIG;IACH,0FAOC;IA/BD,sBAAsB;IACtB,QADW,KAAK,EAAE,CACN;IAEZ,qBAAiB;IACjB,qBAAiB;IACjB,sBAAkB;IAClB,YAAmB;IACnB,2BAAkC;IAGlC,sBAA8B;IAE9B;;;;OAIG;IACH,SAFU,YAAY,CAEQ;IAQ1B,sBAAoB;IACpB,uBAA8B;IAC9B,8BAAwC;IAGxC,kDAAmF;IAGvF;;;;;;;;;;;;;;;;;OAiBG;IACH;QAb0B,aAAa,EAA5B,MAAM,EAAE;QACQ,kBAAkB,GAAlC,MAAM,EAAE;QACQ,YAAY,GAA5B,MAAM,EAAE;QACM,oBAAoB,GAAlC,MAAM;QACQ,mBAAmB,GAAjC,MAAM;QACQ,iBAAiB,GAA/B,MAAM;QACQ,kBAAkB,GAAhC,MAAM;QACQ,MAAM,GAApB,MAAM;QACQ,QAAQ,GAAtB,MAAM;QACS,OAAO,GAAtB,OAAO;QACQ,MAAM,GAArB,OAAO;QACL,KAAK,CA0BjB;IAED,2DAA2D;IAC3D,8BAIC;IAED,2EAA2E;IAC3E,gCAAmD;IAEnD,uEAAuE;IACvE,2BAA8C;IAE9C;;;;;OAKG;IACH,WAFW,MAAM,QAsIhB;CACJ;qBA7WoB,mCAAmC;oCACpB,mCAAmC"}
+{"version":3,"file":"RaycastVehicle.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/vehicle/RaycastVehicle.js"],"names":[],"mappings":"AA8EA;;;;GAIG;AACH;IAEI,8DAA8D;IAC9D,eAD8C,YAAY,CACtB;IAEpC,8EAA8E;IAC9E,oBAD8D,YAAY,CACvB;IAEnD,sEAAsE;IACtE,cADsD,YAAY,CACtB;IAE5C,4BAA0B;IAC1B,0BAAuB;IACvB,2BAA8B;IAC9B,eAAa;IACb,iBAAe;IACf,iBAAgB;IAChB,gBAAe;IAGf,mBAAkB;IAElB,oBAAgB;IAEhB,gDAAgD;IAChD,cADgC,YAAY,CACT;IAEnC,iDAAiD;IACjD,eADiC,YAAY,CACA;IAE7C,qDAAqD;IACrD,sBAAmB;IAEnB,gFAAgF;IAChF,iBAAa;IAEb,kDAAkD;IAClD,iBAAa;IAEb,iDAAiD;IACjD,qBAAiB;IAEjB,yDAAyD;IACzD,wBAAoB;IAGhB,6BAA+B;IAC/B,yBAAiD;CAExD;AAED;IAoBI;;;;OAIG;IACH,0FAOC;IA/BD,sBAAsB;IACtB,QADW,KAAK,EAAE,CACN;IAEZ,qBAAiB;IACjB,qBAAiB;IACjB,sBAAkB;IAClB,YAAmB;IACnB,2BAAkC;IAGlC,sBAA8B;IAE9B;;;;OAIG;IACH,SAFU,YAAY,CAEQ;IAQ1B,sBAAoB;IACpB,uBAA8B;IAC9B,8BAAwC;IAGxC,kDAAmF;IAGvF;;;;;;;;;;;;;;;;;OAiBG;IACH;QAb0B,aAAa,EAA5B,MAAM,EAAE;QACQ,kBAAkB,GAAlC,MAAM,EAAE;QACQ,YAAY,GAA5B,MAAM,EAAE;QACM,oBAAoB,GAAlC,MAAM;QACQ,mBAAmB,GAAjC,MAAM;QACQ,iBAAiB,GAA/B,MAAM;QACQ,kBAAkB,GAAhC,MAAM;QACQ,MAAM,GAApB,MAAM;QACQ,QAAQ,GAAtB,MAAM;QACS,OAAO,GAAtB,OAAO;QACQ,MAAM,GAArB,OAAO;QACL,KAAK,CA0BjB;IAED,2DAA2D;IAC3D,8BAIC;IAED,2EAA2E;IAC3E,gCAAmD;IAEnD,uEAAuE;IACvE,2BAA8C;IAE9C;;;;;OAKG;IACH,WAFW,MAAM,QAsIhB;CACJ;qBA5WoB,mCAAmC;oCACpB,mCAAmC"}

package/src/engine/physics/vehicle/RaycastVehicle.js

@@ -51,10 +51,9 @@ function effective_mass(rb, transform, invM, rx, ry, rz, dx, dy, dz) {
     let k = invM;
     const ii = rb.inverseInertiaLocal;
     if (ii[0] !== 0 || ii[1] !== 0 || ii[2] !== 0) {
-        const q = transform.rotation;
         k += angular_effective_mass_raw(
             ii[0], ii[1], ii[2],
-            q[0], q[1], q[2], q[3],
+            transform.rotation_x, transform.rotation_y, transform.rotation_z, transform.rotation_w,
             rx, ry, rz,
             dx, dy, dz,
             scratch_i
@@ -235,7 +234,7 @@ export class RaycastVehicle {
         if (rb.kind !== BodyKind.Dynamic || dt <= 0) return;
         const tr = this.chassisTransform;
         const invMass = rb.mass > 0 ? 1 / rb.mass : 0;
-        const q = tr.rotation;
+        const qx = tr.rotation_x, qy = tr.rotation_y, qz = tr.rotation_z, qw = tr.rotation_w;
         const px = tr.translation_x, py = tr.translation_y, pz = tr.translation_z;
         const lv = rb.linearVelocity, av = rb.angularVelocity;
         const drivePer = this.__drivenCount > 0 ? this.__driveForce / this.__drivenCount : 0;
@@ -244,9 +243,9 @@ export class RaycastVehicle {
             const w = this.wheels[wi];
 
             // World mount point and suspension axis.
-            v3_quaternion_apply(scratch_v, 0, w.localPosition[0], w.localPosition[1], w.localPosition[2], q[0], q[1], q[2], q[3]);
+            v3_quaternion_apply(scratch_v, 0, w.localPosition[0], w.localPosition[1], w.localPosition[2], qx, qy, qz, qw);
             const mx = px + scratch_v[0], my = py + scratch_v[1], mz = pz + scratch_v[2];
-            v3_quaternion_apply(scratch_v, 0, w.localSuspensionDir[0], w.localSuspensionDir[1], w.localSuspensionDir[2], q[0], q[1], q[2], q[3]);
+            v3_quaternion_apply(scratch_v, 0, w.localSuspensionDir[0], w.localSuspensionDir[1], w.localSuspensionDir[2], qx, qy, qz, qw);
             const sdx = scratch_v[0], sdy = scratch_v[1], sdz = scratch_v[2]; // suspension down (unit)
 
             const maxLen = w.suspensionRestLength + w.radius;
@@ -305,7 +304,7 @@ export class RaycastVehicle {
             }
 
             // --- Tyre friction: forward / side basis in the contact plane ---
-            v3_quaternion_apply(scratch_v, 0, w.localForward[0], w.localForward[1], w.localForward[2], q[0], q[1], q[2], q[3]);
+            v3_quaternion_apply(scratch_v, 0, w.localForward[0], w.localForward[1], w.localForward[2], qx, qy, qz, qw);
             let fwx = scratch_v[0], fwy = scratch_v[1], fwz = scratch_v[2];
             if (w.steering !== 0) {
                 // Steer about the suspension-up axis (−suspension dir).

package/src/shade/device/mock/SoftwareGPUQueue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUQueue.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUQueue.js"],"names":[],"mappings":"AA4DA;;;GAGG;AACH,yCAFgB,QAAQ;IAYpB;;OAEG;IACH,uCAEC;IAoDD;;;;;;;;;OASG;IACH,6CALW,MAAM,QACN,YAAY,eACZ,MAAM,SACN,MAAM,QA6ChB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,yDAJW,YAAY,iEAmCtB;IAED;;;;;;;;;;;;;OAaG;IACH,2IAmEC;IAED;;;OAGG;IACH,uBAFW,0BAA0B,QAmEpC;IAED;;;;;;OAMG;IACH,uBAFa,QAAQ,SAAS,CAAC,CAI9B;;CACJ"}
+{"version":3,"file":"SoftwareGPUQueue.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUQueue.js"],"names":[],"mappings":"AA6DA;;;GAGG;AACH,yCAFgB,QAAQ;IAYpB;;OAEG;IACH,uCAEC;IAoDD;;;;;;;;;OASG;IACH,6CALW,MAAM,QACN,YAAY,eACZ,MAAM,SACN,MAAM,QA6ChB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,yDAJW,YAAY,iEAmCtB;IAED;;;;;;;;;;;;;OAaG;IACH,2IAmEC;IAED;;;OAGG;IACH,uBAFW,0BAA0B,QAmEpC;IAED;;;;;;OAMG;IACH,uBAFa,QAAQ,SAAS,CAAC,CAI9B;;CACJ"}

package/src/shade/device/mock/SoftwareGPUQueue.js

@@ -19,7 +19,8 @@ const COPY_ALIGNMENT = 4;
  * @returns {{buffer: ArrayBuffer, byteOffset: number, byteLength: number, bytesPerElement: number}}
  */
 function normalize_buffer_source(data) {
-    if (data instanceof ArrayBuffer) {
+    // by tag, not `instanceof`: an ArrayBuffer from another realm is still one, and WebGPU takes it
+    if (Object.prototype.toString.call(data) === "[object ArrayBuffer]") {
         return { buffer: data, byteOffset: 0, byteLength: data.byteLength, bytesPerElement: 1 };
     }
 

package/src/shade/playground/path_traced_media/README.md

@@ -0,0 +1,78 @@
+# path_traced_media
+
+The path tracer's participating media: one scene to look at, and checks against closed-form answers. `npm run dev`, then
+`/src/shade/playground/path_traced_media/`. The design is in `PATH_TRACED_MEDIA_PLAN_2026_10_02.md`
+(`src/shade/renderer/path_tracer/`); this page is its device tier.
+
+**glass, water and fog** and **caustics under waves**, first in the list, are the ones to look at.
+The first: clear, amber and milky spheres and a tank of water with a block in it, on a checkerboard
+under the sun and the default sky (from `test_assets/` when it is there). The sun reaches the block
+through the water's surface; light through a sphere crosses two surfaces, which manifold NEE does not
+connect through, so the spheres still cast full shadows. The second: a pool whose surface is two
+crossing sine waves, its floor lit through them — the bright web is caustics, the waves' curvature
+focusing the sun.
+
+The checks below it are built for a number, not a picture, and look it: a slab filling the view is a
+flat colour, a white furnace is a grey square in which the object should vanish, a shadow check is
+floor in bands. Pick one to look at it converge, or press **run the checks**. Each check renders its scene with the
+accumulating path tracer for a fixed number of frames — one sample per pixel each — reads the radiance
+before the tone map at full precision, and compares rectangles of the image with what the scene must
+produce. A rectangle passes within four standard errors plus 0.2%. The standard error is the run's
+own noise: the accumulation is read halfway and at the end, and per pixel the two halves differ by
+noise alone — so structure across a rectangle, a dark arc where the answer is flat, cannot widen its
+own tolerance, as it did when each pixel was taken as an independent estimate of the mean. A check
+also fails if its run accumulated fewer samples than frames.
+From the console: `run_checks({ frames, only })` returns the report as data; `only` runs the checks whose
+name contains it.
+
+## The checks
+
+| check | what it pins | the answer |
+|---|---|---|
+| slab, index-matched, absorbing | free flight through a host medium; the boundary at n = 1 | `exp(-σ d / cos θ)` per pixel |
+| slab, glass n = 1.5, absorbing | exact Fresnel, refraction, the n² radiance law, every internal reflection | `(1 - F)² T / (1 - F² T²)` per pixel |
+| underwater camera | a path starting inside a medium finds it (the origin probe) | `exp(-σ 8 / cos θ)` per pixel |
+| underwater camera inside two overlapping meshes of the same water | the origin probe counts meshes, not media | the same |
+| slab, glass n = 1.5, absorbing, at 45 degrees | Fresnel, the refracted path and the internal reflections off the axis | `(1 - F)² T / (1 - F² T²)` at each pixel's angle to the slab |
+| smooth black tile in air | the specular bounce of a smooth surface | `F`, 0.04 head-on |
+| smooth black tile under water | a surface inside a medium reflects by the relative index | `F` at 1.5 / 1.333, 0.0035 head-on |
+| sunlit scattering half-space | light reaching scattering points, every order of scattering | `ω H(μ₀) H(μ) / (4 ρ (μ₀ + μ))`, Chandrasekhar, against the tile dry |
+| white furnace, clear glass sphere | interface and stack conserve energy, over the whole outline | the sky |
+| white furnace, scattering index-matched sphere | scattering and phase mixtures in a mesh-bounded medium | the sky |
+| white furnace, scattering glass sphere | both together, with light trapped by total internal reflection | the sky, less what the interface limit drops |
+| white furnace, fog volume | the scene's participating-media volumes | the sky |
+| shadow through an index-matched absorbing box | shadow rays crossing a medium boundary | `exp(-σ d)`, against a render without the box |
+| shadow through an absorbing fog volume | shadow rays through volumes | `exp(-σ d)`, against a render without the volume |
+| sun through flat water, 30 / 60 / 75 / 85 degrees | manifold NEE through a flat interface: the solve (from a seed far off, at 85), Fresnel at the vertex, the beam's widening, both legs' water | `t(view) / n² · t(sun) · exp(-a z (1 + 1 / cos θw))`, against the tile dry |
+| sun on an underwater slope facing away from it | the light chosen, and the connection sought, by the refracted direction | the same, times `cos(slope) / cos θw` |
+| sun through flat water past an index-matched box | the connection's probes pass other meshes | as at 30 degrees |
+| lamp over flat water | the same from a point light: its beam narrows to `(h + z / n)²` | `t(0)² / n² · exp(-2 a z) · ((h + z) / (h + z / n))²`, against the tile dry |
+
+The scenes use a flat sky (`make_flat_environment`), an emitter as the backdrop, or a sun overhead, so
+every answer is a formula rather than a reference image.
+
+## What it measured
+
+On an RTX 4090 (Chrome, D3D12) at 256×256 all twenty-one pass, at 0.7–3 ms a frame each. Four things are
+worth knowing when reading the numbers:
+
+- **A tessellated sphere traps light a smooth one would not.** Entering near the outline, light refracts
+  to just under the critical angle; the normals interpolated across flat triangles tip it over at the far
+  side, and then keep its angle from triangle to triangle, so it circles forever. That was the dark arc
+  inside the clear sphere's outline, on the side the tessellation tilts: 4.4% low there, unchanged by a
+  higher event limit. Past its first 4 interface events a path now takes them about the triangle's own
+  normal, and an event a shading normal would turn back across the triangle takes the triangle's,
+  which lets the light out: the outline holds 0.1% on every side, its middle closes exactly.
+- **Every loop has a fixed limit**, because every thread of a group waits for its slowest path and
+  WebGPU has nothing to run beside it. The scattering glass sphere loses 0.5% to the interface limit
+  in its middle and up to 0.7% at its outline (16 events; none at 64), and its checks allow 0.6% on top
+  of the noise.
+- **The index-matched scattering sphere closes to about 1e-4**, so the medium is not what loses light.
+
+- **Through flat water the connection meets the closed form to 0.1%**, once two things outside it
+  were taken out of the check: the tile is smooth (a rough diffuse lobe depends on the light's angle,
+  and the sun arrives at different angles dry and wet), and its index is that of what surrounds it, 1
+  dry and 1.333 wet, so it reflects nothing either way — under water a surface reflects by the ratio.
+
+The default of 256 frames is enough for every tolerance; more buys nothing but a busy GPU. The scenes
+to look at take about 18 ms (glass, water and fog) and 15 ms (caustics) a frame at 512×512.

package/src/shade/playground/path_traced_media/capture_radiance.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The frame's colour just before the tone map, in full precision: with temporal filtering, depth of
+ * field, motion blur, sharpening and bloom off, that is the accumulating path tracer's running mean
+ * of radiance, as it left the tracer.
+ */
+export class CaptureRadiance extends RenderExtension {
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device: GPUDevice);
+    /**
+     * Off by default: a capture copies the whole frame.
+     * @type {boolean}
+     */
+    enabled: boolean;
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame: FrameContext): void;
+    /**
+     * The last captured frame, linear RGB radiance, row by row from the top.
+     *
+     * @returns {Promise<{rgb: Float32Array, width: number, height: number}>}
+     */
+    read(): Promise<{
+        rgb: Float32Array;
+        width: number;
+        height: number;
+    }>;
+    #private;
+}
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+//# sourceMappingURL=capture_radiance.d.ts.map

package/src/shade/playground/path_traced_media/capture_radiance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture_radiance.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/path_traced_media/capture_radiance.js"],"names":[],"mappings":"AAuCA;;;;GAIG;AACH;IAwBI;;OAEG;IACH,+BAIC;IA1BD;;;OAGG;IACH,SAFU,OAAO,CAED;IAwDhB;;OAEG;IACH,kCAeC;IAED;;;;OAIG;IACH,QAFa,QAAQ;QAAC,GAAG,EAAE,YAAY,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAAC,CAwCvE;;CACJ;gCA5K+B,6CAA6C"}

package/src/shade/playground/path_traced_media/capture_radiance.js

@@ -0,0 +1,174 @@
+import { FramePhase } from "../../renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
+import { SceneColor } from "../../renderer/extension/SceneColor.js";
+import { ImageShader } from "../../renderer/shader/ImageShader.js";
+import { CodeChunk } from "../../renderer/shader/compiler/CodeChunk.js";
+import { graph_image_pass } from "../../renderer/shader/graph/graph_image_pass.js";
+import { graph_import_texture } from "../../renderer/shader/graph/graph_import_texture.js";
+import { ShaderResourceSetDescriptor } from "../../renderer/shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../renderer/shader/ShaderDescriptor.js";
+import { GPUTextureContext } from "../../renderer/texture/GPUTextureContext.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup().addTexture("tSource", "unfilterable-float");
+
+const shader_copy_radiance = new ImageShader({
+    descriptor: ShaderDescriptor.from({
+        label: "path_traced_media/copy radiance",
+        resources,
+        body: CodeChunk.from(
+            //language=WGSL
+            `
+@fragment
+fn main(
+    @builtin(position) coord: vec4<f32>,
+) -> @location(0) vec4<f32> {
+    return textureLoad(tSource, vec2<u32>(coord.xy), 0);
+}
+`
+        ),
+    }),
+    targets: [
+        {
+            label: "path_traced_media capture",
+            format: "rgba32float",
+        }
+    ],
+});
+
+/**
+ * The frame's colour just before the tone map, in full precision: with temporal filtering, depth of
+ * field, motion blur, sharpening and bloom off, that is the accumulating path tracer's running mean
+ * of radiance, as it left the tracer.
+ */
+export class CaptureRadiance extends RenderExtension {
+    name = 'path_traced_media/capture radiance';
+
+    phase = FramePhase.BeforePresent;
+
+    /**
+     * Off by default: a capture copies the whole frame.
+     * @type {boolean}
+     */
+    enabled = false;
+
+    /** @type {GPUDevice} */
+    #device;
+
+    /** @type {GPUTextureContext|undefined} */
+    #texture;
+
+    /** @type {GPUBuffer|undefined} */
+    #buffer;
+
+    #width = 0;
+    #height = 0;
+    #bytes_per_row = 0;
+
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        super();
+
+        this.#device = device;
+    }
+
+    #ensure(width, height) {
+        if (this.#width === width && this.#height === height) {
+            return;
+        }
+
+        this.#texture?.destroy();
+        this.#buffer?.destroy();
+
+        const device = this.#device;
+
+        this.#texture = GPUTextureContext.fromTexture(
+            device.createTexture({
+                label: 'path_traced_media/radiance capture',
+                size: [width, height, 1],
+                format: 'rgba32float',
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
+            }),
+            device
+        );
+
+        this.#bytes_per_row = Math.ceil(width * 16 / 256) * 256;
+
+        this.#buffer = device.createBuffer({
+            label: 'path_traced_media/radiance readback',
+            size: this.#bytes_per_row * height,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+        });
+
+        this.#width = width;
+        this.#height = height;
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        if (!this.enabled) {
+            return;
+        }
+
+        const resolution = frame.resolution;
+
+        this.#ensure(resolution[0], resolution[1]);
+
+        graph_image_pass({
+            graph: frame.graph,
+            shader: shader_copy_radiance,
+            inputs: { tSource: frame.get(SceneColor).color },
+            output: [graph_import_texture(frame.graph, this.#texture, 'path_traced_media capture')],
+        });
+    }
+
+    /**
+     * The last captured frame, linear RGB radiance, row by row from the top.
+     *
+     * @returns {Promise<{rgb: Float32Array, width: number, height: number}>}
+     */
+    async read() {
+        if (this.#texture === undefined) {
+            throw new Error('nothing has been captured yet — enable the capture and render a frame');
+        }
+
+        const device = this.#device;
+
+        const encoder = device.createCommandEncoder({ label: 'path_traced_media/radiance readback' });
+
+        encoder.copyTextureToBuffer(
+            { texture: this.#texture.gpu_texture },
+            { buffer: this.#buffer, bytesPerRow: this.#bytes_per_row },
+            [this.#width, this.#height, 1]
+        );
+
+        device.queue.submit([encoder.finish()]);
+
+        await this.#buffer.mapAsync(GPUMapMode.READ);
+
+        const source = new Float32Array(this.#buffer.getMappedRange());
+        const stride = this.#bytes_per_row / 4;
+
+        const rgb = new Float32Array(this.#width * this.#height * 3);
+
+        for (let y = 0; y < this.#height; y++) {
+            for (let x = 0; x < this.#width; x++) {
+                const from = y * stride + x * 4;
+                const to = (y * this.#width + x) * 3;
+
+                rgb[to] = source[from];
+                rgb[to + 1] = source[from + 1];
+                rgb[to + 2] = source[from + 2];
+            }
+        }
+
+        this.#buffer.unmap();
+
+        return { rgb, width: this.#width, height: this.#height };
+    }
+}

package/src/shade/playground/path_traced_media/checks.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @param {object} options
+ * @param {number[]} [options.albedo]
+ * @param {number[]} [options.emissive]
+ * @param {number} [options.roughness]
+ * @param {number} [options.transmission]
+ * @param {number} [options.ior]
+ * @param {ParticipatingMedium|null} [options.medium]
+ * @returns {StandardShadeMaterial}
+ */
+export function surface({ albedo, emissive, roughness, transmission, ior, medium, }: {
+    albedo?: number[];
+    emissive?: number[];
+    roughness?: number;
+    transmission?: number;
+    ior?: number;
+    medium?: ParticipatingMedium | null;
+}): StandardShadeMaterial;
+/**
+ * @param {number[]} absorption
+ * @returns {ParticipatingMedium}
+ */
+export function absorbing_medium(absorption: number[]): ParticipatingMedium;
+/**
+ * A fog volume of uniform density: `extinction` and `scattering` are its coefficients, 1/m.
+ */
+export function place_fog({ scene }: {
+    scene: any;
+}, { position, scale, extinction, scattering, g }: {
+    position: any;
+    scale: any;
+    extinction: any;
+    scattering: any;
+    g: any;
+}): void;
+/**
+ * Mean and standard error per channel over a rectangle of the image, and the mean over the same
+ * pixels of what each should be.
+ *
+ * Given the accumulation read halfway (`half_image`), the standard error is the estimate's own
+ * noise: per pixel, the second half (2 image - half) less the first is noise alone, and the mean of
+ * the whole has a quarter of its variance. Without it, each pixel is taken as one independent
+ * estimate of the rectangle's mean — which counts any structure across the rectangle, a dark arc
+ * where the answer is flat, as noise, and widens the tolerance for exactly the error it should find.
+ *
+ * @param {{rgb: Float32Array, width: number, height: number}} image
+ * @param {number[]} rect
+ * @param {number[]|function(number, number[]): number[]} expected
+ * @param {number} fov_degrees the camera's vertical field of view; the image is square
+ * @param {{rgb: Float32Array}|null} [half_image] the same accumulation after half the frames
+ * @returns {{mean: number[], standard_error: number[], expected: number[], pixels: number, non_finite: number}}
+ */
+export function region_statistics(image: {
+    rgb: Float32Array;
+    width: number;
+    height: number;
+}, rect: number[], expected: number[] | ((arg0: number, arg1: number[]) => number[]), fov_degrees: number, half_image?: {
+    rgb: Float32Array;
+} | null): {
+    mean: number[];
+    standard_error: number[];
+    expected: number[];
+    pixels: number;
+    non_finite: number;
+};
+/**
+ * Whether a measured value agrees with the expected one: within four standard errors, plus a
+ * relative allowance — by default 0.2%, for what the image's formats and the dithered material
+ * inputs add.
+ *
+ * @param {number} measured
+ * @param {number} standard_error
+ * @param {number} expected
+ * @returns {boolean}
+ */
+export function agrees(measured: number, standard_error: number, expected: number, allowance?: number): boolean;
+/**
+ * @type {MediaCheck[]}
+ */
+export const MEDIA_CHECKS: MediaCheck[];
+/**
+ * Scenes with a closed-form answer, for the accumulating path tracer to converge to.
+ *
+ * Each check renders one or two variants of a scene and compares rectangles of the image — mean
+ * radiance per channel — with what the scene must produce: an absolute value, or for a `ratio`
+ * region the test variant over the control, which cancels everything the two share (the BRDF, the
+ * light's units, the view). Rectangles are in normalized image coordinates, `[x0, y0, x1, y1]` from
+ * the top left. Where the answer depends on the angle a pixel's ray makes with the camera's axis —
+ * the path length through a slab facing the camera — `expected` is a function of its cosine, and of
+ * the ray's direction in the camera's frame (x right, y up, looking down -z) where the answer is not
+ * symmetric about the axis, evaluated per pixel and averaged over the rectangle like the measurement
+ * is.
+ */
+export type MediaCheckRegion = {
+    name: string;
+    rect: number[];
+    /**
+     * RGB, or RGB of the cosine
+     * between a pixel's ray and the camera's axis and of that ray's unit direction
+     */
+    expected: number[] | ((arg0: number, arg1: number[]) => number[]);
+    ratio?: boolean;
+    /**
+     * relative error tolerated on top of the standard errors, where a
+     * measured residual is known and stated; 0.2% otherwise
+     */
+    allowance?: number;
+};
+/**
+ * Scenes with a closed-form answer, for the accumulating path tracer to converge to.
+ *
+ * Each check renders one or two variants of a scene and compares rectangles of the image — mean
+ * radiance per channel — with what the scene must produce: an absolute value, or for a `ratio`
+ * region the test variant over the control, which cancels everything the two share (the BRDF, the
+ * light's units, the view). Rectangles are in normalized image coordinates, `[x0, y0, x1, y1]` from
+ * the top left. Where the answer depends on the angle a pixel's ray makes with the camera's axis —
+ * the path length through a slab facing the camera — `expected` is a function of its cosine, and of
+ * the ray's direction in the camera's frame (x right, y up, looking down -z) where the answer is not
+ * symmetric about the axis, evaluated per pixel and averaged over the rectangle like the measurement
+ * is.
+ */
+export type MediaCheck = {
+    name: string;
+    about: string;
+    /**
+     * flat RGB radiance of the sky
+     */
+    environment: number[];
+    camera: {
+        position: number[];
+        target: number[];
+        fov_degrees: number;
+    };
+    test: (arg0: MediaScene) => void;
+    control?: (arg0: MediaScene) => void;
+    regions: MediaCheckRegion[];
+};
+/**
+ * Scenes with a closed-form answer, for the accumulating path tracer to converge to.
+ *
+ * Each check renders one or two variants of a scene and compares rectangles of the image — mean
+ * radiance per channel — with what the scene must produce: an absolute value, or for a `ratio`
+ * region the test variant over the control, which cancels everything the two share (the BRDF, the
+ * light's units, the view). Rectangles are in normalized image coordinates, `[x0, y0, x1, y1]` from
+ * the top left. Where the answer depends on the angle a pixel's ray makes with the camera's axis —
+ * the path length through a slab facing the camera — `expected` is a function of its cosine, and of
+ * the ray's direction in the camera's frame (x right, y up, looking down -z) where the answer is not
+ * symmetric about the axis, evaluated per pixel and averaged over the rectangle like the measurement
+ * is.
+ */
+export type MediaScene = {
+    scene: import("../../renderer/scene/Scene.js").Scene;
+    place: (arg0: MeshletGeometry, arg1: StandardShadeMaterial, arg2: Vector3, arg3: Quaternion | undefined) => void;
+    meshlets: (arg0: BufferedGeometry) => MeshletGeometry;
+};
+import { ParticipatingMedium } from "../../renderer/medium/ParticipatingMedium.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+//# sourceMappingURL=checks.d.ts.map

package/src/shade/playground/path_traced_media/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/path_traced_media/checks.js"],"names":[],"mappings":"AAkFA;;;;;;;;;GASG;AACH;IAR8B,MAAM,GAAzB,MAAM,EAAE;IACW,QAAQ,GAA3B,MAAM,EAAE;IACS,SAAS,GAA1B,MAAM;IACW,YAAY,GAA7B,MAAM;IACW,GAAG,GAApB,MAAM;IAC6B,MAAM,GAAzC,mBAAmB,GAAC,IAAI;IACtB,qBAAqB,CAsBjC;AAED;;;GAGG;AACH,6CAHW,MAAM,EAAE,GACN,mBAAmB,CAQ/B;AA2BD;;GAEG;AACH;;;;;;;;SAYC;AAuoBD;;;;;;;;;;;;;;;;GAgBG;AACH,yCAPW;IAAC,GAAG,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,QAClD,MAAM,EAAE,YACR,MAAM,EAAE,WAAU,MAAM,QAAE,MAAM,EAAE,KAAG,MAAM,EAAE,CAAA,eAC7C,MAAM,eACN;IAAC,GAAG,EAAE,YAAY,CAAA;CAAC,GAAC,IAAI,GACtB;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAC,CA8E9G;AAED;;;;;;;;;GASG;AACH,iCALW,MAAM,kBACN,MAAM,YACN,MAAM,uBACJ,OAAO,CAInB;AA/fD;;GAEG;AACH,2BAFU,UAAU,EAAE,CAiZpB;;;;;;;;;;;;;;;UA1wBY,MAAM;UACN,MAAM,EAAE;;;;;cACR,MAAM,EAAE,WAAU,MAAM,QAAE,MAAM,EAAE,KAAG,MAAM,EAAE,CAAA;YAE7C,OAAO;;;;;gBACP,MAAM;;;;;;;;;;;;;;;;UAIN,MAAM;WACN,MAAM;;;;iBACN,MAAM,EAAE;YACR;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC;iBAClD,UAAU,KAAG,IAAI;qBACjB,UAAU,KAAG,IAAI;aAC1B,gBAAgB,EAAE;;;;;;;;;;;;;;;;WAGlB,OAAO,+BAA+B,EAAE,KAAK;yCACnB,qBAAqB,QAAE,OAAO,QAAE,UAAU,iBAAI,IAAI;;;oCAzCtD,8CAA8C;sCAD5C,kDAAkD;oBARpE,+BAA+B;uBAD5B,kCAAkC"}