@woosh/meep-engine 3.56.0 → 3.58.0

package/src/shade/renderer/geometry/sdf/cards/shader_mesh_cards_merge.js

@@ -0,0 +1,136 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { chunk_mesh_sdf_bake, MESH_SDF_ARENA_RESOURCE } from "../bake/chunk_mesh_sdf_bake.js";
+import { MESH_SDF_BAKE_WORKGROUP_SIZE } from "../bake/MESH_SDF_BAKE.js";
+import { MESH_SDF_HEADERS_RESOURCE } from "../MESH_SDF_RESOURCES.js";
+import { chunk_mesh_cards } from "./chunk_mesh_cards.js";
+import { MESH_CARD_DIRECTIONS } from "./MESH_CARDS.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const MESH_CARDS_MERGE_SETTINGS = WebGPUStruct.from({
+    /** the geometry whose cards are placed */
+    geometry: u32,
+    /** where in `mesh_sdf_take` the page pass's dispatch goes, in words */
+    dispatch: u32,
+}, "MeshCardsMergeSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", MESH_CARDS_MERGE_SETTINGS);
+
+resources.createGroup()
+    .add(MESH_SDF_HEADERS_RESOURCE)
+    .add(MESH_SDF_ARENA_RESOURCE)
+    .addStorageBuffer("mesh_sdf_take", WebGPUArray.u32, true);
+
+/**
+ * Card placement, step 3 (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.5): one thread. The six directions'
+ * splits are taken in order of gain, as the greedy search over all six would take them, until the
+ * gains run out or the geometry has MESH_CARD_MAX cards. Every run start is then covered, or the
+ * ceiling has left some uncovered, which read the material mean.
+ *
+ * The cards are written direction by direction, each direction's cards by their near layer. Each
+ * card records its direction, its slab, and where its column table starts: a word for each column of
+ * its direction, laid out card after card. The layout's header gets the card count, each direction's
+ * first card, and the columns over every card. The page pass's dispatch goes to `mesh_sdf_take`: a
+ * thread a column.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_cards_merge = ComputeShader.from({
+    label: "Mesh Cards Merge",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(1)
+fn main() {
+    let header = mesh_sdf_headers[settings.geometry];
+    let parts = mesh_card_placement_of(header.bricks);
+    let base = header.cards;
+
+    // each direction's next split, and its card starts so far: layer 0 starts the whole-grid card
+    var next = array<u32, ${MESH_CARD_DIRECTIONS}>();
+    var bounds = array<vec2<u32>, ${MESH_CARD_DIRECTIONS}>();
+
+    for (var d = 0u; d < MESH_CARD_DIRECTIONS; d++) {
+        bounds[d] = vec2<u32>(1u, 0u);
+    }
+
+    for (var taken = 0u; taken < MESH_CARD_SPLITS_MAX; taken++) {
+        var best = MESH_CARD_DIRECTIONS;
+        var best_gain = 0u;
+
+        for (var d = 0u; d < MESH_CARD_DIRECTIONS; d++) {
+            if (next[d] >= MESH_CARD_SPLITS_MAX) {
+                continue;
+            }
+
+            let gain = atomicLoad(&mesh_sdf_indirection[base + parts.splits + (d * MESH_CARD_SPLITS_MAX + next[d]) * 2u]);
+
+            if (gain > best_gain) {
+                best_gain = gain;
+                best = d;
+            }
+        }
+
+        if (best == MESH_CARD_DIRECTIONS) {
+            break;
+        }
+
+        let layer = atomicLoad(&mesh_sdf_indirection[base + parts.splits + (best * MESH_CARD_SPLITS_MAX + next[best]) * 2u + 1u]);
+
+        bounds[best][layer >> 5u] |= 1u << (layer & 31u);
+        next[best]++;
+    }
+
+    var cards = 0u;
+    var columns = 0u;
+
+    for (var d = 0u; d < MESH_CARD_DIRECTIONS; d++) {
+        let extent = mesh_card_extent(header.bricks, d);
+        let bound = bounds[d];
+
+        atomicStore(&mesh_sdf_indirection[base + MESH_CARD_LAYOUT_DIRECTION_FIRST + d], cards);
+
+        var near = 0u;
+
+        while (near < extent.x) {
+            var far = near + 1u;
+
+            while (far < extent.x && ((bound[far >> 5u] >> (far & 31u)) & 1u) == 0u) {
+                far++;
+            }
+
+            let record = base + MESH_CARD_LAYOUT_RECORDS + cards * MESH_CARD_RECORD_WORDS;
+
+            atomicStore(&mesh_sdf_indirection[record + MESH_CARD_RECORD_DIRECTION], d);
+            atomicStore(&mesh_sdf_indirection[record + MESH_CARD_RECORD_NEAR], near);
+            atomicStore(&mesh_sdf_indirection[record + MESH_CARD_RECORD_FAR], far);
+            atomicStore(&mesh_sdf_indirection[record + MESH_CARD_RECORD_TABLE], columns);
+
+            cards++;
+            columns += extent.y * extent.z;
+            near = far;
+        }
+    }
+
+    atomicStore(&mesh_sdf_indirection[base + MESH_CARD_LAYOUT_CARD_COUNT], cards);
+    atomicStore(&mesh_sdf_indirection[base + MESH_CARD_LAYOUT_COLUMN_COUNT], columns);
+    atomicStore(&mesh_sdf_indirection[base + MESH_CARD_LAYOUT_PAGE_COUNT], 0u);
+
+    mesh_sdf_take[settings.dispatch] = (columns + ${MESH_SDF_BAKE_WORKGROUP_SIZE - 1}u) / ${MESH_SDF_BAKE_WORKGROUP_SIZE}u;
+    mesh_sdf_take[settings.dispatch + 1u] = 1u;
+    mesh_sdf_take[settings.dispatch + 2u] = 1u;
+}
+`, [
+            chunk_mesh_sdf_bake,
+            chunk_mesh_cards,
+        ]),
+});

package/src/shade/renderer/geometry/sdf/cards/shader_mesh_cards_pages.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const MESH_CARDS_PAGES_SETTINGS: WebGPUStruct;
+/**
+ * Card placement, step 4 (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.5): a thread a column of every card,
+ * dispatched by the merge. A card has a page in a column when its slab holds an occupied brick
+ * there; the page is the column's 8×8 texels on the corner lattice of the bricks' faces.
+ *
+ * A column with a page takes the next page index, and writes it into its card's column table and
+ * itself into the page list: its card, then its column's u and v, a byte each. A column without one
+ * writes MESH_CARD_NO_PAGE. The pages come out in whatever order the threads take them. Capture
+ * walks the page list and a hit reads the column table, so neither needs another order.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_cards_pages: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_mesh_cards_pages.d.ts.map

package/src/shade/renderer/geometry/sdf/cards/shader_mesh_cards_pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_mesh_cards_pages.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/shader_mesh_cards_pages.js"],"names":[],"mappings":"AAUA;;GAEG;AACH,wCAFU,YAAY,CAKO;AAU7B;;;;;;;;;;;GAWG;AACH,sCAFU,aAAa,CAmEpB;6BAnG0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/geometry/sdf/cards/shader_mesh_cards_pages.js

@@ -0,0 +1,104 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { chunk_mesh_sdf_bake, MESH_SDF_ARENA_RESOURCE } from "../bake/chunk_mesh_sdf_bake.js";
+import { MESH_SDF_BAKE_WORKGROUP_SIZE } from "../bake/MESH_SDF_BAKE.js";
+import { MESH_SDF_HEADERS_RESOURCE } from "../MESH_SDF_RESOURCES.js";
+import { chunk_mesh_cards } from "./chunk_mesh_cards.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const MESH_CARDS_PAGES_SETTINGS = WebGPUStruct.from({
+    /** the geometry whose cards are placed */
+    geometry: u32,
+}, "MeshCardsPagesSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", MESH_CARDS_PAGES_SETTINGS);
+
+resources.createGroup()
+    .add(MESH_SDF_HEADERS_RESOURCE)
+    .add(MESH_SDF_ARENA_RESOURCE);
+
+/**
+ * Card placement, step 4 (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.5): a thread a column of every card,
+ * dispatched by the merge. A card has a page in a column when its slab holds an occupied brick
+ * there; the page is the column's 8×8 texels on the corner lattice of the bricks' faces.
+ *
+ * A column with a page takes the next page index, and writes it into its card's column table and
+ * itself into the page list: its card, then its column's u and v, a byte each. A column without one
+ * writes MESH_CARD_NO_PAGE. The pages come out in whatever order the threads take them. Capture
+ * walks the page list and a hit reads the column table, so neither needs another order.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_cards_pages = ComputeShader.from({
+    label: "Mesh Cards Pages",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${MESH_SDF_BAKE_WORKGROUP_SIZE})
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let header = mesh_sdf_headers[settings.geometry];
+    let base = header.cards;
+    let bricks = header.bricks;
+
+    let thread = id.x;
+    let columns = atomicLoad(&mesh_sdf_indirection[base + MESH_CARD_LAYOUT_COLUMN_COUNT]);
+
+    if (thread >= columns) {
+        return;
+    }
+
+    // the card whose columns hold the thread: the last whose table starts at or before it
+    let cards = atomicLoad(&mesh_sdf_indirection[base + MESH_CARD_LAYOUT_CARD_COUNT]);
+
+    var card = 0u;
+
+    for (var c = 1u; c < cards; c++) {
+        if (atomicLoad(&mesh_sdf_indirection[base + MESH_CARD_LAYOUT_RECORDS + c * MESH_CARD_RECORD_WORDS + MESH_CARD_RECORD_TABLE]) > thread) {
+            break;
+        }
+
+        card = c;
+    }
+
+    let record = base + MESH_CARD_LAYOUT_RECORDS + card * MESH_CARD_RECORD_WORDS;
+    let direction = atomicLoad(&mesh_sdf_indirection[record + MESH_CARD_RECORD_DIRECTION]);
+    let near = atomicLoad(&mesh_sdf_indirection[record + MESH_CARD_RECORD_NEAR]);
+    let far = atomicLoad(&mesh_sdf_indirection[record + MESH_CARD_RECORD_FAR]);
+    let table = atomicLoad(&mesh_sdf_indirection[record + MESH_CARD_RECORD_TABLE]);
+
+    let extent = mesh_card_extent(bricks, direction);
+    let index = thread - table;
+    let column = vec2<u32>(index % extent.y, index / extent.y);
+
+    var seen = false;
+
+    for (var layer = near; layer < far && !seen; layer++) {
+        let brick = mesh_card_brick(bricks, direction, column, layer);
+
+        seen = mesh_sdf_entry_holds_slot(atomicLoad(&mesh_sdf_indirection[header.indirection + brick.x + bricks.x * (brick.y + bricks.y * brick.z)]));
+    }
+
+    var page = MESH_CARD_NO_PAGE;
+
+    if (seen) {
+        page = atomicAdd(&mesh_sdf_indirection[base + MESH_CARD_LAYOUT_PAGE_COUNT], 1u);
+
+        // the page list follows the tables
+        atomicStore(&mesh_sdf_indirection[base + MESH_CARD_LAYOUT_TABLES + columns + page], (card << 16u) | (column.y << 8u) | column.x);
+    }
+
+    atomicStore(&mesh_sdf_indirection[base + MESH_CARD_LAYOUT_TABLES + thread], page);
+}
+`, [
+            chunk_mesh_sdf_bake,
+            chunk_mesh_cards,
+        ]),
+});

package/src/shade/renderer/geometry/sdf/cards/shader_mesh_cards_split.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const MESH_CARDS_SPLIT_SETTINGS: WebGPUStruct;
+/**
+ * Card placement, step 2 (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.5): a thread a direction runs its
+ * greedy search. The direction starts with one card over the whole grid, its outer projection, and
+ * each split takes the layer that newly covers the most run starts.
+ *
+ * Within a direction the cards partition the layers. A run start (m, z) lies in the card whose
+ * layers hold z, and is covered when that card's near face is at or before m. A split of card
+ * [k₀, k₁) at layer s gives the far part [s, k₁), which newly covers the uncovered run starts with
+ * k₀ < m ≤ s ≤ z < k₁. The near part keeps its own, so coverage never shrinks. That count is a
+ * rectangle of the (m, z) histogram, read from its 2-D prefix sums in four loads.
+ *
+ * A direction's gains never grow from one split to the next, and splits along one direction leave
+ * the others' gains alone. Merging the six directions' sequences by gain is therefore the greedy
+ * search over all six, which the merge does. The splits are written in the order taken, (gain,
+ * layer) each, MESH_CARD_SPLITS_MAX at most; the first gain of 0 ends the sequence.
+ *
+ * Runs on the device as the bake does, a pass with nothing to wait on, though the six threads do
+ * work a frame's passes must not: the prefix sums over every (m, z) of the direction, and up to 26
+ * scans of its layers. It runs once for each geometry that turns resident.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_cards_split: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_mesh_cards_split.d.ts.map

package/src/shade/renderer/geometry/sdf/cards/shader_mesh_cards_split.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_mesh_cards_split.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/shader_mesh_cards_split.js"],"names":[],"mappings":"AAUA;;GAEG;AACH,wCAFU,YAAY,CAKO;AAU7B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,sCAFU,aAAa,CAmGpB;6BA7I0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/geometry/sdf/cards/shader_mesh_cards_split.js

@@ -0,0 +1,146 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { chunk_mesh_sdf_bake, MESH_SDF_ARENA_RESOURCE } from "../bake/chunk_mesh_sdf_bake.js";
+import { MESH_SDF_HEADERS_RESOURCE } from "../MESH_SDF_RESOURCES.js";
+import { chunk_mesh_cards } from "./chunk_mesh_cards.js";
+import { MESH_CARD_DIRECTIONS } from "./MESH_CARDS.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const MESH_CARDS_SPLIT_SETTINGS = WebGPUStruct.from({
+    /** the geometry whose cards are placed */
+    geometry: u32,
+}, "MeshCardsSplitSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", MESH_CARDS_SPLIT_SETTINGS);
+
+resources.createGroup()
+    .add(MESH_SDF_HEADERS_RESOURCE)
+    .add(MESH_SDF_ARENA_RESOURCE);
+
+/**
+ * Card placement, step 2 (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.5): a thread a direction runs its
+ * greedy search. The direction starts with one card over the whole grid, its outer projection, and
+ * each split takes the layer that newly covers the most run starts.
+ *
+ * Within a direction the cards partition the layers. A run start (m, z) lies in the card whose
+ * layers hold z, and is covered when that card's near face is at or before m. A split of card
+ * [k₀, k₁) at layer s gives the far part [s, k₁), which newly covers the uncovered run starts with
+ * k₀ < m ≤ s ≤ z < k₁. The near part keeps its own, so coverage never shrinks. That count is a
+ * rectangle of the (m, z) histogram, read from its 2-D prefix sums in four loads.
+ *
+ * A direction's gains never grow from one split to the next, and splits along one direction leave
+ * the others' gains alone. Merging the six directions' sequences by gain is therefore the greedy
+ * search over all six, which the merge does. The splits are written in the order taken, (gain,
+ * layer) each, MESH_CARD_SPLITS_MAX at most; the first gain of 0 ends the sequence.
+ *
+ * Runs on the device as the bake does, a pass with nothing to wait on, though the six threads do
+ * work a frame's passes must not: the prefix sums over every (m, z) of the direction, and up to 26
+ * scans of its layers. It runs once for each geometry that turns resident.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_cards_split = ComputeShader.from({
+    label: "Mesh Cards Split",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+/** whether layer k starts a card, two words for up to 64 layers */
+fn mesh_cards_starts(bounds: vec2<u32>, layer: u32) -> bool {
+    return ((bounds[layer >> 5u] >> (layer & 31u)) & 1u) != 0u;
+}
+
+fn mesh_cards_histogram_at(histogram: u32, stride: u32, m: i32, z: i32) -> u32 {
+    if (m < 0 || z < 0) {
+        return 0u;
+    }
+
+    return atomicLoad(&mesh_sdf_indirection[histogram + u32(m) * stride + u32(z)]);
+}
+
+/** run starts with m in [m0, m1] and z in [z0, z1], from the prefix sums */
+fn mesh_cards_rectangle(histogram: u32, stride: u32, m0: i32, m1: i32, z0: i32, z1: i32) -> u32 {
+    if (m0 > m1 || z0 > z1) {
+        return 0u;
+    }
+
+    return mesh_cards_histogram_at(histogram, stride, m1, z1)
+        + mesh_cards_histogram_at(histogram, stride, m0 - 1, z0 - 1)
+        - mesh_cards_histogram_at(histogram, stride, m0 - 1, z1)
+        - mesh_cards_histogram_at(histogram, stride, m1, z0 - 1);
+}
+
+@compute @workgroup_size(${MESH_CARD_DIRECTIONS})
+fn main(@builtin(local_invocation_index) direction: u32) {
+    let header = mesh_sdf_headers[settings.geometry];
+    let parts = mesh_card_placement_of(header.bricks);
+    let layers = mesh_card_extent(header.bricks, direction).x;
+    let stride = parts.layers;
+
+    let histogram = header.cards + parts.histograms + direction * stride * stride;
+
+    // the 2-D inclusive prefix sums, in place
+    for (var m = 0; m < i32(layers); m++) {
+        for (var z = 0; z < i32(layers); z++) {
+            let sum = atomicLoad(&mesh_sdf_indirection[histogram + u32(m) * stride + u32(z)])
+                + mesh_cards_histogram_at(histogram, stride, m - 1, z)
+                + mesh_cards_histogram_at(histogram, stride, m, z - 1)
+                - mesh_cards_histogram_at(histogram, stride, m - 1, z - 1);
+
+            atomicStore(&mesh_sdf_indirection[histogram + u32(m) * stride + u32(z)], sum);
+        }
+    }
+
+    let splits = header.cards + parts.splits + direction * MESH_CARD_SPLITS_MAX * 2u;
+
+    // layer 0 starts the whole-grid card
+    var bounds = vec2<u32>(1u, 0u);
+
+    for (var step = 0u; step < MESH_CARD_SPLITS_MAX; step++) {
+        var best_gain = 0u;
+        var best_layer = 0u;
+
+        // card by card, each [near, far), every layer inside it a candidate
+        var near = 0u;
+
+        while (near < layers) {
+            var far = near + 1u;
+
+            while (far < layers && !mesh_cards_starts(bounds, far)) {
+                far++;
+            }
+
+            for (var s = near + 1u; s < far; s++) {
+                let gain = mesh_cards_rectangle(histogram, stride, i32(near) + 1, i32(s), i32(s), i32(far) - 1);
+
+                if (gain > best_gain) {
+                    best_gain = gain;
+                    best_layer = s;
+                }
+            }
+
+            near = far;
+        }
+
+        if (best_gain == 0u) {
+            break;
+        }
+
+        atomicStore(&mesh_sdf_indirection[splits + 2u * step], best_gain);
+        atomicStore(&mesh_sdf_indirection[splits + 2u * step + 1u], best_layer);
+
+        bounds[best_layer >> 5u] |= 1u << (best_layer & 31u);
+    }
+}
+`, [
+            chunk_mesh_sdf_bake,
+            chunk_mesh_cards,
+        ]),
+});

package/src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Strata along a side of each of the vote's two hemispheres, as UE 5.4 has them: 7 × 7 directions a
+ * hemisphere.
+ * @type {number}
+ */
+export const BLAS_BAND_VOTE_STRATA: number;
+/**
+ * Rays of the vote: two hemispheres of {@link BLAS_BAND_VOTE_STRATA}² directions, 98.
+ * @type {number}
+ */
+export const BLAS_BAND_VOTE_RAYS: number;
+/**
+ * A geometry's signed distance within a band, signed by UE 5.4's vote (`MeshDistanceFieldUtilities.cpp`,
+ * `FMeshDistanceFieldAsyncTask::DoWork`):
+ *
+ * - The nearest point within the band, through the BLAS. With none, the point is a band away, outside,
+ *   and casts no ray.
+ * - Within the band, {@link BLAS_BAND_VOTE_RAYS} rays one band long vote, each pulled back 1e-4 of the
+ *   band so that a point on a face meets it. The point is inside when a ray meets the surface and more
+ *   than a quarter of them meet a back face.
+ * - A two-sided geometry has no back face: it is outside throughout, and casts no ray either.
+ *
+ * The directions are UE's, made as its stream runs, ray after ray: `FRandomStream(0)` drives two
+ * `GenerateStratifiedUniformHemisphereSamples(49)` on Shirley and Chiu's concentric map, and the second
+ * hemisphere's Z is negated. UE's Z is our Y.
+ *
+ * ```wgsl
+ * fn blas_query_band_sdf(point: vec3<f32>, geometry_index: u32, band: f32, two_sided: bool, contact, stack, stack_top: u32) -> f32
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_blas_query_band_sdf: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_blas_query_band_sdf.d.ts.map

