@woosh/meep-engine 3.59.0 → 3.60.0

package/src/shade/renderer/material/resident/GPUResidentMaterialContext.js

@@ -21,6 +21,7 @@ import { INDIRECT_MATERIAL_ARRAY_TYPE } from "./INDIRECT_MATERIAL_ARRAY_TYPE.js"
 import { INDIRECT_MATERIAL_STRUCT } from "./INDIRECT_MATERIAL_STRUCT.js";
 import {
     RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE,
+    RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT,
     RESIDENT_MATERIAL_TEXTURE_RESOLUTION,
     RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION
 } from "./RESIDENT_MATERIAL_TEXTURE_LAYOUT.js";
@@ -381,7 +382,8 @@ export class GPUResidentMaterialContext {
         descriptor.format = "rgba8unorm";
         descriptor.dimension = "2d";
         descriptor.size = [RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE, RESIDENT_MATERIAL_TEXTURE_LAYER_SIZE, 1];
-        descriptor.mipLevelCount = 1;
+        // a slot's chain down to one texel; see RESIDENT_MATERIAL_TEXTURE_LAYOUT
+        descriptor.mipLevelCount = RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT;
         descriptor.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_DST;
 
     }
@@ -548,8 +550,6 @@ export class GPUResidentMaterialContext {
             Math.ceil(texture_count / slice_slot_count)
         );
 
