@woosh/meep-engine 3.61.2 → 3.61.3

package/src/shade/renderer/geometry/sdf/surface/shader_mesh_surface_list.js

@@ -0,0 +1,99 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { MESH_SDF_BAKE_WORKGROUP_SIZE } from "../bake/MESH_SDF_BAKE.js";
+import { chunk_mesh_sdf } from "../chunk_mesh_sdf.js";
+import { MESH_SDF_BRICK_TEXEL_COUNT, MESH_SDF_BRICK_TEXELS } from "../MESH_SDF.js";
+import {
+    MESH_SDF_ATLAS_RESOURCE,
+    MESH_SDF_HEADERS_RESOURCE,
+    MESH_SDF_INDIRECTION_RESOURCE,
+    MESH_SDF_SAMPLER_RESOURCE
+} from "../MESH_SDF_RESOURCES.js";
+import { chunk_mesh_surface_listed } from "./chunk_mesh_surface_listed.js";
+import { chunk_mesh_surface_run_find } from "./chunk_mesh_surface_run_find.js";
+import {
+    MESH_SURFACE_COUNTER_LISTED,
+    MESH_SURFACE_COUNTER_RESOURCE,
+    MESH_SURFACE_LIST_SETTINGS,
+    MESH_SURFACE_RUNS_RESOURCE,
+    MESH_SURFACE_STAGING_WORDS,
+    MESH_SURFACE_STAGING_WRITE_RESOURCE,
+    MESH_SURFACE_TEXEL_STRUCT,
+    MESH_SURFACE_TEXELS_WRITE_RESOURCE
+} from "./MESH_SURFACE_BAKE.js";
+import { MESH_SURFACE_RECORDS_RESOURCE } from "./MESH_SURFACE_RESOURCES.js";
+import { MESH_SURFACE_STRUCT } from "./MESH_SURFACE_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", MESH_SURFACE_LIST_SETTINGS);
+
+resources.createGroup()
+    .add(MESH_SDF_HEADERS_RESOURCE)
+    .add(MESH_SDF_INDIRECTION_RESOURCE)
+    .add(MESH_SDF_ATLAS_RESOURCE)
+    .add(MESH_SDF_SAMPLER_RESOURCE)
+    .add(MESH_SURFACE_RECORDS_RESOURCE)
+    .add(MESH_SURFACE_RUNS_RESOURCE)
+    .add(MESH_SURFACE_TEXELS_WRITE_RESOURCE)
+    .add(MESH_SURFACE_COUNTER_RESOURCE)
+    .add(MESH_SURFACE_STAGING_WRITE_RESOURCE);
+
+/**
+ * Model Surface Cache bake, first pass (`MESH_SURFACE_BAKE.js`): a thread a texel of the frame's runs'
+ * bricks, the bricks a run's cache's field numbered from the run's first number on.
+ *
+ * Every texel's staging, the slot of its thread, is cleared to no surface. A texel that can hold surface
+ * (`mesh_surface_listed`) is listed for the trace, with what it resolved.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_surface_list = ComputeShader.from({
+    label: "Mesh Surface List",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${MESH_SDF_BAKE_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let thread = (workgroup_id.y * settings.groups_x + workgroup_id.x) * ${MESH_SDF_BAKE_WORKGROUP_SIZE}u + lane;
+
+    if (thread >= settings.thread_count) {
+        return;
+    }
+
+    let run = mesh_surface_runs[mesh_surface_run_find(settings.run_count, thread)];
+    let offset = thread - run.x;
+    let number = run.z + offset / ${MESH_SDF_BRICK_TEXEL_COUNT}u;
+    let index = offset % ${MESH_SDF_BRICK_TEXEL_COUNT}u;
+
+    let record = mesh_surface_records[run.y];
+    let header = mesh_sdf_headers[record.geometry];
+    let b = mesh_sdf_indirection[mesh_sdf_numbered(header) + number];
+
+    let t = ${MESH_SDF_BRICK_TEXELS}u;
+    let texel = vec3<u32>(index % t, (index / t) % t, index / (t * t));
+
+    // the albedo word says whether the trace found surface
+    mesh_surface_staging[${MESH_SURFACE_STAGING_WORDS}u * thread] = 0u;
+
+    if (mesh_surface_listed(header, b, texel)) {
+        let listed = atomicAdd(&mesh_surface_counter[${MESH_SURFACE_COUNTER_LISTED}u], 1u);
+
+        if (listed < settings.capacity) {
+            mesh_surface_texels[listed] = ${MESH_SURFACE_TEXEL_STRUCT.wgsl_ref}(record.geometry, record.material, b, index, thread);
+        }
+    }
+}
+`, [
+            MESH_SURFACE_STRUCT.declaration_chunk,
+            MESH_SURFACE_TEXEL_STRUCT.declaration_chunk,
+            chunk_mesh_sdf,
+            chunk_mesh_surface_listed,
+            chunk_mesh_surface_run_find,
+        ]),
+});

package/src/shade/renderer/geometry/sdf/surface/shader_mesh_surface_survey.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Model Surface Cache survey, first pass (`MESH_SURFACE_BAKE.js`): a thread a texel of the frame's
+ * survey runs' bricks, a run a stretch of one field's stored bricks by number. A texel that can hold
+ * surface (`mesh_surface_listed`, as the bake lists it) sets its block's bit in its brick's table word,
+ * which the host cleared before the field's first run.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_surface_survey: ComputeShader;
+/**
+ * Model Surface Cache survey, second pass: a thread a brick of each field whose survey the frame
+ * completes, a run a field's bricks, with its table's word, its result and the ticket the host asked
+ * for it under. Each brick takes as many block numbers as its mask has blocks, counted out of its
+ * field's result, and its table word becomes its first number above its mask; brick 0 writes the
+ * ticket beside the count, so a result no pass wrote is told apart. The numbers of a field's bricks
+ * follow the order they are taken in, which nothing reads into.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_surface_number: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_mesh_surface_survey.d.ts.map

package/src/shade/renderer/geometry/sdf/surface/shader_mesh_surface_survey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_mesh_surface_survey.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/surface/shader_mesh_surface_survey.js"],"names":[],"mappings":"AAoCA;;;;;;;GAOG;AACH,yCAFU,aAAa,CAyCpB;AAWH;;;;;;;;;GASG;AACH,yCAFU,aAAa,CAqCpB;8BA1I2B,kCAAkC"}

package/src/shade/renderer/geometry/sdf/surface/shader_mesh_surface_survey.js

@@ -0,0 +1,140 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { MESH_SDF_BAKE_WORKGROUP_SIZE } from "../bake/MESH_SDF_BAKE.js";
+import { chunk_mesh_sdf } from "../chunk_mesh_sdf.js";
+import { MESH_SDF_BRICK_TEXEL_COUNT, MESH_SDF_BRICK_TEXELS } from "../MESH_SDF.js";
+import {
+    MESH_SDF_ATLAS_RESOURCE,
+    MESH_SDF_HEADERS_RESOURCE,
+    MESH_SDF_INDIRECTION_RESOURCE,
+    MESH_SDF_SAMPLER_RESOURCE
+} from "../MESH_SDF_RESOURCES.js";
+import { chunk_mesh_surface_block_index } from "./chunk_mesh_surface_block.js";
+import { chunk_mesh_surface_listed } from "./chunk_mesh_surface_listed.js";
+import { chunk_mesh_surface_run_find } from "./chunk_mesh_surface_run_find.js";
+import {
+    MESH_SURFACE_DATA_ATOMIC_RESOURCE,
+    MESH_SURFACE_RUNS_RESOURCE,
+    MESH_SURFACE_SURVEY_RESULT_WORDS,
+    MESH_SURFACE_SURVEY_RESULTS_RESOURCE,
+    MESH_SURFACE_SURVEY_SETTINGS
+} from "./MESH_SURFACE_BAKE.js";
+import { MESH_SURFACE_TABLE_MASK_BITS } from "./MESH_SURFACE_BLOCK.js";
+
+const survey_resources = new ShaderResourceSetDescriptor();
+
+survey_resources.setImmediate("settings", MESH_SURFACE_SURVEY_SETTINGS);
+
+survey_resources.createGroup()
+    .add(MESH_SDF_HEADERS_RESOURCE)
+    .add(MESH_SDF_INDIRECTION_RESOURCE)
+    .add(MESH_SDF_ATLAS_RESOURCE)
+    .add(MESH_SDF_SAMPLER_RESOURCE)
+    .add(MESH_SURFACE_RUNS_RESOURCE)
+    .add(MESH_SURFACE_DATA_ATOMIC_RESOURCE);
+
+/**
+ * Model Surface Cache survey, first pass (`MESH_SURFACE_BAKE.js`): a thread a texel of the frame's
+ * survey runs' bricks, a run a stretch of one field's stored bricks by number. A texel that can hold
+ * surface (`mesh_surface_listed`, as the bake lists it) sets its block's bit in its brick's table word,
+ * which the host cleared before the field's first run.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_surface_survey = ComputeShader.from({
+    label: "Mesh Surface Survey",
+    resources: survey_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${MESH_SDF_BAKE_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let thread = (workgroup_id.y * settings.groups_x + workgroup_id.x) * ${MESH_SDF_BAKE_WORKGROUP_SIZE}u + lane;
+
+    if (thread >= settings.thread_count) {
+        return;
+    }
+
+    // its first thread, the geometry, its first brick number, its table's word
+    let run = mesh_surface_runs[mesh_surface_run_find(settings.run_count, thread)];
+    let offset = thread - run.x;
+    let number = run.z + offset / ${MESH_SDF_BRICK_TEXEL_COUNT}u;
+    let index = offset % ${MESH_SDF_BRICK_TEXEL_COUNT}u;
+
+    let header = mesh_sdf_headers[run.y];
+    let b = mesh_sdf_indirection[mesh_sdf_numbered(header) + number];
+
+    let t = ${MESH_SDF_BRICK_TEXELS}u;
+    let texel = vec3<u32>(index % t, (index / t) % t, index / (t * t));
+
+    if (mesh_surface_listed(header, b, texel)) {
+        atomicOr(&mesh_surface_data[run.w + number], 1u << mesh_surface_block_of(texel));
+    }
+}
+`, [
+            chunk_mesh_sdf,
+            chunk_mesh_surface_listed,
+            chunk_mesh_surface_block_index,
+            chunk_mesh_surface_run_find,
+        ]),
+});
+
+const number_resources = new ShaderResourceSetDescriptor();
+
+number_resources.setImmediate("settings", MESH_SURFACE_SURVEY_SETTINGS);
+
+number_resources.createGroup()
+    .add(MESH_SURFACE_RUNS_RESOURCE)
+    .add(MESH_SURFACE_DATA_ATOMIC_RESOURCE)
+    .add(MESH_SURFACE_SURVEY_RESULTS_RESOURCE);
+
+/**
+ * Model Surface Cache survey, second pass: a thread a brick of each field whose survey the frame
+ * completes, a run a field's bricks, with its table's word, its result and the ticket the host asked
+ * for it under. Each brick takes as many block numbers as its mask has blocks, counted out of its
+ * field's result, and its table word becomes its first number above its mask; brick 0 writes the
+ * ticket beside the count, so a result no pass wrote is told apart. The numbers of a field's bricks
+ * follow the order they are taken in, which nothing reads into.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_surface_number = ComputeShader.from({
+    label: "Mesh Surface Number",
+    resources: number_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${MESH_SDF_BAKE_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let thread = (workgroup_id.y * settings.groups_x + workgroup_id.x) * ${MESH_SDF_BAKE_WORKGROUP_SIZE}u + lane;
+
+    if (thread >= settings.thread_count) {
+        return;
+    }
+
+    // its first thread, its table's word, its result, its ticket
+    let run = mesh_surface_runs[mesh_surface_run_find(settings.run_count, thread)];
+    let number = thread - run.x;
+    let word = run.y + number;
+    let result = ${MESH_SURFACE_SURVEY_RESULT_WORDS}u * run.z;
+
+    let mask = atomicLoad(&mesh_surface_data[word]) & ${(1 << MESH_SURFACE_TABLE_MASK_BITS) - 1}u;
+    let first = atomicAdd(&mesh_surface_survey_results[result + 1u], countOneBits(mask));
+
+    atomicStore(&mesh_surface_data[word], (first << ${MESH_SURFACE_TABLE_MASK_BITS}u) | mask);
+
+    if (number == 0u) {
+        atomicStore(&mesh_surface_survey_results[result], run.w);
+    }
+}
+`, [
+            chunk_mesh_surface_run_find,
+        ]),
+});

package/src/shade/renderer/geometry/sdf/surface/shader_mesh_surface_trace.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Model Surface Cache bake, third pass (`MESH_SURFACE_BAKE.js`): a workgroup a texel the list pass
+ * listed, a thread a ray, dispatched through the command pass's command. All of it in the geometry's
+ * local space, against its own triangles: nothing else of the scene is there to be seen.
+ *
+ * - **The rays** look at the texel's nearest surface point, which the field puts d against n from the
+ *   texel, from {@link MESH_SURFACE_LIFT_VOXELS} out from it along n. They leave along the texel's own
+ *   Fibonacci set of {@link MESH_SURFACE_TEXEL_RAYS} directions over the hemisphere facing the surface
+ *   (`mesh_surface_texel_ray`: turned about n and shifted through its bands by the texel's seed), into
+ *   the geometry's BLAS (`ray_query_blas_nearest`), as far as the texel's tent reaches. A texel so holds the surface as a ray of the GI meets it, from outside the
+ *   field: one in a gap the field closes sees the face the field puts there.
+ * - **A hit** is opaque with probability its opacity (`sample_material_alpha`), as the path tracer
+ *   takes alpha; a transparent one is stepped past, {@link MESH_SURFACE_ALPHA_CONTINUATIONS} times at most.
+ * - **The sample** is the first opaque hit under the tent, weighted by the tent there, and the material
+ *   there (`sample_material_data`): its diffuse albedo, albedo × (1 − metalness), its metalness and
+ *   roughness, and its emissive. A hit the field says the ray met from behind gives no sample: the
+ *   field's normal half a voxel back along the ray says so. The material's textures are read at a
+ *   footprint a voxel of the level across on the triangle (`beam_texture_level`), filtered exactly
+ *   ({@link IndirectTextureFilter.Exact}), since the sample is stored rather than averaged over frames.
+ * - **The fit**: the first thread adds the workgroup's samples into the texel's fit
+ *   (`chunk_surface_material_fit`) and writes its codes into the texel's staging, which the encode
+ *   takes into the cache's blocks. A texel no ray found surface under keeps the list pass's clear: no
+ *   material.
+ *
+ * The draws are seeded by the geometry, the brick and the texel alone: a cache baked again over an
+ * unchanged geometry and material bakes the same codes.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_surface_trace: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_mesh_surface_trace.d.ts.map

package/src/shade/renderer/geometry/sdf/surface/shader_mesh_surface_trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_mesh_surface_trace.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/sdf/surface/shader_mesh_surface_trace.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wCAFU,aAAa,CA2KsE;8BApP/D,kCAAkC"}

package/src/shade/renderer/geometry/sdf/surface/shader_mesh_surface_trace.js

@@ -0,0 +1,261 @@
+import { INDIRECT_MATERIAL_ARRAY_TYPE } from "../../../material/resident/INDIRECT_MATERIAL_ARRAY_TYPE.js";
+import { chunk_beam_texture_level } from "../../../path_tracer/shader/chunk_beam_texture_level.js";
+import { chunk_sample_material_alpha, chunk_sample_material_data } from "../../../path_tracer/shader/chunk_sample_material_data.js";
+import { INDIRECT_TEXTURE_FILTER } from "../../../path_tracer/shader/INDIRECT_TEXTURE_FILTER.js";
+import { IndirectTextureFilter } from "../../../path_tracer/shader/IndirectTextureFilter.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 { MAT4_IDENTITY_DEFINITION } from "../../../shader/chunk/geometry/mat4/MAT4_IDENTITY_DEFINITION.js";
+import { chunk_build_orthonormal_matrix_n } from "../../../shader/chunk/geometry/normal/chunk_build_orthonormal_matrix_n.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_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_random } from "../../../shader/chunk/random/chunk_random.js";
+import { chunk_random_initialize } from "../../../shader/chunk/random/chunk_random_initialize.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ShaderSwitchSet } from "../../../shader/compiler/ShaderSwitchSet.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { mesh_sdf_add_blas_resources } from "../bake/shader_mesh_sdf_classify.js";
+import { chunk_mesh_sdf } from "../chunk_mesh_sdf.js";
+import { chunk_mesh_sdf_normal } from "../chunk_mesh_sdf_normal.js";
+import { chunk_mesh_surface_texel_ray } from "./chunk_mesh_surface_texel_ray.js";
+import { MESH_SDF_BRICK_TEXELS } from "../MESH_SDF.js";
+import {
+    MESH_SDF_ATLAS_RESOURCE,
+    MESH_SDF_HEADERS_RESOURCE,
+    MESH_SDF_INDIRECTION_RESOURCE,
+    MESH_SDF_SAMPLER_RESOURCE
+} from "../MESH_SDF_RESOURCES.js";
+import { chunk_rgbe9995_encode } from "../../../shader/chunk/color/rgbe9995/chunk_rgbe9995_encode.js";
+import { chunk_albedo_compress } from "../../../shader/chunk/material/chunk_albedo_compress.js";
+import { chunk_metal_rough_compress } from "../../../shader/chunk/material/chunk_metal_rough_compress.js";
+import { chunk_surface_material_fit } from "./chunk_surface_material_fit.js";
+import {
+    MESH_SURFACE_ALPHA_CONTINUATIONS,
+    MESH_SURFACE_COUNTER_READ_RESOURCE,
+    MESH_SURFACE_COUNTER_TRACED,
+    MESH_SURFACE_LIFT_VOXELS,
+    MESH_SURFACE_STAGING_WORDS,
+    MESH_SURFACE_STAGING_WRITE_RESOURCE,
+    MESH_SURFACE_TEXEL_RAYS,
+    MESH_SURFACE_TEXEL_STRUCT,
+    MESH_SURFACE_TEXELS_READ_RESOURCE
+} from "./MESH_SURFACE_BAKE.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .add(MESH_SDF_HEADERS_RESOURCE)
+    .add(MESH_SDF_INDIRECTION_RESOURCE)
+    .add(MESH_SDF_ATLAS_RESOURCE)
+    .add(MESH_SDF_SAMPLER_RESOURCE)
+    .add(MESH_SURFACE_TEXELS_READ_RESOURCE)
+    .add(MESH_SURFACE_COUNTER_READ_RESOURCE)
+    .add(MESH_SURFACE_STAGING_WRITE_RESOURCE);
+
+resources.createGroup({ label: "materials" })
+    .addUniform("materials", INDIRECT_MATERIAL_ARRAY_TYPE)
+    .addTexture("textures", "unfilterable-float", "2d-array", false);
+
+mesh_sdf_add_blas_resources(resources.createGroup());
+
+/**
+ * Model Surface Cache bake, third pass (`MESH_SURFACE_BAKE.js`): a workgroup a texel the list pass
+ * listed, a thread a ray, dispatched through the command pass's command. All of it in the geometry's
+ * local space, against its own triangles: nothing else of the scene is there to be seen.
+ *
+ * - **The rays** look at the texel's nearest surface point, which the field puts d against n from the
+ *   texel, from {@link MESH_SURFACE_LIFT_VOXELS} out from it along n. They leave along the texel's own
+ *   Fibonacci set of {@link MESH_SURFACE_TEXEL_RAYS} directions over the hemisphere facing the surface
+ *   (`mesh_surface_texel_ray`: turned about n and shifted through its bands by the texel's seed), into
+ *   the geometry's BLAS (`ray_query_blas_nearest`), as far as the texel's tent reaches. A texel so holds the surface as a ray of the GI meets it, from outside the
+ *   field: one in a gap the field closes sees the face the field puts there.
+ * - **A hit** is opaque with probability its opacity (`sample_material_alpha`), as the path tracer
+ *   takes alpha; a transparent one is stepped past, {@link MESH_SURFACE_ALPHA_CONTINUATIONS} times at most.
+ * - **The sample** is the first opaque hit under the tent, weighted by the tent there, and the material
+ *   there (`sample_material_data`): its diffuse albedo, albedo × (1 − metalness), its metalness and
+ *   roughness, and its emissive. A hit the field says the ray met from behind gives no sample: the
+ *   field's normal half a voxel back along the ray says so. The material's textures are read at a
+ *   footprint a voxel of the level across on the triangle (`beam_texture_level`), filtered exactly
+ *   ({@link IndirectTextureFilter.Exact}), since the sample is stored rather than averaged over frames.
+ * - **The fit**: the first thread adds the workgroup's samples into the texel's fit
+ *   (`chunk_surface_material_fit`) and writes its codes into the texel's staging, which the encode
+ *   takes into the cache's blocks. A texel no ray found surface under keeps the list pass's clear: no
+ *   material.
+ *
+ * The draws are seeded by the geometry, the brick and the texel alone: a cache baked again over an
+ * unchanged geometry and material bakes the same codes.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_surface_trace = ComputeShader.from({
+    label: "Mesh Surface Trace",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+var<workgroup> traced_count: u32;
+
+/** a ray's sample's weight, 0 for no sample */
+var<workgroup> sample_weight: array<f32, ${MESH_SURFACE_TEXEL_RAYS}>;
+/** diffuse albedo and metalness */
+var<workgroup> sample_albedo: array<vec4<f32>, ${MESH_SURFACE_TEXEL_RAYS}>;
+/** emissive and roughness */
+var<workgroup> sample_emissive: array<vec4<f32>, ${MESH_SURFACE_TEXEL_RAYS}>;
+
+fn mesh_surface_tent(d: vec3<f32>) -> f32 {
+    let w = max(vec3<f32>(0.0), vec3<f32>(1.0) - abs(d));
+
+    return w.x * w.y * w.z;
+}
+
+@compute @workgroup_size(${MESH_SURFACE_TEXEL_RAYS})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) ray_index: u32,
+) {
+    let listed = folded_workgroup_index(workgroup_id);
+
+    if (ray_index == 0u) {
+        traced_count = mesh_surface_counter[${MESH_SURFACE_COUNTER_TRACED}u];
+    }
+
+    if (listed >= workgroupUniformLoad(&traced_count)) {
+        return;
+    }
+
+    let entry = mesh_surface_texels[listed];
+    let header = mesh_sdf_headers[entry.geometry];
+    let brick = mesh_sdf_brick_of(header, entry.brick);
+    let voxel = mesh_sdf_level_voxel(header, brick.x);
+
+    let s = ${MESH_SDF_BRICK_TEXELS}u;
+    let t = vec3<u32>(entry.texel % s, (entry.texel / s) % s, entry.texel / (s * s));
+    let texel = mesh_sdf_brick_corner(header, brick) + vec3<f32>(t) * voxel;
+
+    // the texel's nearest surface point, d against n, and how far out from it the rays leave
+    let d = mesh_sdf_sample(header, brick.x, texel);
+    let n = mesh_sdf_normal(header, brick.x, texel);
+    let lift = ${MESH_SURFACE_LIFT_VOXELS} * voxel - d;
+
+    // the texel's own set of directions, then each ray's own draws
+    let seed = vec3<u32>(entry.geometry, entry.brick, entry.texel);
+    let direction = mesh_surface_texel_ray(seed, ray_index, n);
+
+    random_initialize(seed, vec3<u32>(ray_index + 1u, 1u, 0u));
+
+    var ray: ${RAY_STRUCT.wgsl_ref};
+
+    ray.origin = texel + lift * n;
+    ray.direction = direction;
+    ray.tmax = abs(lift) + ${Math.sqrt(3).toFixed(6)} * voxel;
+
+    let material = materials[entry.material];
+
+    var stack: array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>;
+
+    var weight = 0.0;
+    var albedo = vec4<f32>(0.0);
+    var emissive = vec4<f32>(0.0);
+
+    for (var step = 0u; step <= ${MESH_SURFACE_ALPHA_CONTINUATIONS}u; step++) {
+        let hit = ray_query_blas_nearest(ray, entry.geometry, &stack, 0u);
+
+        if (hit.t < 0.0) {
+            break;
+        }
+
+        let triangle = geometry_read_triangle_vertices(geometries[entry.geometry], hit.triangle);
+        let lambda = vec3<f32>(1.0 - hit.barycentrics.x - hit.barycentrics.y, hit.barycentrics.x, hit.barycentrics.y);
+
+        // a footprint a voxel of the level across on the triangle, whatever angle the ray came in at
+        let facing = normalize(cross(triangle.b.position - triangle.a.position, triangle.c.position - triangle.a.position));
+        let in_plane = build_orthonormal_matrix_n(facing);
+        let level = beam_texture_level(triangle, facing, in_plane[0] * voxel, in_plane[1] * voxel);
+
+        if (random() < sample_material_alpha(material, triangle, lambda, MAT4_IDENTITY, ray.direction, level).opacity) {
+            let local = ray.origin + hit.t * ray.direction;
+            let w = mesh_surface_tent((local - texel) / voxel);
+
+            if (w > 0.0) {
+                // the field's normal on the ray's side, where a ray of the GI on this path would stand
+                let field = mesh_sdf_normal(header, brick.x, local - ${MESH_SURFACE_LIFT_VOXELS} * voxel * ray.direction);
+
+                // a surface met from behind, from inside a solid, is one the GI never shades
+                if (dot(field, ray.direction) < 0.0) {
+                    let data = sample_material_data(ray, material, triangle, lambda, MAT4_IDENTITY, level);
+
+                    weight = w;
+                    albedo = vec4<f32>(data.albedo * (1.0 - data.metalness), data.metalness);
+                    emissive = vec4<f32>(data.emissive, data.roughness);
+                }
+            }
+
+            break;
+        }
+
+        // past the transparent hit, by a sliver of a voxel
+        let skip = hit.t + 1e-3 * voxel;
+
+        ray.origin += ray.direction * skip;
+        ray.tmax -= skip;
+
+        if (ray.tmax <= 0.0) {
+            break;
+        }
+    }
+
+    sample_weight[ray_index] = weight;
+    sample_albedo[ray_index] = albedo;
+    sample_emissive[ray_index] = emissive;
+
+    workgroupBarrier();
+
+    if (ray_index == 0u) {
+        var fit: SurfaceMaterialFit;
+
+        for (var i = 0u; i < ${MESH_SURFACE_TEXEL_RAYS}u; i++) {
+            let w = sample_weight[i];
+
+            if (w > 0.0) {
+                let a = sample_albedo[i];
+                let e = sample_emissive[i];
+
+                surface_material_fit_add(&fit, w, a.rgb, vec2<f32>(a.a, e.a), e.rgb);
+            }
+        }
+
+        let fitted = surface_material_fit_solve(fit);
+
+        if (fitted.covered) {
+            let at = ${MESH_SURFACE_STAGING_WORDS}u * entry.slot;
+
+            mesh_surface_staging[at] = albedo_compress(fitted.albedo);
+            mesh_surface_staging[at + 1u] = metal_rough_compress(fitted.metal_rough);
+            mesh_surface_staging[at + 2u] = rgbe9995_encode(fitted.emissive);
+        }
+    }
+}
+`, [
+            RAY_STRUCT.declaration_chunk,
+            MESH_SURFACE_TEXEL_STRUCT.declaration_chunk,
+            MAT4_IDENTITY_DEFINITION,
+            chunk_folded_workgroup_index,
+            chunk_mesh_sdf,
+            chunk_mesh_sdf_normal,
+            chunk_surface_material_fit,
+            chunk_albedo_compress,
+            chunk_metal_rough_compress,
+            chunk_rgbe9995_encode,
+            chunk_random,
+            chunk_random_initialize,
+            chunk_mesh_surface_texel_ray,
+            chunk_ray_query_blas_nearest,
+            chunk_geometry_read_triangle_vertices,
+            chunk_build_orthonormal_matrix_n,
+            chunk_beam_texture_level,
+            chunk_sample_material_alpha,
+            chunk_sample_material_data,
+        ]),
+}).variant(ShaderSwitchSet.EMPTY.with(INDIRECT_TEXTURE_FILTER, IndirectTextureFilter.Exact));

package/src/shade/renderer/geometry/virtual/runtime/VirtualGeometry.d.ts

@@ -37,8 +37,8 @@ export class VirtualGeometry extends MeshletGeometry {
      */
     vg_row: number;
     /**
-     * An ordinary geometry standing in for this one where a plain mesh is needed: what its geometry cache is baked
-     * from and its cards are drawn from. A cut of the container ({@link vgeo_to_proxy_mesh}) at
+     * An ordinary geometry standing in for this one where a plain mesh is needed: what its geometry cache and
+     * surface caches are baked from. A cut of the container ({@link vgeo_to_proxy_mesh}) at
      * {@link vgeo_proxy_triangle_limit} of the source's triangles, in the geometry's own space, with its attributes;
      * asked for once, and the same proxy every time after.
      *

package/src/shade/renderer/geometry/virtual/runtime/VirtualGeometry.js

@@ -74,8 +74,8 @@ export class VirtualGeometry extends MeshletGeometry {
     }
 
     /**
-     * An ordinary geometry standing in for this one where a plain mesh is needed: what its geometry cache is baked
-     * from and its cards are drawn from. A cut of the container ({@link vgeo_to_proxy_mesh}) at
+     * An ordinary geometry standing in for this one where a plain mesh is needed: what its geometry cache and
+     * surface caches are baked from. A cut of the container ({@link vgeo_to_proxy_mesh}) at
      * {@link vgeo_proxy_triangle_limit} of the source's triangles, in the geometry's own space, with its attributes;
      * asked for once, and the same proxy every time after.
      *

package/src/shade/renderer/geometry/virtual/sdf/VGeoSDFProxies.d.ts

@@ -1,16 +1,16 @@
 /**
- * The geometry caches and cards of virtual geometry (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8, §17).
- * {@link GPUGeometrySDFManager} bakes a geometry's field from its tree and captures its cards through its meshlets, and
- * a virtual geometry has neither.
+ * The geometry caches and surface caches of virtual geometry (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8, §17).
+ * {@link GPUGeometrySDFManager} bakes a geometry's field and its surface caches from its tree, and a virtual geometry
+ * has none.
  *
  * Each virtual geometry whose cache is asked for gets its proxy ({@link VirtualGeometry#get_proxy}): an ordinary
  * geometry in the same local space, with its attributes. The proxy is added to the geometry manager and the virtual
  * geometry aliased to it ({@link GPUGeometrySDFManager#alias}). From there the proxy is any geometry: the virtual
- * geometry's holders hold its cache, baked from its tree, and the virtual geometry's card sets capture its layout,
- * drawn through its meshlets with the virtual geometry's own materials.
+ * geometry's holders hold its cache, baked from its tree, and the virtual geometry's surface caches follow its field,
+ * baked from its triangles with the virtual geometry's own materials.
  *
  * **The proxy's detail is its own**, not the cache's voxel's: a proxy coarser than the voxel bakes a coarser field and
- * coarser cards than the asset would. A known discrepancy, kept: a hit on virtual geometry has a material at all.
+ * coarser surface caches than the asset would. A known discrepancy, kept: a hit on virtual geometry has a material at all.
  *
  * A proxy is applied as it arrives, which is between frames: adding a geometry grows the geometry manager's buffers,
  * which a frame's passes must not find replaced under them. A virtual geometry the geometry manager lets go takes its

package/src/shade/renderer/geometry/virtual/sdf/VGeoSDFProxies.js

@@ -21,18 +21,18 @@ class VGeoProxyEntry {
 }
 
 /**
- * The geometry caches and cards of virtual geometry (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8, §17).
- * {@link GPUGeometrySDFManager} bakes a geometry's field from its tree and captures its cards through its meshlets, and
- * a virtual geometry has neither.
+ * The geometry caches and surface caches of virtual geometry (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8, §17).
+ * {@link GPUGeometrySDFManager} bakes a geometry's field and its surface caches from its tree, and a virtual geometry
+ * has none.
  *
  * Each virtual geometry whose cache is asked for gets its proxy ({@link VirtualGeometry#get_proxy}): an ordinary
  * geometry in the same local space, with its attributes. The proxy is added to the geometry manager and the virtual
  * geometry aliased to it ({@link GPUGeometrySDFManager#alias}). From there the proxy is any geometry: the virtual
- * geometry's holders hold its cache, baked from its tree, and the virtual geometry's card sets capture its layout,
- * drawn through its meshlets with the virtual geometry's own materials.
+ * geometry's holders hold its cache, baked from its tree, and the virtual geometry's surface caches follow its field,
+ * baked from its triangles with the virtual geometry's own materials.
  *
  * **The proxy's detail is its own**, not the cache's voxel's: a proxy coarser than the voxel bakes a coarser field and
- * coarser cards than the asset would. A known discrepancy, kept: a hit on virtual geometry has a material at all.
+ * coarser surface caches than the asset would. A known discrepancy, kept: a hit on virtual geometry has a material at all.
  *
  * A proxy is applied as it arrives, which is between frames: adding a geometry grows the geometry manager's buffers,
  * which a frame's passes must not find replaced under them. A virtual geometry the geometry manager lets go takes its
@@ -133,7 +133,7 @@ export class VGeoSDFProxies {
                     this.#asked.delete(record.index);
                     this.#failed_count++;
 
-                    console.warn('vgeo: no proxy, the geometry has no cache or cards', error);
+                    console.warn('vgeo: no proxy, the geometry has no cache or surface caches', error);
                 }
             }
         );