@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/renderer/path_tracer/shader/media/chunk_medium_stack.d.ts

@@ -0,0 +1,57 @@
+/**
+ * How many media bounded by refracting surfaces a path can be inside at once: water inside a glass,
+ * inside a tank. Entering a fourth is treated as entering nothing.
+ * @type {number}
+ */
+export const MEDIUM_STACK_LIMIT: number;
+/**
+ * The media bounded by refracting surfaces a path is inside, as the materials of the surfaces it
+ * entered them through, ordered by priority: the one at `depth - 1` is the current medium — of
+ * highest priority, and among equals the one entered last — and `entries.x` the lowest.
+ * A material carries the interface's index of refraction (`ior_factor`) and names the medium.
+ */
+export const MEDIUM_STACK_STRUCT: WebGPUStruct;
+/**
+ * What crossing a medium-bounding surface does to a path.
+ *
+ * - `stack`: the path's stack after the crossing, if the light crosses — kept as it was if the
+ *   surface reflects instead.
+ * - `is_interface`: whether there is a refracting interface here at all. Where there is not, the path
+ *   continues straight through as if the surface were not there.
+ * - `outside` and `inside`: the materials on the two sides, each a material id or
+ *   GPU_DATABASE_NULL for vacuum, oriented the way the surface's outward normal points; the index of
+ *   refraction across the interface is the inside material's `ior_factor` over the outside's.
+ */
+export const MEDIUM_CROSSING_STRUCT: WebGPUStruct;
+/**
+ * Nested and overlapping media bounded by refracting surfaces, by priority (Schmidt & Budge 2002,
+ * "Simple Nested Dielectrics in Ray Traced Images"). At any point exactly one such medium is the
+ * medium: the highest-priority one the point is inside. A path carries the ones it is inside on a
+ * small stack, and at each medium-bounding surface `medium_crossing` decides:
+ *
+ * | the surface                                              | crossing it                       |
+ * |----------------------------------------------------------|-----------------------------------|
+ * | enters the current medium again (same medium)            | no interface: index-matched       |
+ * | enters a medium of lower priority than the current one   | no interface: a false intersection |
+ * | enters with the stack full                               | no interface                      |
+ * | enters any other medium                                  | interface, current -> new         |
+ * | leaves a medium the path is not inside                   | no interface (inconsistent geometry) |
+ * | leaves a medium of lower priority than the current one   | no interface; it leaves the stack |
+ * | leaves the current medium into the same medium           | no interface                      |
+ * | leaves the current medium                                | interface, current -> next one out |
+ *
+ * Entering records the material even where there is no interface, so that leaving it later is
+ * recognized — in priority order (`medium_stack_push`), so the stack's top is always the medium
+ * however the path got there, as `medium_stack_at` finds it for a path starting there. With the
+ * stack full, a medium entered is not recorded, and leaving it later is taken for leaving the
+ * innermost recorded mesh of its material — wrong only three media deep. Reads `materials` (the resident material table, for a material's `medium` slot) and
+ * `media` (the resident media table, for a medium's priority), which the importing shader binds.
+ *
+ * Every access to the stack is by `select`: a dynamically indexed array would sit in local memory.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_medium_stack: CodeChunk;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_medium_stack.d.ts.map

package/src/shade/renderer/path_tracer/shader/media/chunk_medium_stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_medium_stack.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/path_tracer/shader/media/chunk_medium_stack.js"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,iCAFU,MAAM,CAEoB;AAEpC;;;;;GAKG;AACH,+CAGkB;AAElB;;;;;;;;;;GAUG;AACH,kDAKqB;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,iCAFU,SAAS,CA0JjB;6BA1N2B,sCAAsC;0BAFzC,uCAAuC"}

package/src/shade/renderer/path_tracer/shader/media/chunk_medium_stack.js

@@ -0,0 +1,222 @@
+import { GPU_DATABASE_NULL } from "../../../buffer/table/GPU_DATABASE_NULL.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { bool, u32, vec3u } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+
+/**
+ * How many media bounded by refracting surfaces a path can be inside at once: water inside a glass,
+ * inside a tank. Entering a fourth is treated as entering nothing.
+ * @type {number}
+ */
+export const MEDIUM_STACK_LIMIT = 3;
+
+/**
+ * The media bounded by refracting surfaces a path is inside, as the materials of the surfaces it
+ * entered them through, ordered by priority: the one at `depth - 1` is the current medium — of
+ * highest priority, and among equals the one entered last — and `entries.x` the lowest.
+ * A material carries the interface's index of refraction (`ior_factor`) and names the medium.
+ */
+export const MEDIUM_STACK_STRUCT = WebGPUStruct.from({
+    entries: vec3u,
+    depth: u32,
+}, "MediumStack");
+
+/**
+ * What crossing a medium-bounding surface does to a path.
+ *
+ * - `stack`: the path's stack after the crossing, if the light crosses — kept as it was if the
+ *   surface reflects instead.
+ * - `is_interface`: whether there is a refracting interface here at all. Where there is not, the path
+ *   continues straight through as if the surface were not there.
+ * - `outside` and `inside`: the materials on the two sides, each a material id or
+ *   GPU_DATABASE_NULL for vacuum, oriented the way the surface's outward normal points; the index of
+ *   refraction across the interface is the inside material's `ior_factor` over the outside's.
+ */
+export const MEDIUM_CROSSING_STRUCT = WebGPUStruct.from({
+    stack: MEDIUM_STACK_STRUCT,
+    is_interface: bool,
+    outside: u32,
+    inside: u32,
+}, "MediumCrossing");
+
+/**
+ * Nested and overlapping media bounded by refracting surfaces, by priority (Schmidt & Budge 2002,
+ * "Simple Nested Dielectrics in Ray Traced Images"). At any point exactly one such medium is the
+ * medium: the highest-priority one the point is inside. A path carries the ones it is inside on a
+ * small stack, and at each medium-bounding surface `medium_crossing` decides:
+ *
+ * | the surface                                              | crossing it                       |
+ * |----------------------------------------------------------|-----------------------------------|
+ * | enters the current medium again (same medium)            | no interface: index-matched       |
+ * | enters a medium of lower priority than the current one   | no interface: a false intersection |
+ * | enters with the stack full                               | no interface                      |
+ * | enters any other medium                                  | interface, current -> new         |
+ * | leaves a medium the path is not inside                   | no interface (inconsistent geometry) |
+ * | leaves a medium of lower priority than the current one   | no interface; it leaves the stack |
+ * | leaves the current medium into the same medium           | no interface                      |
+ * | leaves the current medium                                | interface, current -> next one out |
+ *
+ * Entering records the material even where there is no interface, so that leaving it later is
+ * recognized — in priority order (`medium_stack_push`), so the stack's top is always the medium
+ * however the path got there, as `medium_stack_at` finds it for a path starting there. With the
+ * stack full, a medium entered is not recorded, and leaving it later is taken for leaving the
+ * innermost recorded mesh of its material — wrong only three media deep. Reads `materials` (the resident material table, for a material's `medium` slot) and
+ * `media` (the resident media table, for a medium's priority), which the importing shader binds.
+ *
+ * Every access to the stack is by `select`: a dynamically indexed array would sit in local memory.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_medium_stack = CodeChunk.from(
+    //language=WGSL
+    `
+const MEDIUM_STACK_LIMIT: u32 = ${MEDIUM_STACK_LIMIT}u;
+const MEDIUM_NONE: u32 = ${GPU_DATABASE_NULL}u;
+
+fn medium_stack_entry(stack: ${MEDIUM_STACK_STRUCT.wgsl_ref}, index: u32) -> u32 {
+    return select(select(stack.entries.x, stack.entries.y, index == 1u), stack.entries.z, index == 2u);
+}
+
+fn medium_stack_top(stack: ${MEDIUM_STACK_STRUCT.wgsl_ref}) -> u32 {
+    if (stack.depth == 0u) {
+        return MEDIUM_NONE;
+    }
+
+    return medium_stack_entry(stack, stack.depth - 1u);
+}
+
+fn medium_stack_contains(stack: ${MEDIUM_STACK_STRUCT.wgsl_ref}, material: u32) -> bool {
+    return (stack.depth > 0u && stack.entries.x == material)
+        || (stack.depth > 1u && stack.entries.y == material)
+        || (stack.depth > 2u && stack.entries.z == material);
+}
+
+// appends the material on top, whatever its priority: a plain list
+fn medium_stack_append(stack: ${MEDIUM_STACK_STRUCT.wgsl_ref}, material: u32) -> ${MEDIUM_STACK_STRUCT.wgsl_ref} {
+    if (stack.depth >= MEDIUM_STACK_LIMIT) {
+        return stack;
+    }
+
+    return medium_stack_insert(stack, material, stack.depth);
+}
+
+// enters the material: above every entry of no higher priority, so that the top is the medium of
+// highest priority and, among equals, the one entered last
+fn medium_stack_push(stack: ${MEDIUM_STACK_STRUCT.wgsl_ref}, material: u32) -> ${MEDIUM_STACK_STRUCT.wgsl_ref} {
+    if (stack.depth >= MEDIUM_STACK_LIMIT) {
+        return stack;
+    }
+
+    let priority = medium_priority_of_material(material);
+
+    var at = stack.depth;
+
+    for (var i = stack.depth; i > 0u; i--) {
+        if (medium_priority_of_material(medium_stack_entry(stack, i - 1u)) > priority) {
+            at = i - 1u;
+        }
+    }
+
+    return medium_stack_insert(stack, material, at);
+}
+
+// the material at index at, the entries from there up moving up one
+fn medium_stack_insert(stack: ${MEDIUM_STACK_STRUCT.wgsl_ref}, material: u32, at: u32) -> ${MEDIUM_STACK_STRUCT.wgsl_ref} {
+
+    let entries = vec3<u32>(
+        select(stack.entries.x, material, at == 0u),
+        select(select(stack.entries.x, material, at == 1u), stack.entries.y, at > 1u),
+        select(select(stack.entries.y, material, at == 2u), stack.entries.z, at > 2u),
+    );
+
+    return ${MEDIUM_STACK_STRUCT.wgsl_ref}(entries, stack.depth + 1u);
+}
+
+// removes the innermost occurrence of the material, the ones inside it moving down one
+fn medium_stack_remove(stack: ${MEDIUM_STACK_STRUCT.wgsl_ref}, material: u32) -> ${MEDIUM_STACK_STRUCT.wgsl_ref} {
+    var at = MEDIUM_STACK_LIMIT;
+
+    if (stack.depth > 2u && stack.entries.z == material) {
+        at = 2u;
+    } else if (stack.depth > 1u && stack.entries.y == material) {
+        at = 1u;
+    } else if (stack.depth > 0u && stack.entries.x == material) {
+        at = 0u;
+    }
+
+    if (at == MEDIUM_STACK_LIMIT) {
+        return stack;
+    }
+
+    let entries = vec3<u32>(
+        select(stack.entries.x, stack.entries.y, at == 0u),
+        select(stack.entries.y, stack.entries.z, at <= 1u),
+        select(stack.entries.z, MEDIUM_NONE, at <= 2u),
+    );
+
+    return ${MEDIUM_STACK_STRUCT.wgsl_ref}(entries, stack.depth - 1u);
+}
+
+fn medium_of_material(material: u32) -> u32 {
+    if (material == MEDIUM_NONE) {
+        return MEDIUM_NONE;
+    }
+
+    return materials[material].medium;
+}
+
+fn medium_priority_of_material(material: u32) -> u32 {
+    let medium = medium_of_material(material);
+
+    if (medium == MEDIUM_NONE) {
+        return 0u;
+    }
+
+    return media.records[medium].priority;
+}
+
+fn medium_crossing(
+    stack: ${MEDIUM_STACK_STRUCT.wgsl_ref},
+    material: u32,
+    entering: bool,
+) -> ${MEDIUM_CROSSING_STRUCT.wgsl_ref} {
+    let medium = medium_of_material(material);
+    let current = medium_stack_top(stack);
+    let current_medium = medium_of_material(current);
+
+    if (entering) {
+        let pushed = medium_stack_push(stack, material);
+
+        if (stack.depth >= MEDIUM_STACK_LIMIT
+            || (current != MEDIUM_NONE && current_medium == medium)
+            || (current != MEDIUM_NONE && medium_priority_of_material(material) < medium_priority_of_material(current))) {
+            return ${MEDIUM_CROSSING_STRUCT.wgsl_ref}(pushed, false, current, material);
+        }
+
+        return ${MEDIUM_CROSSING_STRUCT.wgsl_ref}(pushed, true, current, material);
+    }
+
+    if (!medium_stack_contains(stack, material)) {
+        return ${MEDIUM_CROSSING_STRUCT.wgsl_ref}(stack, false, current, material);
+    }
+
+    let removed = medium_stack_remove(stack, material);
+
+    if (material != current) {
+        return ${MEDIUM_CROSSING_STRUCT.wgsl_ref}(removed, false, current, material);
+    }
+
+    let next = medium_stack_top(removed);
+
+    if (next != MEDIUM_NONE && medium_of_material(next) == medium) {
+        return ${MEDIUM_CROSSING_STRUCT.wgsl_ref}(removed, false, next, material);
+    }
+
+    return ${MEDIUM_CROSSING_STRUCT.wgsl_ref}(removed, true, next, material);
+}
+    `,
+    [
+        MEDIUM_STACK_STRUCT.declaration_chunk,
+        MEDIUM_CROSSING_STRUCT.declaration_chunk,
+    ]
+);

package/src/shade/renderer/path_tracer/shader/media/chunk_medium_transport.d.ts

@@ -0,0 +1,88 @@
+/**
+ * What a free flight ended in. {@link MEDIUM_COLLISION_STRUCT }'s `event`.
+ */
+export type MEDIUM_EVENT = number;
+/**
+ * What a free flight ended in. {@link MEDIUM_COLLISION_STRUCT}'s `event`.
+ * @readonly
+ * @enum {number}
+ */
+export const MEDIUM_EVENT: Readonly<{
+    /** reached the end of the segment: the surface, or nothing */
+    Escaped: 0;
+    /** scattered at `t`: sample the medium's phase function there */
+    Scattered: 1;
+    /** absorbed (or cut short): the path ends */
+    Absorbed: 2;
+}>;
+/**
+ * Tentative collisions one free flight, or one transmittance estimate, may take before it is cut
+ * short — a bound on how long a single path can hold a GPU thread, which every thread in its group
+ * waits on, not a sampling parameter. A homogeneous medium takes one collision a flight (its majorant
+ * is its extinction); null collisions come from volume edges and overlaps, and from the gaps the
+ * rest piece spans (see {@link MEDIUM_PIECE_LIMIT}). A cut free flight ends absorbed and counts
+ * itself in `capped`; a cut transmittance estimate answers zero — dark, so a cut is a bias.
+ *
+ * A shadow ray steps by its piece's largest channel, so where one channel's optical depth runs past
+ * the limit it is cut, and answers zero for the other channels too, light they still carry: through
+ * extinction (0.02, 0.2, 1) over 80 m, red 0.011 against 0.20. It takes channels 20 times apart; the
+ * standard particles are at most 4.8.
+ * @type {number}
+ */
+export const MEDIUM_COLLISION_LIMIT: number;
+/**
+ * Volume pieces one free flight, or one transmittance estimate, walks before it takes the rest of
+ * its ray as one piece (`medium_volumes_rest`): a piece inside each volume and one in each gap, so
+ * 32 separate volumes are walked one by one. The rest sums the majorants of every volume left on the
+ * ray across all of it, gaps included, so its null collisions grow as the square of the volumes left
+ * and soon pass {@link MEDIUM_COLLISION_LIMIT}: past it, rays crossing more volumes still come out
+ * dark. At 8 pieces, 12 fog boxes 10 m apart (extinction 0.1) transmitted 0.17 against 0.30, and 20
+ * nothing. A piece costs one walk over the volumes, as a collision does.
+ * @type {number}
+ */
+export const MEDIUM_PIECE_LIMIT: number;
+/**
+ * A path's state as it crosses media, spectrally.
+ *
+ * Distances are sampled with one channel's coefficients, the hero, picked per path; the other
+ * channels follow along weighted, and every contribution the path makes is divided by the mean of
+ * `r_u` — one-sample MIS over the three channels as the technique that could have sampled the path
+ * (Miller, Georgiev & Jarosz 2019, as PBRT-v4's VolPathIntegrator implements it, over RGB). In a
+ * homogeneous medium the majorant is the extinction, so there are no null collisions.
+ *
+ * - `beta`: the path throughput per channel.
+ * - `r_u`: per channel, the probability of the path had that channel been the hero, over the
+ *   probability it was sampled with; 1 for the hero.
+ * - `hero`: 0, 1 or 2.
+ * - `capped`: free flights this path cut at {@link MEDIUM_COLLISION_LIMIT}.
+ */
+export const MEDIUM_PATH_STATE_STRUCT: WebGPUStruct;
+/**
+ * Where a free flight ended, as a distance along the ray, and how ({@link MEDIUM_EVENT}).
+ */
+export const MEDIUM_COLLISION_STRUCT: WebGPUStruct;
+/**
+ * Light transport through participating media for the path tracer: one medium bounded by surfaces
+ * (`host`, a {@link MEDIUM_STRUCT}, homogeneous; the zero record is vacuum) plus the scene's
+ * participating-media volumes, read from the scene database the importing shader binds as
+ * `scene_database`.
+ *
+ * - `medium_free_flight(origin, direction, t_max, host, state)` samples where along the segment the
+ *   path's next real collision is, by delta tracking against per-channel majorants (the host's
+ *   extinction plus the volumes the ray is inside, piece by piece), and updates the path's
+ *   throughput and MIS state for what it found: a scattering at `t`, an absorption, or the end of the
+ *   segment.
+ * - `medium_transmittance(origin, direction, t_max, host)` estimates the segment's transmittance per
+ *   channel for a shadow ray — residual ratio tracking (Novak et al. 2014): the host's part is
+ *   `exp(-sigma_t t_max)` exactly, the volumes' is ratio-tracked against one majorant for all
+ *   channels, so each step's factor stays within [0, 1]. Through the host alone it takes no step and
+ *   is exact. Delta lights are reachable only by such shadow rays, so no MIS weight is needed.
+ *
+ * Both draw from `random()`. `t_max` may be F32_MAX for a segment that hits nothing.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_medium_transport: CodeChunk;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_medium_transport.d.ts.map

package/src/shade/renderer/path_tracer/shader/media/chunk_medium_transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_medium_transport.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/path_tracer/shader/media/chunk_medium_transport.js"],"names":[],"mappings":";;;2BAWU,MAAM;AAHhB;;;;GAIG;AACH;IACI,8DAA8D;;IAE9D,iEAAiE;;IAEjE,6CAA6C;;GAE9C;AAEH;;;;;;;;;;;;;GAaG;AACH,qCAFU,MAAM,CAEyB;AAEzC;;;;;;;;;GASG;AACH,iCAFU,MAAM,CAEqB;AAErC;;;;;;;;;;;;;;GAcG;AACH,oDAKsB;AAEtB;;GAEG;AACH,mDAGsB;AAEtB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qCAFU,SAAS,CA4MjB;6BA3S2B,sCAAsC;0BACzC,uCAAuC"}

package/src/shade/renderer/path_tracer/shader/media/chunk_medium_transport.js

@@ -0,0 +1,304 @@
+import { MEDIUM_STRUCT } from "../../../medium/MEDIUM_STRUCT.js";
+import { F32_MAX_DEFINITION } from "../../../shader/chunk/math/F32_MAX_DEFINITION.js";
+import { chunk_random } from "../../../shader/chunk/random/chunk_random.js";
+import { f32, u32, vec3f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { chunk_medium_volumes, MEDIUM_PIECE_STRUCT } from "./chunk_medium_volumes.js";
+
+/**
+ * What a free flight ended in. {@link MEDIUM_COLLISION_STRUCT}'s `event`.
+ * @readonly
+ * @enum {number}
+ */
+export const MEDIUM_EVENT = Object.freeze({
+    /** reached the end of the segment: the surface, or nothing */
+    Escaped: 0,
+    /** scattered at `t`: sample the medium's phase function there */
+    Scattered: 1,
+    /** absorbed (or cut short): the path ends */
+    Absorbed: 2,
+});
+
+/**
+ * Tentative collisions one free flight, or one transmittance estimate, may take before it is cut
+ * short — a bound on how long a single path can hold a GPU thread, which every thread in its group
+ * waits on, not a sampling parameter. A homogeneous medium takes one collision a flight (its majorant
+ * is its extinction); null collisions come from volume edges and overlaps, and from the gaps the
+ * rest piece spans (see {@link MEDIUM_PIECE_LIMIT}). A cut free flight ends absorbed and counts
+ * itself in `capped`; a cut transmittance estimate answers zero — dark, so a cut is a bias.
+ *
+ * A shadow ray steps by its piece's largest channel, so where one channel's optical depth runs past
+ * the limit it is cut, and answers zero for the other channels too, light they still carry: through
+ * extinction (0.02, 0.2, 1) over 80 m, red 0.011 against 0.20. It takes channels 20 times apart; the
+ * standard particles are at most 4.8.
+ * @type {number}
+ */
+export const MEDIUM_COLLISION_LIMIT = 64;
+
+/**
+ * Volume pieces one free flight, or one transmittance estimate, walks before it takes the rest of
+ * its ray as one piece (`medium_volumes_rest`): a piece inside each volume and one in each gap, so
+ * 32 separate volumes are walked one by one. The rest sums the majorants of every volume left on the
+ * ray across all of it, gaps included, so its null collisions grow as the square of the volumes left
+ * and soon pass {@link MEDIUM_COLLISION_LIMIT}: past it, rays crossing more volumes still come out
+ * dark. At 8 pieces, 12 fog boxes 10 m apart (extinction 0.1) transmitted 0.17 against 0.30, and 20
+ * nothing. A piece costs one walk over the volumes, as a collision does.
+ * @type {number}
+ */
+export const MEDIUM_PIECE_LIMIT = 64;
+
+/**
+ * A path's state as it crosses media, spectrally.
+ *
+ * Distances are sampled with one channel's coefficients, the hero, picked per path; the other
+ * channels follow along weighted, and every contribution the path makes is divided by the mean of
+ * `r_u` — one-sample MIS over the three channels as the technique that could have sampled the path
+ * (Miller, Georgiev & Jarosz 2019, as PBRT-v4's VolPathIntegrator implements it, over RGB). In a
+ * homogeneous medium the majorant is the extinction, so there are no null collisions.
+ *
+ * - `beta`: the path throughput per channel.
+ * - `r_u`: per channel, the probability of the path had that channel been the hero, over the
+ *   probability it was sampled with; 1 for the hero.
+ * - `hero`: 0, 1 or 2.
+ * - `capped`: free flights this path cut at {@link MEDIUM_COLLISION_LIMIT}.
+ */
+export const MEDIUM_PATH_STATE_STRUCT = WebGPUStruct.from({
+    beta: vec3f,
+    hero: u32,
+    r_u: vec3f,
+    capped: u32,
+}, "MediumPathState");
+
+/**
+ * Where a free flight ended, as a distance along the ray, and how ({@link MEDIUM_EVENT}).
+ */
+export const MEDIUM_COLLISION_STRUCT = WebGPUStruct.from({
+    t: f32,
+    event: u32,
+}, "MediumCollision");
+
+/**
+ * Light transport through participating media for the path tracer: one medium bounded by surfaces
+ * (`host`, a {@link MEDIUM_STRUCT}, homogeneous; the zero record is vacuum) plus the scene's
+ * participating-media volumes, read from the scene database the importing shader binds as
+ * `scene_database`.
+ *
+ * - `medium_free_flight(origin, direction, t_max, host, state)` samples where along the segment the
+ *   path's next real collision is, by delta tracking against per-channel majorants (the host's
+ *   extinction plus the volumes the ray is inside, piece by piece), and updates the path's
+ *   throughput and MIS state for what it found: a scattering at `t`, an absorption, or the end of the
+ *   segment.
+ * - `medium_transmittance(origin, direction, t_max, host)` estimates the segment's transmittance per
+ *   channel for a shadow ray — residual ratio tracking (Novak et al. 2014): the host's part is
+ *   `exp(-sigma_t t_max)` exactly, the volumes' is ratio-tracked against one majorant for all
+ *   channels, so each step's factor stays within [0, 1]. Through the host alone it takes no step and
+ *   is exact. Delta lights are reachable only by such shadow rays, so no MIS weight is needed.
+ *
+ * Both draw from `random()`. `t_max` may be F32_MAX for a segment that hits nothing.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_medium_transport = CodeChunk.from(
+    //language=WGSL
+    `
+const MEDIUM_EVENT_ESCAPED: u32 = ${MEDIUM_EVENT.Escaped}u;
+const MEDIUM_EVENT_SCATTERED: u32 = ${MEDIUM_EVENT.Scattered}u;
+const MEDIUM_EVENT_ABSORBED: u32 = ${MEDIUM_EVENT.Absorbed}u;
+const MEDIUM_COLLISION_LIMIT: u32 = ${MEDIUM_COLLISION_LIMIT}u;
+const MEDIUM_PIECE_LIMIT: u32 = ${MEDIUM_PIECE_LIMIT}u;
+
+fn medium_volumes_walk(origin: vec3<f32>, direction: vec3<f32>, t: f32, t_max: f32, pieces: u32) -> ${MEDIUM_PIECE_STRUCT.wgsl_ref} {
+    if (pieces > MEDIUM_PIECE_LIMIT) {
+        return medium_volumes_rest(origin, direction, t, t_max);
+    }
+
+    return medium_volumes_piece(origin, direction, t, t_max);
+}
+
+fn medium_host_scattering(host: ${MEDIUM_STRUCT.wgsl_ref}) -> vec3<f32> {
+    var medium = host;
+    var scattering = vec3<f32>(0.0);
+
+    for (var l = 0u; l < medium.lobe_count; l++) {
+        scattering += medium.lobes[l].scattering;
+    }
+
+    return scattering;
+}
+
+// exp(-sigma * distance) per channel, 1 where sigma is 0 whatever the distance (0 * inf is NaN)
+fn medium_beer_lambert(sigma: vec3<f32>, distance: f32) -> vec3<f32> {
+    return select(exp(-sigma * distance), vec3<f32>(1.0), sigma <= vec3<f32>(0.0));
+}
+
+fn medium_free_flight(
+    origin: vec3<f32>,
+    direction: vec3<f32>,
+    t_max: f32,
+    host: ${MEDIUM_STRUCT.wgsl_ref},
+    state: ptr<function, ${MEDIUM_PATH_STATE_STRUCT.wgsl_ref}>,
+) -> ${MEDIUM_COLLISION_STRUCT.wgsl_ref} {
+    let hero = (*state).hero;
+
+    let host_scattering = medium_host_scattering(host);
+    let host_extinction = host.absorption + host_scattering;
+
+    var t = 0.0;
+    // majorant transmittance since the last tentative collision, per channel
+    var majorant_transmittance = vec3<f32>(1.0);
+    var collisions = 0u;
+    var pieces = 0u;
+
+    while (t < t_max) {
+        pieces++;
+
+        let piece = medium_volumes_walk(origin, direction, t, t_max, pieces);
+
+        let majorant = host_extinction + piece.majorant;
+        let majorant_hero = majorant[hero];
+
+        loop {
+            var step = F32_MAX;
+
+            if (majorant_hero > 0.0) {
+                // 1 - random() is in (0, 1], so the logarithm is finite
+                step = -log(1.0 - random()) / majorant_hero;
+            }
+
+            if (step >= piece.next - t) {
+                majorant_transmittance *= medium_beer_lambert(majorant, piece.next - t);
+                t = piece.next;
+                break;
+            }
+
+            t += step;
+            majorant_transmittance *= medium_beer_lambert(majorant, step);
+
+            collisions++;
+
+            if (collisions > MEDIUM_COLLISION_LIMIT) {
+                (*state).beta = vec3<f32>(0.0);
+                (*state).capped += 1u;
+
+                return ${MEDIUM_COLLISION_STRUCT.wgsl_ref}(t, MEDIUM_EVENT_ABSORBED);
+            }
+
+            let volumes = medium_volumes_coefficients_at(origin + direction * t);
+
+            let absorption = host.absorption + volumes.absorption;
+            let scattering = host_scattering + volumes.scattering;
+
+            let p_absorb = absorption[hero] / majorant_hero;
+            let p_scatter = scattering[hero] / majorant_hero;
+
+            let u = random();
+
+            if (u < p_absorb) {
+                (*state).beta = vec3<f32>(0.0);
+
+                return ${MEDIUM_COLLISION_STRUCT.wgsl_ref}(t, MEDIUM_EVENT_ABSORBED);
+            }
+
+            if (u < p_absorb + p_scatter) {
+                let pdf = majorant_transmittance[hero] * scattering[hero];
+                let factor = majorant_transmittance * scattering / pdf;
+
+                (*state).beta *= factor;
+                (*state).r_u *= factor;
+
+                return ${MEDIUM_COLLISION_STRUCT.wgsl_ref}(t, MEDIUM_EVENT_SCATTERED);
+            }
+
+            // a null collision: the medium here is thinner than the majorant
+            let null_coefficient = max(majorant - absorption - scattering, vec3<f32>(0.0));
+            let pdf = majorant_transmittance[hero] * null_coefficient[hero];
+
+            if (pdf <= 0.0) {
+                (*state).beta = vec3<f32>(0.0);
+
+                return ${MEDIUM_COLLISION_STRUCT.wgsl_ref}(t, MEDIUM_EVENT_ABSORBED);
+            }
+
+            let factor = majorant_transmittance * null_coefficient / pdf;
+
+            (*state).beta *= factor;
+            (*state).r_u *= factor;
+
+            majorant_transmittance = vec3<f32>(1.0);
+        }
+    }
+
+    // the segment ends before any real collision; for the hero that had probability
+    // majorant_transmittance[hero], which the other channels are weighted against
+    let normalizer = majorant_transmittance[hero];
+
+    if (normalizer <= 0.0) {
+        (*state).beta = vec3<f32>(0.0);
+    } else {
+        (*state).beta *= majorant_transmittance / normalizer;
+        (*state).r_u *= majorant_transmittance / normalizer;
+    }
+
+    return ${MEDIUM_COLLISION_STRUCT.wgsl_ref}(t_max, MEDIUM_EVENT_ESCAPED);
+}
+
+fn medium_transmittance(
+    origin: vec3<f32>,
+    direction: vec3<f32>,
+    t_max: f32,
+    host: ${MEDIUM_STRUCT.wgsl_ref},
+) -> vec3<f32> {
+    // the host is homogeneous: its part is exact
+    var transmittance = medium_beer_lambert(host.absorption + medium_host_scattering(host), t_max);
+
+    var t = 0.0;
+    var collisions = 0u;
+    var pieces = 0u;
+
+    while (t < t_max && any(transmittance > vec3<f32>(0.0))) {
+        pieces++;
+
+        let piece = medium_volumes_walk(origin, direction, t, t_max, pieces);
+
+        // one majorant for every channel, so 1 - sigma / majorant stays in [0, 1] for each
+        let majorant = max(piece.majorant.x, max(piece.majorant.y, piece.majorant.z));
+
+        loop {
+            var step = F32_MAX;
+
+            if (majorant > 0.0) {
+                step = -log(1.0 - random()) / majorant;
+            }
+
+            if (step >= piece.next - t) {
+                t = piece.next;
+                break;
+            }
+
+            t += step;
+
+            collisions++;
+
+            if (collisions > MEDIUM_COLLISION_LIMIT) {
+                return vec3<f32>(0.0);
+            }
+
+            let volumes = medium_volumes_coefficients_at(origin + direction * t);
+
+            transmittance *= vec3<f32>(1.0) - (volumes.absorption + volumes.scattering) / majorant;
+        }
+    }
+
+    return transmittance;
+}
+    `,
+    [
+        MEDIUM_STRUCT.declaration_chunk,
+        MEDIUM_PATH_STATE_STRUCT.declaration_chunk,
+        MEDIUM_COLLISION_STRUCT.declaration_chunk,
+        F32_MAX_DEFINITION,
+        chunk_random,
+        chunk_medium_volumes,
+    ]
+);