-        const target_texture = this.buffer_textures;
-
         const texture_manager = this.#texture_manager;
 
         {
@@ -582,80 +582,13 @@ export class GPUResidentMaterialContext {
 
             const source_ctx = texture_manager.obtain(source);
 
-            const is_square = source_ctx.width === source_ctx.height;
-
-            /*
-             The fast path is a copyTextureToTexture, which requires the two formats to be
-             copy-compatible. `!is_srgb` used to stand in for that and was true only by accident: every
-             material texture was rgba8unorm, so the only way to differ was the srgb suffix. A BC7
-             source would have reached the copy and failed validation.
-
-             Asking the question directly costs nothing and covers every format at once — a source
-             that does not match takes the render path below, which samples it into the atlas and is
-             what that path exists for.
-            */
-            const format_matches = source_ctx.gpu_texture.format === target_texture.gpu_texture.format;
-
-            const is_pot_w = isPowerOfTwo(source_ctx.width) && isPowerOfTwo(source_ctx.height);
-
-            const source_mip_w = Math.log2(source_ctx.width / RESIDENT_MATERIAL_TEXTURE_RESOLUTION)
-            const source_mip_h = Math.log2(source_ctx.height / RESIDENT_MATERIAL_TEXTURE_RESOLUTION)
-
-
             const texture_slot_z = Math.floor(info.id / slice_slot_count);
             const id_in_slice = info.id % slice_slot_count;
             const texture_slot_y = Math.floor(id_in_slice / RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION);
             const texture_slot_x = id_in_slice % RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION;
 
-            if (is_square && is_pot_w && source_mip_w >= 0 && source_ctx.gpu_texture.mipLevelCount >= source_mip_w && format_matches) {
-
-                encoder.copyTextureToTexture(
-                    {
-                        texture: source_ctx.gpu_texture,
-                        mipLevel: source_mip_w,
-                    },
-                    {
-                        texture: target_texture.gpu_texture,
-                        mipLevel: 0,
-                        origin: [
-                            texture_slot_x * RESIDENT_MATERIAL_TEXTURE_RESOLUTION,
-                            texture_slot_y * RESIDENT_MATERIAL_TEXTURE_RESOLUTION,
-                            texture_slot_z
-                        ]
-                    },
-                    [RESIDENT_MATERIAL_TEXTURE_RESOLUTION, RESIDENT_MATERIAL_TEXTURE_RESOLUTION]
-                );
-
-            } else {
-                const nearest_mip = Math.max(0, Math.floor(Math.min(source_mip_w, source_mip_h)));
-
-                // needs resizing and potentially color-space conversion
-                render_copy_texture(
-                    {
-                        graphics: this.#graphics,
-                        encoder: encoder,
-                        target_format: target_texture.gpu_texture.format,
-                        output_view: target_texture.obtainView(TextureViewDescriptor.from({
-                            baseArrayLayer: texture_slot_z,
-                            dimension: "2d"
-                        })),
-                        source_view: source_ctx.obtainView(TextureViewDescriptor.from({
-                            baseMipLevel: nearest_mip
-                        })),
-                        source_clip: [
-                            0, 0,
-                            source_ctx.width >> nearest_mip, source_ctx.height >> nearest_mip
-                        ],
-                        output_clip: [
-                            texture_slot_x * RESIDENT_MATERIAL_TEXTURE_RESOLUTION,
-                            texture_slot_y * RESIDENT_MATERIAL_TEXTURE_RESOLUTION,
-
-                            RESIDENT_MATERIAL_TEXTURE_RESOLUTION,
-                            RESIDENT_MATERIAL_TEXTURE_RESOLUTION,
-                        ]
-                    },
-                );
-
+            for (let level = 0; level < RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT; level++) {
+                this.#write_slot_level(encoder, source_ctx, texture_slot_x, texture_slot_y, texture_slot_z, level);
             }
         }
 
@@ -665,6 +598,91 @@ export class GPUResidentMaterialContext {
 
     }
 
+    /**
+     * Mip `level` of a texture's slot, from the texture's own chain: copied from the source level the
+     * slot's level is the size of, or drawn from the source level nearest above its size where no level
+     * can be copied as it is. The source's chain does the filtering either way.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {GPUTextureContext} source_ctx
+     * @param {number} slot_x
+     * @param {number} slot_y
+     * @param {number} slot_z
+     * @param {number} level
+     */
+    #write_slot_level(encoder, source_ctx, slot_x, slot_y, slot_z, level) {
+        const target_texture = this.#buffer_textures;
+        const source_texture = source_ctx.gpu_texture;
+
+        const size = RESIDENT_MATERIAL_TEXTURE_RESOLUTION >> level;
+
+        const is_square = source_ctx.width === source_ctx.height;
+
+        /*
+         The fast path is a copyTextureToTexture, which requires the two formats to be
+         copy-compatible. `!is_srgb` used to stand in for that and was true only by accident: every
+         material texture was rgba8unorm, so the only way to differ was the srgb suffix. A BC7
+         source would have reached the copy and failed validation.
+
+         Asking the question directly costs nothing and covers every format at once — a source
+         that does not match takes the render path below, which samples it into the atlas and is
+         what that path exists for.
+        */
+        const format_matches = source_texture.format === target_texture.gpu_texture.format;
+
+        const is_pot_w = isPowerOfTwo(source_ctx.width) && isPowerOfTwo(source_ctx.height);
+
+        const source_mip_w = Math.log2(source_ctx.width / size);
+        const source_mip_h = Math.log2(source_ctx.height / size);
+
+        if (is_square && is_pot_w && source_mip_w >= 0 && source_mip_w < source_texture.mipLevelCount && format_matches) {
+
+            encoder.copyTextureToTexture(
+                {
+                    texture: source_texture,
+                    mipLevel: source_mip_w,
+                },
+                {
+                    texture: target_texture.gpu_texture,
+                    mipLevel: level,
+                    origin: [slot_x * size, slot_y * size, slot_z]
+                },
+                [size, size]
+            );
+
+        } else {
+            // a chain that stops short draws from its last level
+            const nearest_mip = Math.min(
+                Math.max(0, Math.floor(Math.min(source_mip_w, source_mip_h))),
+                source_texture.mipLevelCount - 1
+            );
+
+            // needs resizing and potentially color-space conversion
+            render_copy_texture(
+                {
+                    graphics: this.#graphics,
+                    encoder: encoder,
+                    target_format: target_texture.gpu_texture.format,
+                    output_view: target_texture.obtainView(TextureViewDescriptor.from({
+                        baseArrayLayer: slot_z,
+                        dimension: "2d",
+                        baseMipLevel: level,
+                        mipLevelCount: 1,
+                    })),
+                    source_view: source_ctx.obtainView(TextureViewDescriptor.from({
+                        baseMipLevel: nearest_mip
+                    })),
+                    source_clip: [
+                        0, 0,
+                        source_ctx.width >> nearest_mip, source_ctx.height >> nearest_mip
+                    ],
+                    output_clip: [slot_x * size, slot_y * size, size, size]
+                },
+            );
+
+        }
+    }
+
     /**
      * Every texture slot's mean, after the slots are written (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6):
      * the rows' sums, then the slots' means, which {@link buffer_texture_means} holds.

package/src/shade/renderer/material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.d.ts

@@ -3,6 +3,11 @@
  * @type {number}
  */
 export const RESIDENT_MATERIAL_TEXTURE_RESOLUTION: number;
+/**
+ * Mip levels a slot has, the last one texel.
+ * @type {number}
+ */
+export const RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT: number;
 /**
  * Texels a side of a layer.
  * @type {number}

package/src/shade/renderer/material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RESIDENT_MATERIAL_TEXTURE_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.js"],"names":[],"mappings":"AAOA;;;GAGG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;GAGG;AACH,mDAFU,MAAM,CAEyC;AAEzD;;;GAGG;AACH,wDAFU,MAAM,CAEiI;AAEjJ;;;GAGG;AACH,wDAFU,MAAM,CAE+H"}
+{"version":3,"file":"RESIDENT_MATERIAL_TEXTURE_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.js"],"names":[],"mappings":"AAUA;;;GAGG;AACH,mDAFU,MAAM,CAEuC;AAEvD;;;GAGG;AACH,oDAFU,MAAM,CAEyF;AAEzG;;;GAGG;AACH,mDAFU,MAAM,CAEyC;AAEzD;;;GAGG;AACH,wDAFU,MAAM,CAEiI;AAEjJ;;;GAGG;AACH,wDAFU,MAAM,CAE+H"}

package/src/shade/renderer/material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.js

@@ -3,6 +3,9 @@
  each texture a square slot, the slots in rows across a layer, the layers stacked. Slot `s` is in layer
  `⌊s / SLOTS_PER_LAYER⌋`, at column `s mod SLOT_RESOLUTION` and row `⌊s / SLOT_RESOLUTION⌋ mod
  SLOT_RESOLUTION` of it.
+
+ The array has LEVEL_COUNT mip levels, a slot's chain down to one texel: level k of a slot is
+ (RESOLUTION >> k)² texels at the slot's level-0 origin >> k, in level k of the same layer.
 */
 
 /**
@@ -11,6 +14,12 @@
  */
 export const RESIDENT_MATERIAL_TEXTURE_RESOLUTION = 64;
 
+/**
+ * Mip levels a slot has, the last one texel.
+ * @type {number}
+ */
+export const RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT = Math.log2(RESIDENT_MATERIAL_TEXTURE_RESOLUTION) + 1;
+
 /**
  * Texels a side of a layer.
  * @type {number}

package/src/shade/renderer/path_tracer/shader/INDIRECT_TEXTURE_FILTER.d.ts

@@ -0,0 +1,13 @@
+/**
+ * How a shader reads the resident material textures — decided by {@link chunk_indirect_sample_texture},
+ * so the material reads written once (`sample_material_data`, `sample_material_alpha`) take one filter
+ * or the other by the pipeline they are linked into.
+ *
+ * Whether the pass averages its reads is the pass's, so it is fixed per shader: `Stochastic`, the
+ * default, for every pass that never sets it; `Exact` for the card capture, which stores each read.
+ *
+ * @type {ShaderSwitch}
+ */
+export const INDIRECT_TEXTURE_FILTER: ShaderSwitch;
+import { ShaderSwitch } from "../../shader/compiler/ShaderSwitch.js";
+//# sourceMappingURL=INDIRECT_TEXTURE_FILTER.d.ts.map

package/src/shade/renderer/path_tracer/shader/INDIRECT_TEXTURE_FILTER.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"INDIRECT_TEXTURE_FILTER.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/INDIRECT_TEXTURE_FILTER.js"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,sCAFU,YAAY,CAEqF;6BAb9E,uCAAuC"}

package/src/shade/renderer/path_tracer/shader/INDIRECT_TEXTURE_FILTER.js

@@ -0,0 +1,14 @@
+import { ShaderSwitch } from "../../shader/compiler/ShaderSwitch.js";
+import { IndirectTextureFilter } from "./IndirectTextureFilter.js";
+
+/**
+ * How a shader reads the resident material textures — decided by {@link chunk_indirect_sample_texture},
+ * so the material reads written once (`sample_material_data`, `sample_material_alpha`) take one filter
+ * or the other by the pipeline they are linked into.
+ *
+ * Whether the pass averages its reads is the pass's, so it is fixed per shader: `Stochastic`, the
+ * default, for every pass that never sets it; `Exact` for the card capture, which stores each read.
+ *
+ * @type {ShaderSwitch}
+ */
+export const INDIRECT_TEXTURE_FILTER = ShaderSwitch.enum('indirect texture filter', IndirectTextureFilter);

package/src/shade/renderer/path_tracer/shader/IndirectTextureFilter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * How a read of the resident material textures (`indirect_sample_texture`) takes the texture filtered
+ * at a level: trilinearly, bilinear at the two levels around it and those lerped.
+ */
+export type IndirectTextureFilter = number;
+export namespace IndirectTextureFilter {
+    let Stochastic: number;
+    let Exact: number;
+}
+//# sourceMappingURL=IndirectTextureFilter.d.ts.map

package/src/shade/renderer/path_tracer/shader/IndirectTextureFilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndirectTextureFilter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/IndirectTextureFilter.js"],"names":[],"mappings":";;;;oCAIU,MAAM"}

package/src/shade/renderer/path_tracer/shader/IndirectTextureFilter.js

@@ -0,0 +1,15 @@
+/**
+ * How a read of the resident material textures (`indirect_sample_texture`) takes the texture filtered
+ * at a level: trilinearly, bilinear at the two levels around it and those lerped.
+ *
+ * @enum {number}
+ */
+export const IndirectTextureFilter = {
+    /**
+     * One tap of the filter, a texel of the two levels' eight drawn with its weight: what the filter
+     * gives on average, for a pass that averages many reads into each result — the path tracer.
+     */
+    Stochastic: 0,
+    /** The filter itself, every tap weighed: for a pass that keeps each read as it is — the card capture. */
+    Exact: 1,
+};

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_tangent_normal.d.ts

@@ -1,7 +1,8 @@
 /**
- * A resident material's tangent-space normal at `uv`, from its normal texture in the atlas — or +Z,
- * the geometric normal exactly, when it has none (`id` is GPU_DATABASE_NULL; see
- * INDIRECT_MATERIAL_STRUCT's `texture_normal` for why there is no default texture to read instead).
+ * A resident material's tangent-space normal at `uv`, from its normal texture in the atlas at `level`
+ * (see {@link chunk_indirect_sample_texture}) — or +Z, the geometric normal exactly, when it has none
+ * (`id` is GPU_DATABASE_NULL; see INDIRECT_MATERIAL_STRUCT's `texture_normal` for why there is no
+ * default texture to read instead).
  *
  * Reads the `textures` atlas binding, which {@link chunk_indirect_sample_texture} leaves to the
  * shader that includes it.

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_tangent_normal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_indirect_sample_tangent_normal.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_indirect_sample_tangent_normal.js"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,mDAFU,SAAS,CAeZ;0BA1BmB,oCAAoC"}
+{"version":3,"file":"chunk_indirect_sample_tangent_normal.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_indirect_sample_tangent_normal.js"],"names":[],"mappings":"AAKA;;;;;;;;;;GAUG;AACH,mDAFU,SAAS,CAeZ;0BA3BmB,oCAAoC"}

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_tangent_normal.js

@@ -4,9 +4,10 @@ import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { chunk_indirect_sample_texture } from "./chunk_indirect_sample_texture.js";
 
 /**
- * A resident material's tangent-space normal at `uv`, from its normal texture in the atlas — or +Z,
- * the geometric normal exactly, when it has none (`id` is GPU_DATABASE_NULL; see
- * INDIRECT_MATERIAL_STRUCT's `texture_normal` for why there is no default texture to read instead).
+ * A resident material's tangent-space normal at `uv`, from its normal texture in the atlas at `level`
+ * (see {@link chunk_indirect_sample_texture}) — or +Z, the geometric normal exactly, when it has none
+ * (`id` is GPU_DATABASE_NULL; see INDIRECT_MATERIAL_STRUCT's `texture_normal` for why there is no
+ * default texture to read instead).
  *
  * Reads the `textures` atlas binding, which {@link chunk_indirect_sample_texture} leaves to the
  * shader that includes it.
@@ -16,12 +17,12 @@ import { chunk_indirect_sample_texture } from "./chunk_indirect_sample_texture.j
 export const chunk_indirect_sample_tangent_normal = CodeChunk.from(
     //language=WGSL
     `
-fn indirect_sample_tangent_normal(id: u32, sampler_packed: u32, uv: vec2<f32>) -> vec3<f32> {
+fn indirect_sample_tangent_normal(id: u32, sampler_packed: u32, uv: vec2<f32>, level: f32) -> vec3<f32> {
     if (id == ${GPU_DATABASE_NULL}u) {
         return vec3<f32>(0.0, 0.0, 1.0);
     }
 
-    return decode_tangent_normal(indirect_sample_texture(id, sampler_packed, uv));
+    return decode_tangent_normal(indirect_sample_texture(id, sampler_packed, uv, level));
 }
 `, [
         chunk_decode_tangent_normal,

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture.d.ts

@@ -1,3 +1,18 @@
-export const chunk_indirect_sample_texture: CodeChunk;
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+/**
+ * A resident material texture filtered at a level:
+ * `indirect_sample_texture(id: u32, sampler_packed: u32, uv: vec2<f32>, level: f32) -> vec4<f32>`, texture
+ * `id` of the atlas with its packed sampler's wrap and filter, trilinearly at `level`: log2 of the texels
+ * of a slot's level 0 the read's footprint spans, clamped to the slot's chain. A read at level 0 is
+ * level 0's bilinear filter.
+ *
+ * By the pass's {@link INDIRECT_TEXTURE_FILTER}: one tap of the filter
+ * ({@link chunk_indirect_sample_texture_stochastic}, the default), or the filter itself
+ * ({@link chunk_indirect_sample_texture_exact}).
+ *
+ * Reads the `textures` atlas binding, which the shader that includes it declares.
+ *
+ * @type {CodeChunkChoice}
+ */
+export const chunk_indirect_sample_texture: CodeChunkChoice;
+import { CodeChunkChoice } from "../../shader/compiler/CodeChunkChoice.js";
 //# sourceMappingURL=chunk_indirect_sample_texture.d.ts.map

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_indirect_sample_texture.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture.js"],"names":[],"mappings":"AAWA,sDA6CE;0BApDwB,oCAAoC"}
+{"version":3,"file":"chunk_indirect_sample_texture.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH,4CAFU,eAAe,CAEkE;gCArB3D,0CAA0C"}

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture.js

@@ -1,57 +1,25 @@
-import { chunk_coordinate_wrap } from "../../shader/chunk/texture/chunk_coordinate_wrap.js";
-import { chunk_texture_sampler_enums } from "../../shader/chunk/texture/chunk_texture_sampler_enums.js";
-import { chunk_sampler_descriptor_unpack } from "../../shader/chunk/texture/chunk_sampler_descriptor_unpack.js";
-import { chunk_random_round_vec2 } from "../../shader/chunk/random/chunk_random_round_vec2.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import {
-    RESIDENT_MATERIAL_TEXTURE_RESOLUTION,
-    RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION,
-    RESIDENT_MATERIAL_TEXTURE_SLOTS_PER_LAYER
-} from "../../material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.js";
-
-export const chunk_indirect_sample_texture = CodeChunk.from(
-//language=WGSL
-    `
-fn indirect_sample_texture(id: u32, sampler_packed: u32, uv: vec2<f32>) -> vec4<f32>{
-
-    let sampler = sampler_descriptor_unpack(sampler_packed);
-
-    // figure out slot
-    let slot_z = id / ${RESIDENT_MATERIAL_TEXTURE_SLOTS_PER_LAYER};
-
-    let in_slice_id = id - slot_z * ${RESIDENT_MATERIAL_TEXTURE_SLOTS_PER_LAYER};
-
-    let slot_y = in_slice_id / ${RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION};
-    let slot_x = in_slice_id % ${RESIDENT_MATERIAL_TEXTURE_SLOT_RESOLUTION};
-
-    let texture_texel_coord = uv * vec2<f32>( ${RESIDENT_MATERIAL_TEXTURE_RESOLUTION} ) - 0.5;
-
-    // Texture Filtering: Nearest snaps to the closest texel; everything else
-    // (Linear and the higher-order filters) resolves to a stochastic bilinear
-    // tap, which converges to the filtered result across many samples. Mip
-    // level is ignored in the indirect path - we always read level 0.
-    var sample_coord: vec2<f32>;
-    if (sampler.mag_filter == TEXTURE_FILTER_NEAREST) {
-        sample_coord = round(texture_texel_coord);
-    } else {
-        sample_coord = random_round_vec2(texture_texel_coord);
-    }
-
-    // Texture Wrapping (per-axis, S->U / T->V)
-    let wrapped_coord = vec2(
-        coordinate_wrap(sample_coord.x, ${RESIDENT_MATERIAL_TEXTURE_RESOLUTION}, sampler.address_mode_u),
-        coordinate_wrap(sample_coord.y, ${RESIDENT_MATERIAL_TEXTURE_RESOLUTION}, sampler.address_mode_v),
-    );
-
-    // Convert to atlas space
-    let pixel_coord = vec2<u32>(slot_x, slot_y) * ${RESIDENT_MATERIAL_TEXTURE_RESOLUTION} +  vec2<u32>(wrapped_coord);
-
-    return textureLoad(textures, pixel_coord, slot_z, 0 );
-}
-    `, [
-        chunk_random_round_vec2,
-        chunk_coordinate_wrap,
-        chunk_texture_sampler_enums,
-        chunk_sampler_descriptor_unpack,
-    ]
-);
+import { CodeChunkChoice } from "../../shader/compiler/CodeChunkChoice.js";
+import { chunk_indirect_sample_texture_exact } from "./chunk_indirect_sample_texture_exact.js";
+import { chunk_indirect_sample_texture_stochastic } from "./chunk_indirect_sample_texture_stochastic.js";
+import { INDIRECT_TEXTURE_FILTER } from "./INDIRECT_TEXTURE_FILTER.js";
+import { IndirectTextureFilter } from "./IndirectTextureFilter.js";
+
+/**
+ * A resident material texture filtered at a level:
+ * `indirect_sample_texture(id: u32, sampler_packed: u32, uv: vec2<f32>, level: f32) -> vec4<f32>`, texture
+ * `id` of the atlas with its packed sampler's wrap and filter, trilinearly at `level`: log2 of the texels
+ * of a slot's level 0 the read's footprint spans, clamped to the slot's chain. A read at level 0 is
+ * level 0's bilinear filter.
+ *
+ * By the pass's {@link INDIRECT_TEXTURE_FILTER}: one tap of the filter
+ * ({@link chunk_indirect_sample_texture_stochastic}, the default), or the filter itself
+ * ({@link chunk_indirect_sample_texture_exact}).
+ *
+ * Reads the `textures` atlas binding, which the shader that includes it declares.
+ *
+ * @type {CodeChunkChoice}
+ */
+export const chunk_indirect_sample_texture = CodeChunkChoice.from(INDIRECT_TEXTURE_FILTER);
+
+chunk_indirect_sample_texture.add(IndirectTextureFilter.Stochastic, chunk_indirect_sample_texture_stochastic);
+chunk_indirect_sample_texture.add(IndirectTextureFilter.Exact, chunk_indirect_sample_texture_exact);

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture_exact.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `indirect_sample_texture(id, sampler_packed, uv, level)` as the filter itself
+ * ({@link INDIRECT_TEXTURE_FILTER} `Exact`): bilinear at the levels on either side of `level`, lerped by
+ * where it falls between them. No draw, so the same read gives the same value every time.
+ *
+ * Between a level's texels the filter is the sampler's mag filter, at every level, as the stochastic
+ * read takes it: Nearest snaps to the closest texel.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_indirect_sample_texture_exact: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_indirect_sample_texture_exact.d.ts.map

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture_exact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_indirect_sample_texture_exact.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture_exact.js"],"names":[],"mappings":"AAUA;;;;;;;;;GASG;AACH,kDAFU,SAAS,CAmDjB;0BA9DwB,oCAAoC"}

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture_exact.js

