@woosh/meep-engine 3.56.0 → 3.58.0

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

@@ -0,0 +1,82 @@
+/**
+ * Bricks along each axis of a direction: the axis it looks along, then its columns' u and v.
+ *
+ * @param {number} direction
+ * @returns {number[]} axis, u axis, v axis
+ */
+export function mesh_card_axes(direction: number): number[];
+/**
+ * The range card placement runs in, for a level-0 grid of `bricks`: room for any layout of the grid,
+ * bounded before the cards are placed — at most MESH_CARD_MAX cards, each with no more columns than
+ * the largest face of the grid, and no more pages than columns — then the placement's scratch.
+ *
+ * @param {ArrayLike<number>} bricks level 0's bricks along x, y and z
+ * @returns {{histograms: number, splits: number, words: number, layers: number, columns_max: number}}
+ * word offsets from the range's start, and its length
+ */
+export function mesh_card_placement_of(bricks: ArrayLike<number>): {
+    histograms: number;
+    splits: number;
+    words: number;
+    layers: number;
+    columns_max: number;
+};
+/**
+ * Words a placed layout keeps: its header and records, its column tables and its page list.
+ *
+ * @param {number} columns over every card
+ * @param {number} pages
+ * @returns {number}
+ */
+export function mesh_card_layout_words(columns: number, pages: number): number;
+/**
+ * Cards a geometry has at most: UE's ceiling.
+ * @type {number}
+ */
+export const MESH_CARD_MAX: number;
+/**
+ * ±X, ±Y and ±Z.
+ * @type {number}
+ */
+export const MESH_CARD_DIRECTIONS: number;
+/**
+ * Texels a page has along each side: a brick face's corners, as a brick's texels sit on its voxels'.
+ * @type {number}
+ */
+export const MESH_CARD_PAGE_TEXELS: number;
+/** A column a card sees nothing in. */
+export const MESH_CARD_NO_PAGE: 4294967295;
+/** Layout header: cards placed. */
+export const MESH_CARD_LAYOUT_CARD_COUNT: 0;
+/** Layout header: pages over every card. */
+export const MESH_CARD_LAYOUT_PAGE_COUNT: 1;
+/** Layout header: columns over every card, the column tables' length. */
+export const MESH_CARD_LAYOUT_COLUMN_COUNT: 2;
+/**
+ * Layout header: each direction's first card, {@link MESH_CARD_DIRECTIONS} words. The records are
+ * written direction by direction, so a direction's cards run from its word to the next direction's,
+ * and the last direction's to the card count. A reader looking along one direction reads its run alone.
+ */
+export const MESH_CARD_LAYOUT_DIRECTION_FIRST: 3;
+/** Layout header, in words. */
+export const MESH_CARD_LAYOUT_HEADER_WORDS: number;
+/** Card record: the direction it looks along. */
+export const MESH_CARD_RECORD_DIRECTION: 0;
+/** Card record: the first layer of its slab. */
+export const MESH_CARD_RECORD_NEAR: 1;
+/** Card record: one past the last layer of its slab. */
+export const MESH_CARD_RECORD_FAR: 2;
+/** Card record: its column table, from the tables' start. */
+export const MESH_CARD_RECORD_TABLE: 3;
+/** Card record, in words. */
+export const MESH_CARD_RECORD_WORDS: 4;
+/** Where the card records start, from the layout's start. */
+export const MESH_CARD_LAYOUT_RECORDS: number;
+/** Where the column tables start, from the layout's start. The page list follows them. */
+export const MESH_CARD_LAYOUT_TABLES: number;
+/**
+ * Splits a direction's greedy search may record: every card past the six whole-grid ones.
+ * @type {number}
+ */
+export const MESH_CARD_SPLITS_MAX: number;
+//# sourceMappingURL=MESH_CARDS.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MESH_CARDS.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/MESH_CARDS.js"],"names":[],"mappings":"AAmFA;;;;;GAKG;AACH,0CAHW,MAAM,GACJ,MAAM,EAAE,CAMpB;AAED;;;;;;;;GAQG;AACH,+CAJW,UAAU,MAAM,CAAC,GACf;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAcpG;AAED;;;;;;GAMG;AACH,gDAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;AArGD;;;GAGG;AACH,4BAFU,MAAM,CAEgB;AAEhC;;;GAGG;AACH,mCAFU,MAAM,CAEsB;AAEtC;;;GAGG;AACH,oCAFU,MAAM,CAE2C;AAE3D,uCAAuC;AACvC,2CAA4C;AAE5C,mCAAmC;AACnC,4CAA6C;AAC7C,4CAA4C;AAC5C,4CAA6C;AAC7C,yEAAyE;AACzE,8CAA+C;AAC/C;;;;GAIG;AACH,iDAAkD;AAClD,+BAA+B;AAC/B,mDAAqG;AAErG,iDAAiD;AACjD,2CAA4C;AAC5C,gDAAgD;AAChD,sCAAuC;AACvC,wDAAwD;AACxD,qCAAsC;AACtC,6DAA6D;AAC7D,uCAAwC;AACxC,6BAA6B;AAC7B,uCAAwC;AAExC,6DAA6D;AAC7D,8CAAsE;AACtE,0FAA0F;AAC1F,6CAAyG;AAEzG;;;GAGG;AACH,mCAFU,MAAM,CAEyD"}

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