package/src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_blas_query_band_sdf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.js"],"names":[],"mappings":"AAgBA;;;;GAIG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,kCAFU,MAAM,CAEqE;AAErF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wCAFU,SAAS,CAgHjB;0BAlJwB,oCAAoC"}

package/src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.js

@@ -0,0 +1,161 @@
+import { UINT32_MAX } from "../../../../core/binary/UINT32_MAX.js";
+import { BVH_TRAVERSAL_STACK_SIZE } from "../../shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
+import {
+    chunk_geometry_read_triangle_vertices
+} from "../../shader/chunk/geometry/format/chunk_geometry_read_triangle_vertices.js";
+import {
+    chunk_compute_triangle_face_normal
+} from "../../shader/chunk/geometry/normal/chunk_compute_triangle_face_normal.js";
+import { chunk_ray_query_blas_nearest } from "../../shader/chunk/geometry/ray/chunk_ray_query_blas_nearest.js";
+import { RAY_STRUCT } from "../../shader/chunk/geometry/ray/RAY_STRUCT.js";
+import { chunk_f32_array_as_vec3 } from "../../shader/chunk/geometry/vec3/chunk_f32_array_as_vec3.js";
+import { PI_DECLARATION } from "../../shader/chunk/math/PI_DECLARATION.js";
+import { chunk_point_query_blas_nearest } from "../../shader/chunk/sdf/chunk_point_query_blas_nearest.js";
+import { SURFACE_POINT_3D } from "../../shader/chunk/sdf/SURFACE_POINT_3D.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Strata along a side of each of the vote's two hemispheres, as UE 5.4 has them: 7 × 7 directions a
+ * hemisphere.
+ * @type {number}
+ */
+export const BLAS_BAND_VOTE_STRATA = 7;
+
+/**
+ * Rays of the vote: two hemispheres of {@link BLAS_BAND_VOTE_STRATA}² directions, 98.
+ * @type {number}
+ */
+export const BLAS_BAND_VOTE_RAYS = 2 * BLAS_BAND_VOTE_STRATA * BLAS_BAND_VOTE_STRATA;
+
+/**
+ * A geometry's signed distance within a band, signed by UE 5.4's vote (`MeshDistanceFieldUtilities.cpp`,
+ * `FMeshDistanceFieldAsyncTask::DoWork`):
+ *
+ * - The nearest point within the band, through the BLAS. With none, the point is a band away, outside,
+ *   and casts no ray.
+ * - Within the band, {@link BLAS_BAND_VOTE_RAYS} rays one band long vote, each pulled back 1e-4 of the
+ *   band so that a point on a face meets it. The point is inside when a ray meets the surface and more
+ *   than a quarter of them meet a back face.
+ * - A two-sided geometry has no back face: it is outside throughout, and casts no ray either.
+ *
+ * The directions are UE's, made as its stream runs, ray after ray: `FRandomStream(0)` drives two
+ * `GenerateStratifiedUniformHemisphereSamples(49)` on Shirley and Chiu's concentric map, and the second
+ * hemisphere's Z is negated. UE's Z is our Y.
+ *
+ * ```wgsl
+ * fn blas_query_band_sdf(point: vec3<f32>, geometry_index: u32, band: f32, two_sided: bool, contact, stack, stack_top: u32) -> f32
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_blas_query_band_sdf = CodeChunk.from(
+    //language=WGSL
+    `
+const BLAS_BAND_VOTE_STRATA = ${BLAS_BAND_VOTE_STRATA}u;
+const BLAS_BAND_VOTE_HEMISPHERE = ${BLAS_BAND_VOTE_STRATA * BLAS_BAND_VOTE_STRATA}u;
+const BLAS_BAND_VOTE_RAYS = ${BLAS_BAND_VOTE_RAYS}u;
+
+/** FRandomStream::GetFraction: the stream's next fraction in [0, 1) */
+fn blas_band_vote_fraction(seed: ptr<function, u32>) -> f32 {
+    *seed = *seed * 196314165u + 907633515u;
+
+    return bitcast<f32>(0x3F800000u | (*seed >> 9u)) - 1.0;
+}
+
+/** direction i of the vote, its stratum's square jittered by the stream's two fractions */
+fn blas_band_vote_direction(i: u32, u1: f32, u2: f32) -> vec3<f32> {
+    let stratum = i % BLAS_BAND_VOTE_HEMISPHERE;
+    let square = vec2<f32>(
+        (f32(stratum / BLAS_BAND_VOTE_STRATA) + u1) / f32(BLAS_BAND_VOTE_STRATA),
+        (f32(stratum % BLAS_BAND_VOTE_STRATA) + u2) / f32(BLAS_BAND_VOTE_STRATA)
+    ) * 2.0 - 1.0;
+
+    if (square.x == 0.0 && square.y == 0.0) {
+        return vec3<f32>(0.0);
+    }
+
+    // onto the disk, concentrically
+    var r: f32;
+    var theta: f32;
+
+    if (abs(square.x) > abs(square.y)) {
+        r = square.x;
+        theta = PI / 4.0 * (square.y / square.x);
+    } else {
+        r = square.y;
+        theta = PI / 2.0 - PI / 4.0 * (square.x / square.y);
+    }
+
+    // and up onto the hemisphere
+    let u = r * cos(theta);
+    let v = r * sin(theta);
+    let r2 = r * r;
+    let lift = sqrt(2.0 - r2);
+    let up = select(1.0 - r2, r2 - 1.0, i >= BLAS_BAND_VOTE_HEMISPHERE);
+
+    return vec3<f32>(u * lift, up, v * lift);
+}
+
+fn blas_query_band_sdf(
+    point: vec3<f32>,
+    geometry_index: u32,
+    band: f32,
+    two_sided: bool,
+    contact: ptr<function, ${SURFACE_POINT_3D.wgsl_ref}>,
+    traversal_stack: ptr<function, array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>>,
+    stack_top: u32
+) -> f32 {
+    *contact = point_query_blas_nearest(point, band, geometry_index, traversal_stack, stack_top);
+
+    if ((*contact).primitive == ${UINT32_MAX}u) {
+        return band;
+    }
+
+    let distance = min(band, length(point - (*contact).position));
+
+    if (two_sided) {
+        return distance;
+    }
+
+    var seed = 0u;
+    var back = 0u;
+
+    for (var i = 0u; i < BLAS_BAND_VOTE_RAYS; i++) {
+        let u1 = blas_band_vote_fraction(&seed);
+        let u2 = blas_band_vote_fraction(&seed);
+        let direction = blas_band_vote_direction(i, u1, u2);
+
+        var ray: ${RAY_STRUCT.wgsl_ref};
+
+        ray.origin = point - 1e-4 * band * direction;
+        ray.direction = direction;
+        ray.tmax = band;
+
+        let hit = ray_query_blas_nearest(ray, geometry_index, traversal_stack, stack_top);
+
+        if (hit.t < 0.0) {
+            continue;
+        }
+
+        let triangle = geometry_read_triangle_vertices(geometries[geometry_index], hit.triangle);
+        let normal = compute_triangle_face_normal(triangle.a.position, triangle.b.position, triangle.c.position);
+
+        if (dot(direction, normal) > 0.0) {
+            back++;
+        }
+    }
+
+    // UE's Hit > 0 && HitBack > 0.25 · samples, of which the first follows from the second
+    return select(distance, -distance, 4u * back > BLAS_BAND_VOTE_RAYS);
+}
+`, [
+        PI_DECLARATION,
+        SURFACE_POINT_3D.declaration_chunk,
+        RAY_STRUCT.declaration_chunk,
+        chunk_point_query_blas_nearest,
+        chunk_ray_query_blas_nearest,
+        chunk_geometry_read_triangle_vertices,
+        chunk_f32_array_as_vec3,
+        chunk_compute_triangle_face_normal,
+    ]
+);

package/src/shade/renderer/geometry/sdf/chunk_mesh_sdf.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The arithmetic of a geometry's sparse distance field on the device — {@link MeshSDFLayout}'s, and
+ * the encoding of a texel — over a {@link MESH_SDF_STRUCT} passed by value. Pure: nothing here reads a
+ * binding.
+ *
+ * ```wgsl
+ * fn mesh_sdf_level_bricks(header: MeshSDF, level: u32) -> vec3<u32>
+ * fn mesh_sdf_level_offset(header: MeshSDF, level: u32) -> u32   // the level's first entry
+ * fn mesh_sdf_level_voxel(header: MeshSDF, level: u32) -> f32
+ * fn mesh_sdf_brick_of(header: MeshSDF, brick: u32) -> vec4<u32> // level, then x, y, z
+ * fn mesh_sdf_brick_corner(header: MeshSDF, brick: vec4<u32>) -> vec3<f32> // texel 0's point
+ * fn mesh_sdf_encode(distance: f32, voxel: f32) -> f32           // saturate(d / 2R + 0.5)
+ * fn mesh_sdf_decode(encoded: f32, voxel: f32) -> f32
+ * fn mesh_sdf_entry_holds_slot(entry: u32) -> bool               // not EMPTY, on either side
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mesh_sdf: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_mesh_sdf.d.ts.map

package/src/shade/renderer/geometry/sdf/chunk_mesh_sdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_mesh_sdf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/chunk_mesh_sdf.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;GAiBG;AACH,6BAFU,SAAS,CAoFZ;0BA/GmB,oCAAoC"}