@@ -0,0 +1,70 @@
+import {
+    RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT,
+    RESIDENT_MATERIAL_TEXTURE_RESOLUTION
+} from "../../material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.js";
+import { chunk_sampler_descriptor_unpack } from "../../shader/chunk/texture/chunk_sampler_descriptor_unpack.js";
+import { chunk_texture_sampler_enums } from "../../shader/chunk/texture/chunk_texture_sampler_enums.js";
+import { SAMPLER_DESCRIPTOR_STRUCT } from "../../shader/chunk/texture/SAMPLER_DESCRIPTOR_STRUCT.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_indirect_texture_load } from "./chunk_indirect_texture_load.js";
+
+/**
+ * `indirect_sample_texture(id, sampler_packed, uv, level)` as the filter itself
+ * ({@link INDIRECT_TEXTURE_FILTER} `Exact`): bilinear at the levels on either side of `level`, lerped by
+ * where it falls between them. No draw, so the same read gives the same value every time.
+ *
+ * Between a level's texels the filter is the sampler's mag filter, at every level, as the stochastic
+ * read takes it: Nearest snaps to the closest texel.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_indirect_sample_texture_exact = CodeChunk.from(
+//language=WGSL
+    `
+fn indirect_sample_texture_level(id: u32, sampler: ${SAMPLER_DESCRIPTOR_STRUCT.wgsl_ref}, uv: vec2<f32>, mip: u32) -> vec4<f32>{
+
+    let texture_texel_coord = uv * f32(${RESIDENT_MATERIAL_TEXTURE_RESOLUTION}u >> mip) - 0.5;
+
+    if (sampler.mag_filter == TEXTURE_FILTER_NEAREST) {
+        return indirect_texture_load(id, sampler, round(texture_texel_coord), mip);
+    }
+
+    let corner = floor(texture_texel_coord);
+    let weight = texture_texel_coord - corner;
+
+    let row_0 = mix(
+        indirect_texture_load(id, sampler, corner, mip),
+        indirect_texture_load(id, sampler, corner + vec2<f32>(1.0, 0.0), mip),
+        weight.x
+    );
+    let row_1 = mix(
+        indirect_texture_load(id, sampler, corner + vec2<f32>(0.0, 1.0), mip),
+        indirect_texture_load(id, sampler, corner + vec2<f32>(1.0, 1.0), mip),
+        weight.x
+    );
+
+    return mix(row_0, row_1, weight.y);
+}
+
+fn indirect_sample_texture(id: u32, sampler_packed: u32, uv: vec2<f32>, level: f32) -> vec4<f32>{
+
+    let sampler = sampler_descriptor_unpack(sampler_packed);
+
+    let within = clamp(level, 0.0, ${RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT - 1}.0);
+
+    let lower = u32(within);
+    let upper = min(lower + 1u, ${RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT - 1}u);
+
+    return mix(
+        indirect_sample_texture_level(id, sampler, uv, lower),
+        indirect_sample_texture_level(id, sampler, uv, upper),
+        within - f32(lower)
+    );
+}
+    `, [
+        SAMPLER_DESCRIPTOR_STRUCT.declaration_chunk,
+        chunk_texture_sampler_enums,
+        chunk_sampler_descriptor_unpack,
+        chunk_indirect_texture_load,
+    ]
+);

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture_stochastic.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `indirect_sample_texture(id, sampler_packed, uv, level)` as one tap of the filter
+ * ({@link INDIRECT_TEXTURE_FILTER} `Stochastic`, the default): what the filter gives on average, which
+ * a pass converges to across many reads.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_indirect_sample_texture_stochastic: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_indirect_sample_texture_stochastic.d.ts.map

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture_stochastic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_indirect_sample_texture_stochastic.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture_stochastic.js"],"names":[],"mappings":"AAWA;;;;;;GAMG;AACH,uDAFU,SAAS,CA0CjB;0BAlDwB,oCAAoC"}

package/src/shade/renderer/path_tracer/shader/chunk_indirect_sample_texture_stochastic.js

@@ -0,0 +1,59 @@
+import {
+    RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT,
+    RESIDENT_MATERIAL_TEXTURE_RESOLUTION
+} from "../../material/resident/RESIDENT_MATERIAL_TEXTURE_LAYOUT.js";
+import { chunk_random } from "../../shader/chunk/random/chunk_random.js";
+import { chunk_random_round_vec2 } from "../../shader/chunk/random/chunk_random_round_vec2.js";
+import { chunk_sampler_descriptor_unpack } from "../../shader/chunk/texture/chunk_sampler_descriptor_unpack.js";
+import { chunk_texture_sampler_enums } from "../../shader/chunk/texture/chunk_texture_sampler_enums.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_indirect_texture_load } from "./chunk_indirect_texture_load.js";
+
+/**
+ * `indirect_sample_texture(id, sampler_packed, uv, level)` as one tap of the filter
+ * ({@link INDIRECT_TEXTURE_FILTER} `Stochastic`, the default): what the filter gives on average, which
+ * a pass converges to across many reads.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_indirect_sample_texture_stochastic = CodeChunk.from(
+//language=WGSL
+    `
+fn indirect_sample_texture(id: u32, sampler_packed: u32, uv: vec2<f32>, level: f32) -> vec4<f32>{
+
+    let sampler = sampler_descriptor_unpack(sampler_packed);
+
+    // a level between two is the upper one with the probability of its fraction: a draw, and none at a
+    // whole level, so a read at level 0 takes the random numbers it always did
+    let within = clamp(level, 0.0, ${RESIDENT_MATERIAL_TEXTURE_LEVEL_COUNT - 1}.0);
+
+    var mip = u32(within);
+
+    let fraction = within - f32(mip);
+
+    if (fraction > 0.0 && random() < fraction) {
+        mip += 1u;
+    }
+
+    let texture_texel_coord = uv * f32(${RESIDENT_MATERIAL_TEXTURE_RESOLUTION}u >> mip) - 0.5;
+
+    // Texture Filtering: Nearest snaps to the closest texel; everything else
+    // (Linear and the higher-order filters) resolves to a stochastic bilinear
+    // tap, which converges to the filtered result across many samples.
+    var sample_coord: vec2<f32>;
+    if (sampler.mag_filter == TEXTURE_FILTER_NEAREST) {
+        sample_coord = round(texture_texel_coord);
+    } else {
+        sample_coord = random_round_vec2(texture_texel_coord);
+    }
+
+    return indirect_texture_load(id, sampler, sample_coord, mip);
+}
+    `, [
+        chunk_random,
+        chunk_random_round_vec2,
+        chunk_texture_sampler_enums,
+        chunk_sampler_descriptor_unpack,
+        chunk_indirect_texture_load,
+    ]
+);

package/src/shade/renderer/path_tracer/shader/chunk_indirect_texture_load.d.ts

@@ -0,0 +1,12 @@
+/**
+ * One texel of a resident material texture: `indirect_texture_load(id, sampler, texel, level)`, the texel
+ * at the integer-valued coordinate `texel` of texture `id`'s slot at mip `level`, the coordinate wrapped
+ * within the slot at that level by the sampler's address modes (RESIDENT_MATERIAL_TEXTURE_LAYOUT).
+ *
+ * Reads the `textures` atlas binding, which the shader that includes it declares.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_indirect_texture_load: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_indirect_texture_load.d.ts.map