@@ -0,0 +1,127 @@
+import { MESH_SDF_BRICK_TEXELS } from "../MESH_SDF.js";
+
+/*
+ A geometry's surface cards (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.5): slabs of its level-0 brick
+ grid seen along ±X, ±Y and ±Z of its local space. Their layout lives in the indirection arena at
+ the header's `cards` word, made once a geometry's field is resident:
+
+   header           MESH_CARD_LAYOUT_HEADER_WORDS: card count, page count, columns over every card,
+                    each direction's first card
+   card records     at MESH_CARD_LAYOUT_RECORDS, MESH_CARD_MAX of MESH_CARD_RECORD_WORDS: direction,
+                    near and far layer, the offset of its column table in the tables
+   column tables    at MESH_CARD_LAYOUT_TABLES, a word for each column of each card, along the
+                    card's direction: the page seeing that column, or MESH_CARD_NO_PAGE
+   page list        right after the tables, a word a page: its card, and its column's u and v
+
+ Placement runs in a range sized for any layout of the grid ({@link mesh_card_placement_of}), its
+ scratch past that: run starts by (m, z) along each direction, then each direction's splits. Its log
+ record gives the columns and pages it took; the layout is then moved into a range of its own size
+ ({@link mesh_card_layout_words}), and the placement's range is given back.
+
+ A direction d looks along axis d >> 1, toward +axis when d is even. Layer 0 is the first brick a
+ ray along the direction meets; a column is a line of bricks along it, at (u, v) on the other two
+ axes in order.
+*/
+
+/**
+ * Cards a geometry has at most: UE's ceiling.
+ * @type {number}
+ */
+export const MESH_CARD_MAX = 32;
+
+/**
+ * ±X, ±Y and ±Z.
+ * @type {number}
+ */
+export const MESH_CARD_DIRECTIONS = 6;
+
+/**
+ * Texels a page has along each side: a brick face's corners, as a brick's texels sit on its voxels'.
+ * @type {number}
+ */
+export const MESH_CARD_PAGE_TEXELS = MESH_SDF_BRICK_TEXELS;
+
+/** A column a card sees nothing in. */
+export const MESH_CARD_NO_PAGE = 0xffffffff;
+
+/** Layout header: cards placed. */
+export const MESH_CARD_LAYOUT_CARD_COUNT = 0;
+/** Layout header: pages over every card. */
+export const MESH_CARD_LAYOUT_PAGE_COUNT = 1;
+/** Layout header: columns over every card, the column tables' length. */
+export const MESH_CARD_LAYOUT_COLUMN_COUNT = 2;
+/**
+ * Layout header: each direction's first card, {@link MESH_CARD_DIRECTIONS} words. The records are
+ * written direction by direction, so a direction's cards run from its word to the next direction's,
+ * and the last direction's to the card count. A reader looking along one direction reads its run alone.
+ */
+export const MESH_CARD_LAYOUT_DIRECTION_FIRST = 3;
+/** Layout header, in words. */
+export const MESH_CARD_LAYOUT_HEADER_WORDS = MESH_CARD_LAYOUT_DIRECTION_FIRST + MESH_CARD_DIRECTIONS;
+
+/** Card record: the direction it looks along. */
+export const MESH_CARD_RECORD_DIRECTION = 0;
+/** Card record: the first layer of its slab. */
+export const MESH_CARD_RECORD_NEAR = 1;
+/** Card record: one past the last layer of its slab. */
+export const MESH_CARD_RECORD_FAR = 2;
+/** Card record: its column table, from the tables' start. */
+export const MESH_CARD_RECORD_TABLE = 3;
+/** Card record, in words. */
+export const MESH_CARD_RECORD_WORDS = 4;
+
+/** Where the card records start, from the layout's start. */
+export const MESH_CARD_LAYOUT_RECORDS = MESH_CARD_LAYOUT_HEADER_WORDS;
+/** Where the column tables start, from the layout's start. The page list follows them. */
+export const MESH_CARD_LAYOUT_TABLES = MESH_CARD_LAYOUT_RECORDS + MESH_CARD_MAX * MESH_CARD_RECORD_WORDS;
+
+/**
+ * Splits a direction's greedy search may record: every card past the six whole-grid ones.
+ * @type {number}
+ */
+export const MESH_CARD_SPLITS_MAX = MESH_CARD_MAX - MESH_CARD_DIRECTIONS;
+
+/**
+ * Bricks along each axis of a direction: the axis it looks along, then its columns' u and v.
+ *
+ * @param {number} direction
+ * @returns {number[]} axis, u axis, v axis
+ */
+export function mesh_card_axes(direction) {
+    const axis = direction >> 1;
+
+    return [axis, (axis + 1) % 3, (axis + 2) % 3];
+}
+
+/**
+ * The range card placement runs in, for a level-0 grid of `bricks`: room for any layout of the grid,
+ * bounded before the cards are placed — at most MESH_CARD_MAX cards, each with no more columns than
+ * the largest face of the grid, and no more pages than columns — then the placement's scratch.
+ *
+ * @param {ArrayLike<number>} bricks level 0's bricks along x, y and z
+ * @returns {{histograms: number, splits: number, words: number, layers: number, columns_max: number}}
+ * word offsets from the range's start, and its length
+ */
+export function mesh_card_placement_of(bricks) {
+    const layers = Math.max(bricks[0], bricks[1], bricks[2]);
+    const columns_max = Math.max(bricks[0] * bricks[1], bricks[1] * bricks[2], bricks[0] * bricks[2]);
+
+    // a histogram a direction, layers × layers: run starts by (m, z), then its 2-D prefix sums
+    const histograms = MESH_CARD_LAYOUT_TABLES + 2 * MESH_CARD_MAX * columns_max;
+    // a direction's splits in the order its greedy search took them: (gain, layer)
+    const splits = histograms + MESH_CARD_DIRECTIONS * layers * layers;
+    const words = splits + MESH_CARD_DIRECTIONS * MESH_CARD_SPLITS_MAX * 2;
+
+    return { histograms, splits, words, layers, columns_max };
+}
+
+/**
+ * Words a placed layout keeps: its header and records, its column tables and its page list.
+ *
+ * @param {number} columns over every card
+ * @param {number} pages
+ * @returns {number}
+ */
+export function mesh_card_layout_words(columns, pages) {
+    return MESH_CARD_LAYOUT_TABLES + columns + pages;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Every card set's record, by card set id.
+ * @type {ShaderResourceDescriptor}
+ */
+export const MESH_CARD_SETS_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The card atlas's first plane: √(diffuse albedo), and depth through the slab on [1/255, 1], 0 where
+ * a texel saw nothing. `rgba8unorm`, 8×8 tiles, read texel by texel.
+ * @type {ShaderResourceDescriptor}
+ */
+export const MESH_CARD_ALBEDO_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The card atlas's second plane: emissive / s_e.
+ * @type {ShaderResourceDescriptor}
+ */
+export const MESH_CARD_EMISSIVE_RESOURCE: ShaderResourceDescriptor;
+/**
+ * A word a `meshes` row: the card set of the row's (geometry, material) pair, or
+ * `GPU_DATABASE_NULL` while it has none that readers may use.
+ * @type {ShaderResourceDescriptor}
+ */
+export const MESH_CARD_ROWS_RESOURCE: ShaderResourceDescriptor;
+import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
+//# sourceMappingURL=MESH_CARD_RESOURCES.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MESH_CARD_RESOURCES.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/MESH_CARD_RESOURCES.js"],"names":[],"mappings":"AAIA;;;GAGG;AACH,sCAFU,wBAAwB,CAEsG;AAExI;;;;GAIG;AACH,wCAFU,wBAAwB,CAE2E;AAE7G;;;GAGG;AACH,0CAFU,wBAAwB,CAE+E;AAEjH;;;;GAIG;AACH,sCAFU,wBAAwB,CAE+E;yCA5BxE,sDAAsD"}

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

@@ -0,0 +1,29 @@
+import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { MESH_CARD_SET_STRUCT } from "./MESH_CARD_SET_STRUCT.js";
+
+/**
+ * Every card set's record, by card set id.
+ * @type {ShaderResourceDescriptor}
+ */
+export const MESH_CARD_SETS_RESOURCE = ShaderResourceDescriptor.storageBuffer("mesh_card_sets", WebGPUArray.from(MESH_CARD_SET_STRUCT));
+
+/**
+ * The card atlas's first plane: √(diffuse albedo), and depth through the slab on [1/255, 1], 0 where
+ * a texel saw nothing. `rgba8unorm`, 8×8 tiles, read texel by texel.
+ * @type {ShaderResourceDescriptor}
+ */
+export const MESH_CARD_ALBEDO_RESOURCE = ShaderResourceDescriptor.texture("mesh_card_albedo", "float", "2d");
+
+/**
+ * The card atlas's second plane: emissive / s_e.
+ * @type {ShaderResourceDescriptor}
+ */
+export const MESH_CARD_EMISSIVE_RESOURCE = ShaderResourceDescriptor.texture("mesh_card_emissive", "float", "2d");
+
+/**
+ * A word a `meshes` row: the card set of the row's (geometry, material) pair, or
+ * `GPU_DATABASE_NULL` while it has none that readers may use.
+ * @type {ShaderResourceDescriptor}
+ */
+export const MESH_CARD_ROWS_RESOURCE = ShaderResourceDescriptor.storageBuffer("mesh_card_rows", WebGPUArray.u32);

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

@@ -0,0 +1,12 @@
+/**
+ * A card set: one (geometry, material) pair's capture of its geometry's card layout
+ * (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.5), by card set id. Its pages are a run of tiles of the
+ * card atlas, one a page of the layout, in the layout's page order.
+ *
+ * 16 bytes.
+ *
+ * @type {WebGPUStruct}
+ */
+export const MESH_CARD_SET_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=MESH_CARD_SET_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MESH_CARD_SET_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/MESH_CARD_SET_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,mCAFU,YAAY,CAoBJ;6BA7BW,sCAAsC"}

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

@@ -0,0 +1,31 @@
+import { f32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+
+/**
+ * A card set: one (geometry, material) pair's capture of its geometry's card layout
+ * (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.5), by card set id. Its pages are a run of tiles of the
+ * card atlas, one a page of the layout, in the layout's page order.
+ *
+ * 16 bytes.
+ *
+ * @type {WebGPUStruct}
+ */
+export const MESH_CARD_SET_STRUCT = WebGPUStruct.from({
+    /**
+     * The geometry id whose layout this captures: the source's, for a skinned row.
+     */
+    geometry: u32,
+    /**
+     * The material's resident id.
+     */
+    material: u32,
+    /**
+     * The tile of the card atlas holding the layout's page 0.
+     */
+    page_base: u32,
+    /**
+     * s_e: the largest component of the material's emissive factor, which emissive is stored over.
+     * 0 for a material that emits nothing.
+     */
+    emissive_scale: f32,
+}, "MeshCardSet");

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

@@ -0,0 +1,29 @@
+/**
+ * What a card set's cards say of a surface point (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6, steps
+ * 2–5), in the geometry's local space:
+ *
+ * ```wgsl
+ * fn mesh_card_surface(card_set: u32, p: vec3<f32>, n: vec3<f32>, tolerance: f32) -> MeshCardSurface
+ * ```
+ *
+ * - The directions facing the surface: for each axis a with n_a ≠ 0, the cards looking along
+ *   −sign(n_a)·e_a, weighed by n_a², as UE weighs them.
+ * - A card of such a direction passes when its slab holds p's depth within `tolerance`, and the
+ *   texel nearest p stored a depth within `tolerance` and one step of the slab of p's: otherwise it
+ *   sees something in front of p. Of a direction's passing cards, the one whose near face is
+ *   nearest p serves, one texel.
+ * - The serving texels blend by weight: diffuse albedo as Σ w·stored² / Σ w, emissive as
+ *   Σ w·stored·s_e / Σ w.
+ *
+ * `found` is false when no card passes; the caller falls back (§6.6 step 6). `tolerance` is in local
+ * units: 1.5 voxels of the hit's cascade, which is as exact as the hit is. The card set must be one
+ * readers may use (resident), its layout placed.
+ *
+ * A direction's scan reads that direction's cards alone, the run the layout's header names; a
+ * candidate costs a table entry and a texel of each plane.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mesh_card_surface: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_mesh_card_surface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_mesh_card_surface.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/chunk_mesh_card_surface.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,sCAFU,SAAS,CA4IZ;0BA3KmB,uCAAuC"}

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

@@ -0,0 +1,179 @@
+import { chunk_index_to_grid2d } from "../../../shader/chunk/grid/chunk_index_to_grid2d.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { MESH_SDF_HEADERS_RESOURCE, MESH_SDF_INDIRECTION_RESOURCE } from "../MESH_SDF_RESOURCES.js";
+import { MESH_SDF_STRUCT } from "../MESH_SDF_STRUCT.js";
+import { chunk_mesh_cards } from "./chunk_mesh_cards.js";
+import { MESH_CARD_SET_STRUCT } from "./MESH_CARD_SET_STRUCT.js";
+import { MESH_CARD_ALBEDO_RESOURCE, MESH_CARD_EMISSIVE_RESOURCE, MESH_CARD_SETS_RESOURCE } from "./MESH_CARD_RESOURCES.js";
+
+/**
+ * What a card set's cards say of a surface point (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6, steps
+ * 2–5), in the geometry's local space:
+ *
+ * ```wgsl
+ * fn mesh_card_surface(card_set: u32, p: vec3<f32>, n: vec3<f32>, tolerance: f32) -> MeshCardSurface
+ * ```
+ *
+ * - The directions facing the surface: for each axis a with n_a ≠ 0, the cards looking along
+ *   −sign(n_a)·e_a, weighed by n_a², as UE weighs them.
+ * - A card of such a direction passes when its slab holds p's depth within `tolerance`, and the
+ *   texel nearest p stored a depth within `tolerance` and one step of the slab of p's: otherwise it
+ *   sees something in front of p. Of a direction's passing cards, the one whose near face is
+ *   nearest p serves, one texel.
+ * - The serving texels blend by weight: diffuse albedo as Σ w·stored² / Σ w, emissive as
+ *   Σ w·stored·s_e / Σ w.
+ *
+ * `found` is false when no card passes; the caller falls back (§6.6 step 6). `tolerance` is in local
+ * units: 1.5 voxels of the hit's cascade, which is as exact as the hit is. The card set must be one
+ * readers may use (resident), its layout placed.
+ *
+ * A direction's scan reads that direction's cards alone, the run the layout's header names; a
+ * candidate costs a table entry and a texel of each plane.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mesh_card_surface = CodeChunk.from(
+    //language=WGSL
+    `
+struct MeshCardSurface {
+    found: bool,
+    albedo: vec3<f32>,
+    emissive: vec3<f32>,
+}
+
+struct MeshCardAxis {
+    found: bool,
+    depth: f32,
+    albedo: vec3<f32>,
+    emissive: vec3<f32>,
+}
+
+/*
+ The serving card of the direction facing p along one axis, if one passes. p and the tolerance are
+ in voxels from the grid's corner.
+*/
+fn mesh_card_surface_axis(
+    card_set: ${MESH_CARD_SET_STRUCT.wgsl_ref},
+    header: ${MESH_SDF_STRUCT.wgsl_ref},
+    p: vec3<f32>,
+    normal_component: f32,
+    axis: u32,
+    tolerance: f32,
+) -> MeshCardAxis {
+    var out: MeshCardAxis;
+
+    out.depth = 3.0e38;
+
+    // a surface facing +axis is seen by the cards looking toward -axis: the odd direction
+    let direction = 2u * axis + select(0u, 1u, normal_component > 0.0);
+    let axes = mesh_card_axes(direction);
+    let extent = mesh_card_extent(header.bricks, direction);
+    let lattice = vec2<f32>(f32(extent.y * MESH_SDF_BRICK_VOXELS), f32(extent.z * MESH_SDF_BRICK_VOXELS));
+
+    // the lattice point nearest p across the card, and the page column and texel it falls in
+    let nearest = vec2<u32>(clamp(round(vec2<f32>(p[axes.y], p[axes.z])), vec2<f32>(0.0), lattice));
+    let column = min(nearest / MESH_SDF_BRICK_VOXELS, extent.yz - 1u);
+    let texel = nearest - column * MESH_SDF_BRICK_VOXELS;
+    let column_index = column.x + extent.y * column.y;
+
+    // the records run direction by direction: this direction's from its first card to the next one's
+    let base = header.cards;
+    let first = mesh_sdf_indirection[base + MESH_CARD_LAYOUT_DIRECTION_FIRST + direction];
+    let end = select(
+        mesh_sdf_indirection[base + MESH_CARD_LAYOUT_DIRECTION_FIRST + direction + 1u],
+        mesh_sdf_indirection[base + MESH_CARD_LAYOUT_CARD_COUNT],
+        direction == MESH_CARD_DIRECTIONS - 1u
+    );
+    let tiles_per_row = textureDimensions(mesh_card_albedo).x / MESH_CARD_PAGE_TEXELS;
+
+    for (var card = first; card < min(end, MESH_CARD_MAX); card++) {
+        let record = base + MESH_CARD_LAYOUT_RECORDS + card * MESH_CARD_RECORD_WORDS;
+
+        let near = mesh_sdf_indirection[record + MESH_CARD_RECORD_NEAR];
+        let far = mesh_sdf_indirection[record + MESH_CARD_RECORD_FAR];
+
+        // p's depth from the card's near face, and the slab's
+        let face = f32(select(extent.x - near, near, (direction & 1u) == 0u) * MESH_SDF_BRICK_VOXELS);
+        let depth = select(face - p[axis], p[axis] - face, (direction & 1u) == 0u);
+        let slab = f32((far - near) * MESH_SDF_BRICK_VOXELS);
+
+        if (depth < -tolerance || depth > slab + tolerance || depth >= out.depth) {
+            continue;
+        }
+
+        let page = mesh_sdf_indirection[base + MESH_CARD_LAYOUT_TABLES + mesh_sdf_indirection[record + MESH_CARD_RECORD_TABLE] + column_index];
+
+        if (page == MESH_CARD_NO_PAGE) {
+            continue;
+        }
+
+        let coord = index_to_grid2d(card_set.page_base + page, tiles_per_row) * MESH_CARD_PAGE_TEXELS + texel;
+        let albedo = textureLoad(mesh_card_albedo, coord, 0);
+
+        if (albedo.w < 0.5 / 255.0) {
+            // the texel's ray found nothing in the slab
+            continue;
+        }
+
+        let seen = (albedo.w * 255.0 - 1.0) / 254.0 * slab;
+
+        if (abs(seen - depth) > tolerance + slab / 254.0) {
+            // the card sees something in front of p
+            continue;
+        }
+
+        out.found = true;
+        out.depth = depth;
+        out.albedo = albedo.rgb * albedo.rgb;
+        out.emissive = textureLoad(mesh_card_emissive, coord, 0).rgb * card_set.emissive_scale;
+    }
+
+    return out;
+}
+
+fn mesh_card_surface(card_set_id: u32, p: vec3<f32>, n: vec3<f32>, tolerance: f32) -> MeshCardSurface {
+    let card_set = mesh_card_sets[card_set_id];
+    let header = mesh_sdf_headers[card_set.geometry];
+
+    let local = (p - header.origin) / header.voxel;
+    let reach = tolerance / header.voxel;
+
+    var out: MeshCardSurface;
+    var weight = 0.0;
+
+    for (var axis = 0u; axis < 3u; axis++) {
+        let w = n[axis] * n[axis];
+
+        if (w == 0.0) {
+            continue;
+        }
+
+        let seen = mesh_card_surface_axis(card_set, header, local, n[axis], axis, reach);
+
+        if (seen.found) {
+            out.albedo += w * seen.albedo;
+            out.emissive += w * seen.emissive;
+            weight += w;
+        }
+    }
+
+    if (weight > 0.0) {
+        out.found = true;
+        out.albedo /= weight;
+        out.emissive /= weight;
+    }
+
+    return out;
+}
+`, [
+        MESH_CARD_SET_STRUCT.declaration_chunk,
+        MESH_SDF_STRUCT.declaration_chunk,
+        chunk_mesh_cards,
+        chunk_index_to_grid2d,
+    ]);
+
+chunk_mesh_card_surface.requireResource(MESH_SDF_HEADERS_RESOURCE);
+chunk_mesh_card_surface.requireResource(MESH_SDF_INDIRECTION_RESOURCE);
+chunk_mesh_card_surface.requireResource(MESH_CARD_SETS_RESOURCE);
+chunk_mesh_card_surface.requireResource(MESH_CARD_ALBEDO_RESOURCE);
+chunk_mesh_card_surface.requireResource(MESH_CARD_EMISSIVE_RESOURCE);

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

@@ -0,0 +1,17 @@
+/**
+ * A geometry's cards on the device (`MESH_CARDS.js`): the layout's constants, the placement's
+ * scratch by the level-0 grid, a direction's axes and extent, and the brick a direction's column
+ * holds at a layer. Pure: nothing here reads a binding.
+ *
+ * ```wgsl
+ * fn mesh_card_placement_of(bricks: vec3<u32>) -> MeshCardPlacement  // offsets from the range's start
+ * fn mesh_card_axes(direction: u32) -> vec3<u32>                // the axis looked along, then u, v
+ * fn mesh_card_extent(bricks: vec3<u32>, direction: u32) -> vec3<u32>
+ * fn mesh_card_brick(bricks: vec3<u32>, direction: u32, column: vec2<u32>, layer: u32) -> vec3<u32>
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mesh_cards: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_mesh_cards.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_mesh_cards.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/cards/chunk_mesh_cards.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;GAaG;AACH,+BAFU,SAAS,CAwEZ;0BA1GmB,uCAAuC"}

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

@@ -0,0 +1,107 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { chunk_mesh_sdf } from "../chunk_mesh_sdf.js";
+import { MESH_SDF_STRUCT } from "../MESH_SDF_STRUCT.js";
+import {
+    MESH_CARD_DIRECTIONS,
+    MESH_CARD_LAYOUT_CARD_COUNT,
+    MESH_CARD_LAYOUT_COLUMN_COUNT,
+    MESH_CARD_LAYOUT_DIRECTION_FIRST,
+    MESH_CARD_LAYOUT_PAGE_COUNT,
+    MESH_CARD_LAYOUT_RECORDS,
+    MESH_CARD_LAYOUT_TABLES,
+    MESH_CARD_MAX,
+    MESH_CARD_NO_PAGE,
+    MESH_CARD_PAGE_TEXELS,
+    MESH_CARD_RECORD_DIRECTION,
+    MESH_CARD_RECORD_FAR,
+    MESH_CARD_RECORD_NEAR,
+    MESH_CARD_RECORD_TABLE,
+    MESH_CARD_RECORD_WORDS,
+    MESH_CARD_SPLITS_MAX
+} from "./MESH_CARDS.js";
+
+/**
+ * A geometry's cards on the device (`MESH_CARDS.js`): the layout's constants, the placement's
+ * scratch by the level-0 grid, a direction's axes and extent, and the brick a direction's column
+ * holds at a layer. Pure: nothing here reads a binding.
+ *
+ * ```wgsl
+ * fn mesh_card_placement_of(bricks: vec3<u32>) -> MeshCardPlacement  // offsets from the range's start
+ * fn mesh_card_axes(direction: u32) -> vec3<u32>                // the axis looked along, then u, v
+ * fn mesh_card_extent(bricks: vec3<u32>, direction: u32) -> vec3<u32>
+ * fn mesh_card_brick(bricks: vec3<u32>, direction: u32, column: vec2<u32>, layer: u32) -> vec3<u32>
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mesh_cards = CodeChunk.from(
+    //language=WGSL
+    `
+const MESH_CARD_MAX = ${MESH_CARD_MAX}u;
+const MESH_CARD_DIRECTIONS = ${MESH_CARD_DIRECTIONS}u;
+const MESH_CARD_SPLITS_MAX = ${MESH_CARD_SPLITS_MAX}u;
+const MESH_CARD_PAGE_TEXELS = ${MESH_CARD_PAGE_TEXELS}u;
+const MESH_CARD_NO_PAGE = ${MESH_CARD_NO_PAGE}u;
+
+const MESH_CARD_LAYOUT_CARD_COUNT = ${MESH_CARD_LAYOUT_CARD_COUNT}u;
+const MESH_CARD_LAYOUT_PAGE_COUNT = ${MESH_CARD_LAYOUT_PAGE_COUNT}u;
+const MESH_CARD_LAYOUT_COLUMN_COUNT = ${MESH_CARD_LAYOUT_COLUMN_COUNT}u;
+const MESH_CARD_LAYOUT_DIRECTION_FIRST = ${MESH_CARD_LAYOUT_DIRECTION_FIRST}u;
+const MESH_CARD_LAYOUT_RECORDS = ${MESH_CARD_LAYOUT_RECORDS}u;
+const MESH_CARD_LAYOUT_TABLES = ${MESH_CARD_LAYOUT_TABLES}u;
+
+const MESH_CARD_RECORD_DIRECTION = ${MESH_CARD_RECORD_DIRECTION}u;
+const MESH_CARD_RECORD_NEAR = ${MESH_CARD_RECORD_NEAR}u;
+const MESH_CARD_RECORD_FAR = ${MESH_CARD_RECORD_FAR}u;
+const MESH_CARD_RECORD_TABLE = ${MESH_CARD_RECORD_TABLE}u;
+const MESH_CARD_RECORD_WORDS = ${MESH_CARD_RECORD_WORDS}u;
+
+struct MeshCardPlacement {
+    histograms: u32,
+    splits: u32,
+    layers: u32,
+}
+
+fn mesh_card_placement_of(bricks: vec3<u32>) -> MeshCardPlacement {
+    let layers = max(bricks.x, max(bricks.y, bricks.z));
+    let columns_max = max(bricks.x * bricks.y, max(bricks.y * bricks.z, bricks.x * bricks.z));
+
+    var parts: MeshCardPlacement;
+
+    parts.histograms = MESH_CARD_LAYOUT_TABLES + 2u * MESH_CARD_MAX * columns_max;
+    parts.splits = parts.histograms + MESH_CARD_DIRECTIONS * layers * layers;
+    parts.layers = layers;
+
+    return parts;
+}
+
+fn mesh_card_axes(direction: u32) -> vec3<u32> {
+    let axis = direction >> 1u;
+
+    return vec3<u32>(axis, (axis + 1u) % 3u, (axis + 2u) % 3u);
+}
+
+fn mesh_card_extent(bricks: vec3<u32>, direction: u32) -> vec3<u32> {
+    let axes = mesh_card_axes(direction);
+
+    return vec3<u32>(bricks[axes.x], bricks[axes.y], bricks[axes.z]);
+}
+
+fn mesh_card_brick(bricks: vec3<u32>, direction: u32, column: vec2<u32>, layer: u32) -> vec3<u32> {
+    let axes = mesh_card_axes(direction);
+
+    // an even direction looks toward +axis, so its layer 0 is the grid's first brick along it
+    let along = select(bricks[axes.x] - 1u - layer, layer, (direction & 1u) == 0u);
+
+    var brick = vec3<u32>(0u);
+
+    brick[axes.x] = along;
+    brick[axes.y] = column.x;
+    brick[axes.z] = column.y;
+
+    return brick;
+}
+`, [
+        chunk_mesh_sdf,
+        MESH_SDF_STRUCT.declaration_chunk,
+    ]);