@woosh/meep-engine 3.61.3 → 3.62.0

package/src/shade/renderer/rasterize/visibility/VISIBILITY_BUFFER.js

@@ -0,0 +1,45 @@
+import { MESHLET_DEFINITION_STRUCT } from "../../geometry/meshlet/encoding/MESHLET_DEFINITION_STRUCT.js";
+import { MESHLET_COLLECTION_STRUCT } from "../MESHLET_COLLECTION_STRUCT.js";
+
+/**
+ * The visibility buffer's format: one `u32` a pixel, `slot << VISIBILITY_TRIANGLE_BITS | triangle`. `slot` is
+ * the pixel's meshlet's place in the frame's visible-meshlet table, which says the meshlet and the mesh row
+ * it was drawn for (`chunk_visibility_decode`); `triangle` is the triangle within that meshlet.
+ *
+ * @type {GPUTextureFormat}
+ */
+export const VISIBILITY_FORMAT = 'r32uint';
+
+/**
+ * Bits of a visibility word that hold the triangle within its meshlet, below the slot.
+ *
+ * @type {number}
+ */
+export const VISIBILITY_TRIANGLE_BITS = 8;
+
+/**
+ * How many slots the visible-meshlet table can hold: every value the bits above the triangle reach, less
+ * the last, which {@link VISIBILITY_NONE} takes.
+ *
+ * @type {number}
+ */
+export const VISIBLE_MESHLET_SLOT_LIMIT = 2 ** (32 - VISIBILITY_TRIANGLE_BITS) - 1;
+
+/**
+ * What a pixel no surface covers holds, and what the visibility buffer is cleared to: the first word of the
+ * slot past every slot the table can hold. A 32-bit float holds it exactly, as a clear value has to be —
+ * `RenderPassColorAttachmentDescriptor` keeps one in a `Float32Array`, where every bit set would round up
+ * to 2^32.
+ *
+ * @type {number}
+ */
+export const VISIBILITY_NONE = VISIBLE_MESHLET_SLOT_LIMIT * 2 ** VISIBILITY_TRIANGLE_BITS;
+
+/**
+ * Where the table's elements start, counted in meshlet definitions from the start of its buffer. The table
+ * is a meshlet collection, a count before the elements; a pass that binds the whole buffer as a bare array
+ * of definitions — as the alpha-tested raster binds its lists — finds slot `s` at `s` plus this.
+ *
+ * @type {number}
+ */
+export const VISIBLE_MESHLETS_ARRAY_OFFSET = MESHLET_COLLECTION_STRUCT.get('elements').offset / MESHLET_DEFINITION_STRUCT.size;

package/src/shade/renderer/rasterize/visibility/chunk_visibility_decode.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The frame's visible-meshlet table: every meshlet the view's raster drew into the visibility buffer, at
+ * the slot its pixels name. A meshlet collection, read-only to the passes that resolve pixels through it.
+ *
+ * @type {ShaderResourceDescriptor}
+ */
+export const VISIBLE_MESHLETS_RESOURCE: ShaderResourceDescriptor;
+/**
+ * What a visibility word says of its pixel ({@link VISIBILITY_FORMAT}): the scene row of the mesh, the
+ * meshlet (a global meshlet index) and the triangle within it, through the frame's visible-meshlet table,
+ * bound as `visible_meshlets`.
+ *
+ * ```wgsl
+ * const VISIBILITY_NONE: u32
+ * struct VisibilityTexel { mesh: u32, meshlet: u32, triangle: u32 }
+ * fn visibility_decode(encoded: u32) -> VisibilityTexel
+ * ```
+ *
+ * Only for a word that is not `VISIBILITY_NONE`, which no surface covers.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_visibility_decode: CodeChunk;
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_visibility_decode.d.ts.map

package/src/shade/renderer/rasterize/visibility/chunk_visibility_decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_visibility_decode.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/visibility/chunk_visibility_decode.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,wCAFU,wBAAwB,CAE6F;AAE/H;;;;;;;;;;;;;;GAcG;AACH,sCAFU,SAAS,CAmBjB;yCA5CuC,mDAAmD;0BADlE,oCAAoC"}

package/src/shade/renderer/rasterize/visibility/chunk_visibility_decode.js

@@ -0,0 +1,48 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { MESHLET_COLLECTION_STRUCT } from "../MESHLET_COLLECTION_STRUCT.js";
+import { VISIBILITY_NONE, VISIBILITY_TRIANGLE_BITS } from "./VISIBILITY_BUFFER.js";
+
+/**
+ * The frame's visible-meshlet table: every meshlet the view's raster drew into the visibility buffer, at
+ * the slot its pixels name. A meshlet collection, read-only to the passes that resolve pixels through it.
+ *
+ * @type {ShaderResourceDescriptor}
+ */
+export const VISIBLE_MESHLETS_RESOURCE = ShaderResourceDescriptor.storageBuffer("visible_meshlets", MESHLET_COLLECTION_STRUCT);
+
+/**
+ * What a visibility word says of its pixel ({@link VISIBILITY_FORMAT}): the scene row of the mesh, the
+ * meshlet (a global meshlet index) and the triangle within it, through the frame's visible-meshlet table,
+ * bound as `visible_meshlets`.
+ *
+ * ```wgsl
+ * const VISIBILITY_NONE: u32
+ * struct VisibilityTexel { mesh: u32, meshlet: u32, triangle: u32 }
+ * fn visibility_decode(encoded: u32) -> VisibilityTexel
+ * ```
+ *
+ * Only for a word that is not `VISIBILITY_NONE`, which no surface covers.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_visibility_decode = CodeChunk.from(
+    //language=WGSL
+    `
+const VISIBILITY_NONE: u32 = ${VISIBILITY_NONE}u;
+
+struct VisibilityTexel {
+    mesh: u32,
+    meshlet: u32,
+    triangle: u32,
+}
+
+fn visibility_decode(encoded: u32) -> VisibilityTexel {
+    let meshlet = visible_meshlets.elements[encoded >> ${VISIBILITY_TRIANGLE_BITS}u];
+
+    return VisibilityTexel(meshlet.mesh, meshlet.index, encoded & ${2 ** VISIBILITY_TRIANGLE_BITS - 1}u);
+}
+`
+);
+
+chunk_visibility_decode.requireResource(VISIBLE_MESHLETS_RESOURCE);

package/src/shade/renderer/rasterize/visibility/shader_visible_meshlets_append.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Reserve the slots of one list in the visible-meshlet table and write the commands that use them: `draw`
+ * draws the list's meshlets from the table, `instanceCount` of them from `firstInstance`, its first slot;
+ * `copy` dispatches {@link shader_visible_meshlets_copy} over them, one invocation a meshlet.
+ *
+ * The table's count is every slot asked for, as a meshlet collection's count is: a list past the table's
+ * end draws only what fits, and the count tells the collection limits how far to grow it.
+ *
+ * One invocation.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_visible_meshlets_reserve: ComputeShader;
+/**
+ * Copy a list's reserved meshlets into the visible-meshlet table, at the slots `draw` holds
+ * ({@link shader_visible_meshlets_reserve}). Dispatched indirectly by its `copy` command.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_visible_meshlets_copy: ComputeShader;
+/**
+ * {@link shader_visible_meshlets_copy} for a list kept as a bare array whose count is held elsewhere — the
+ * alpha-tested raster's, sorted by material, whose collection the reserve counts.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_visible_meshlets_copy_array: ComputeShader;
+/**
+ * Move per-material draw commands over a sorted list onto the list's copy in the visible-meshlet table:
+ * each command's range of the list becomes the same range of the slots `draw` holds, cut to the slots the
+ * copy filled. The draws bind the table's whole buffer as a bare array of definitions, which puts slot `s`
+ * at `s + ${VISIBLE_MESHLETS_ARRAY_OFFSET}` ({@link VISIBLE_MESHLETS_ARRAY_OFFSET}).
+ *
+ * One invocation a command.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_visible_meshlets_offset_commands: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_visible_meshlets_append.d.ts.map

package/src/shade/renderer/rasterize/visibility/shader_visible_meshlets_append.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_visible_meshlets_append.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/rasterize/visibility/shader_visible_meshlets_append.js"],"names":[],"mappings":"AA4BA;;;;;;;;;;;GAWG;AACH,8CAFU,aAAa,CA8BpB;AAmCH;;;;;GAKG;AACH,2CAFU,aAAa,CAMpB;AASH;;;;;GAKG;AACH,iDAFU,aAAa,CAMpB;AAQH;;;;;;;;;GASG;AACH,sDAFU,aAAa,CAuBpB;8BAnK2B,+BAA+B"}

package/src/shade/renderer/rasterize/visibility/shader_visible_meshlets_append.js

@@ -0,0 +1,172 @@
+import { GEOMETRY_MESHLET_TRIANGLE_LIMIT } from "../../geometry/meshlet/GEOMETRY_MESHLET_TRIANGLE_LIMIT.js";
+import { MESHLET_DEFINITION_STRUCT } from "../../geometry/meshlet/encoding/MESHLET_DEFINITION_STRUCT.js";
+import { chunk_folded_dispatch } from "../../gpu_primitive/indirect/chunk_folded_dispatch.js";
+import { STRUCT_DISPATCH_COMPUTE_COMMAND } from "../../gpu_primitive/indirect/STRUCT_DISPATCH_COMPUTE_COMMAND.js";
+import { STRUCT_UNINDEXED_DRAW_COMMAND } from "../../gpu_primitive/indirect/STRUCT_UNINDEXED_DRAW_COMMAND.js";
+import { chunk_folded_workgroup_index } from "../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { MESHLET_COLLECTION_STRUCT } from "../MESHLET_COLLECTION_STRUCT.js";
+import { VISIBLE_MESHLET_SLOT_LIMIT, VISIBLE_MESHLETS_ARRAY_OFFSET } from "./VISIBILITY_BUFFER.js";
+
+/*
+ A draw into the visibility buffer takes its meshlets from the frame's visible-meshlet table, so that the
+ slot its pixels write names the meshlet for every later reader. Before each such draw its list is
+ appended to the table: one invocation reserves the slots, then the copy runs over the list.
+*/
+
+const reserve_resources = new ShaderResourceSetDescriptor();
+
+reserve_resources.createGroup()
+    .addStorageBuffer("input", MESHLET_COLLECTION_STRUCT)
+    .addStorageBuffer("visible_meshlets", MESHLET_COLLECTION_STRUCT, true)
+    .addStorageBuffer("draw", STRUCT_UNINDEXED_DRAW_COMMAND, true)
+    .addStorageBuffer("copy", STRUCT_DISPATCH_COMPUTE_COMMAND, true);
+
+/**
+ * Reserve the slots of one list in the visible-meshlet table and write the commands that use them: `draw`
+ * draws the list's meshlets from the table, `instanceCount` of them from `firstInstance`, its first slot;
+ * `copy` dispatches {@link shader_visible_meshlets_copy} over them, one invocation a meshlet.
+ *
+ * The table's count is every slot asked for, as a meshlet collection's count is: a list past the table's
+ * end draws only what fits, and the count tells the collection limits how far to grow it.
+ *
+ * One invocation.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_visible_meshlets_reserve = ComputeShader.from({
+    label: "Visible meshlets / reserve",
+    resources: reserve_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(1)
+fn main() {
+    let count = min(input.count, arrayLength(&input.elements));
+
+    let base = visible_meshlets.count;
+    let capacity = min(arrayLength(&visible_meshlets.elements), ${VISIBLE_MESHLET_SLOT_LIMIT}u);
+    let stored = select(0u, min(count, capacity - base), base < capacity);
+
+    visible_meshlets.count = base + count;
+
+    draw.vertexCount = ${GEOMETRY_MESHLET_TRIANGLE_LIMIT * 3}u;
+    draw.instanceCount = stored;
+    draw.firstVertex = 0u;
+    draw.firstInstance = base;
+
+    let groups = folded_dispatch((stored + ${COMPUTE_SHADER_DEFAULT_GROUP_SIZE - 1}u) / ${COMPUTE_SHADER_DEFAULT_GROUP_SIZE}u);
+
+    copy.workgroupCountX = groups.x;
+    copy.workgroupCountY = groups.y;
+    copy.workgroupCountZ = groups.z;
+}
+`, [chunk_folded_dispatch])
+});
+
+/**
+ * The copy kernels' body: `source(i)` is the list's `i`-th meshlet.
+ *
+ * @param {string} source
+ * @returns {CodeChunk}
+ */
+function copy_body(source) {
+    return CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${COMPUTE_SHADER_DEFAULT_GROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) local_index: u32,
+) {
+    let i = folded_workgroup_index(workgroup_id) * ${COMPUTE_SHADER_DEFAULT_GROUP_SIZE}u + local_index;
+
+    if (i >= draw.instanceCount) {
+        return;
+    }
+
+    visible_meshlets.elements[draw.firstInstance + i] = ${source};
+}
+`, [chunk_folded_workgroup_index]);
+}
+
+const copy_resources = new ShaderResourceSetDescriptor();
+
+copy_resources.createGroup()
+    .addStorageBuffer("draw", STRUCT_UNINDEXED_DRAW_COMMAND)
+    .addStorageBuffer("input", MESHLET_COLLECTION_STRUCT)
+    .addStorageBuffer("visible_meshlets", MESHLET_COLLECTION_STRUCT, true);
+
+/**
+ * Copy a list's reserved meshlets into the visible-meshlet table, at the slots `draw` holds
+ * ({@link shader_visible_meshlets_reserve}). Dispatched indirectly by its `copy` command.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_visible_meshlets_copy = ComputeShader.from({
+    label: "Visible meshlets / copy",
+    resources: copy_resources,
+    body: copy_body("input.elements[i]"),
+});
+
+const copy_array_resources = new ShaderResourceSetDescriptor();
+
+copy_array_resources.createGroup()
+    .addStorageBuffer("draw", STRUCT_UNINDEXED_DRAW_COMMAND)
+    .addStorageBuffer("input", WebGPUArray.from(MESHLET_DEFINITION_STRUCT))
+    .addStorageBuffer("visible_meshlets", MESHLET_COLLECTION_STRUCT, true);
+
+/**
+ * {@link shader_visible_meshlets_copy} for a list kept as a bare array whose count is held elsewhere — the
+ * alpha-tested raster's, sorted by material, whose collection the reserve counts.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_visible_meshlets_copy_array = ComputeShader.from({
+    label: "Visible meshlets / copy",
+    resources: copy_array_resources,
+    body: copy_body("input[i]"),
+});
+
+const offset_resources = new ShaderResourceSetDescriptor();
+
+offset_resources.createGroup()
+    .addStorageBuffer("draw", STRUCT_UNINDEXED_DRAW_COMMAND)
+    .addStorageBuffer("commands", WebGPUArray.from(STRUCT_UNINDEXED_DRAW_COMMAND), true);
+
+/**
+ * Move per-material draw commands over a sorted list onto the list's copy in the visible-meshlet table:
+ * each command's range of the list becomes the same range of the slots `draw` holds, cut to the slots the
+ * copy filled. The draws bind the table's whole buffer as a bare array of definitions, which puts slot `s`
+ * at `s + ${VISIBLE_MESHLETS_ARRAY_OFFSET}` ({@link VISIBLE_MESHLETS_ARRAY_OFFSET}).
+ *
+ * One invocation a command.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_visible_meshlets_offset_commands = ComputeShader.from({
+    label: "Visible meshlets / offset draw commands",
+    resources: offset_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${COMPUTE_SHADER_DEFAULT_GROUP_SIZE})
+fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let k = global_id.x;
+
+    if (k >= arrayLength(&commands)) {
+        return;
+    }
+
+    let start = commands[k].firstInstance;
+    let end = min(start + commands[k].instanceCount, draw.instanceCount);
+
+    commands[k].instanceCount = select(0u, end - start, start < end);
+    commands[k].firstInstance = draw.firstInstance + start + ${VISIBLE_MESHLETS_ARRAY_OFFSET}u;
+}
+`)
+});

package/src/shade/renderer/restir/di/chunk_restir_reconstruct_surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_restir_reconstruct_surface.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/restir/di/chunk_restir_reconstruct_surface.js"],"names":[],"mappings":"AAWA;;;;;;;;;;GAUG;AACH,+CAFU,SAAS,CAqDjB;0BAhEwB,oCAAoC"}
+{"version":3,"file":"chunk_restir_reconstruct_surface.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/restir/di/chunk_restir_reconstruct_surface.js"],"names":[],"mappings":"AAcA;;;;;;;;;;GAUG;AACH,+CAFU,SAAS,CAoDjB;0BA/DwB,oCAAoC"}

package/src/shade/renderer/restir/di/chunk_restir_reconstruct_surface.js

@@ -4,6 +4,9 @@ import { chunk_project_position_from_depth } from "../../shader/chunk/camera/chu
 import { chunk_get_view_space_depth } from "../../shader/chunk/depth/chunk_get_view_space_depth.js";
 import { chunk_mat4_extract_position } from "../../shader/chunk/geometry/mat4/chunk_mat4_extract_position.js";
 import { chunk_decode_g_buffer_normal } from "../../shader/chunk/geometry/normal/chunk_decode_g_buffer_normal.js";
+import {
+    chunk_decode_g_buffer_face_normal
+} from "../../shader/chunk/geometry/normal/chunk_decode_g_buffer_face_normal.js";
 import { GEOMETRIC_SHADING_INFO_STRUCT } from "../../shader/chunk/material/GEOMETRIC_SHADING_INFO_STRUCT.js";
 import { MATERIAL_SHADING_INFO_STRUCT } from "../../shader/chunk/material/MATERIAL_SHADING_INFO_STRUCT.js";
 import { chunk_texel_coordinate_to_uv } from "../../shader/chunk/texture/chunk_texel_coordinate_to_uv.js";
@@ -47,11 +50,9 @@ fn restir_reconstruct_surface(i_coord: vec2<u32>, texture_size: vec2<u32>) -> Re
     let camera_position_ws = mat4_extract_position(camera.transform);
     let view_direction = normalize(camera_position_ws - position_ws);
 
-    let g_buffer_sample_normal = textureLoad(gBufferNormal, i_coord, 0);
-
     surface.geometry = ${GEOMETRIC_SHADING_INFO_STRUCT.wgsl_ref}(
-        decode_g_buffer_normal(g_buffer_sample_normal.xy),
-        decode_g_buffer_normal(g_buffer_sample_normal.zw),
+        decode_g_buffer_normal(textureLoad(gBufferNormal, i_coord, 0).x),
+        decode_g_buffer_face_normal(textureLoad(gBufferPBR, i_coord, 0)),
         position_ws,
         view_direction,
     );
@@ -69,6 +70,7 @@ fn restir_reconstruct_surface(i_coord: vec2<u32>, texture_size: vec2<u32>) -> Re
         chunk_project_position_from_depth,
         chunk_mat4_extract_position,
         chunk_decode_g_buffer_normal,
+        chunk_decode_g_buffer_face_normal,
         chunk_read_gBuffer_material,
     ]
 );

package/src/shade/renderer/restir/di/chunk_restir_spatial_reuse.js

@@ -81,7 +81,7 @@ fn restir_spatial_reuse(
         if (abs(neighbour_view_depth - self_view_depth) > RESTIR_SPATIAL_DEPTH_TOLERANCE * self_view_depth) {
             continue;
         }
-        let neighbour_normal = decode_g_buffer_normal(textureLoad(gBufferNormal, neighbour_u, 0).xy);
+        let neighbour_normal = decode_g_buffer_normal(textureLoad(gBufferNormal, neighbour_u, 0).x);
         if (dot(neighbour_normal, geometry.shading_normal) < RESTIR_SPATIAL_NORMAL_TOLERANCE) {
             continue;
         }

package/src/shade/renderer/restir/di/shader_restir_di_denoise.js

@@ -76,7 +76,7 @@ fn main(
     }
 
     let center_depth = get_view_space_depth(center_device_depth, camera);
-    let center_normal = decode_g_buffer_normal(textureLoad(gBufferNormal, i_coord, 0).xy);
+    let center_normal = decode_g_buffer_normal(textureLoad(gBufferNormal, i_coord, 0).x);
     let center_luma = rgb_to_luminance(center_radiance);
 
     let step = i32(step_size);
@@ -107,7 +107,7 @@ fn main(
 
         let sample_radiance = textureLoad(tInput, p, 0).rgb;
         let sample_depth = get_view_space_depth(sample_device_depth, camera);
-        let sample_normal = decode_g_buffer_normal(textureLoad(gBufferNormal, p, 0).xy);
+        let sample_normal = decode_g_buffer_normal(textureLoad(gBufferNormal, p, 0).x);
         let sample_luma = rgb_to_luminance(sample_radiance);
 
         let w_normal = normal_edge_stopping_weight(center_normal, sample_normal, PHI_NORMAL);

package/src/shade/renderer/shader/chunk/color/sRGB/chunk_sRGBTransferEOTF.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Electro-optical transfer function (EOTF), the inverse of {@link chunk_sRGBTransferOETF}
+ *
+ * sRGB to sRGB-linear, the IEC 61966-2-1 curve an `-srgb` texture format decodes with.
+ * @see convert_channel_sRGB_to_linear the JS twin, which carries the same constants
+ */
+export const chunk_sRGBTransferEOTF: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sRGBTransferEOTF.d.ts.map

package/src/shade/renderer/shader/chunk/color/sRGB/chunk_sRGBTransferEOTF.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sRGBTransferEOTF.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/color/sRGB/chunk_sRGBTransferEOTF.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,+CASG;0BAjBuB,gCAAgC"}

package/src/shade/renderer/shader/chunk/color/sRGB/chunk_sRGBTransferEOTF.js

@@ -0,0 +1,18 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * Electro-optical transfer function (EOTF), the inverse of {@link chunk_sRGBTransferOETF}
+ *
+ * sRGB to sRGB-linear, the IEC 61966-2-1 curve an `-srgb` texture format decodes with.
+ * @see convert_channel_sRGB_to_linear the JS twin, which carries the same constants
+ */
+export const chunk_sRGBTransferEOTF = CodeChunk.from(
+//language=WGSL
+    `
+fn sRGBTransferEOTF( value: vec3<f32> ) -> vec3<f32> {
+    let low = value * 0.0773993808;
+    let high = pow( value * 0.9478672986 + vec3( 0.0521327014 ), vec3( 2.4 ) );
+
+    return select( low, high, value >= vec3( 0.04045 ) );
+}
+`);

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_determinant.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Determinant of a 3×3 as the triple product of its columns, `dot(m[0], cross(m[1], m[2]))`. Same
+ * expression as {@link m4_linear_determinant}, the CPU twin of `mat4_linear_determinant`, which
+ * reads it through this.
+ *
+ * Written out rather than left to WGSL's `determinant`. The specification gives that builtin no
+ * accuracy at all ("Infinite ULP"), each backend expands it its own way, and no CPU model can stand
+ * in for it. This expression's accuracy is what `dot` and `cross` inherit from their operations. It
+ * is exactly zero for a column of zeros at any rotation, because every term of the expansion
+ * carries a factor from that column, even where the backend fuses the products.
+ *
+ * A caller dividing by a determinant tests that very number, not another expansion of it. Two
+ * expansions agree in exact arithmetic but not in f32, and near a singular matrix one can read zero
+ * where the other does not.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mat3_determinant: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_mat3_determinant.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_determinant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_mat3_determinant.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_determinant.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,qCAFU,SAAS,CAQZ;0BAzBmB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_determinant.js

@@ -0,0 +1,26 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * Determinant of a 3×3 as the triple product of its columns, `dot(m[0], cross(m[1], m[2]))`. Same
+ * expression as {@link m4_linear_determinant}, the CPU twin of `mat4_linear_determinant`, which
+ * reads it through this.
+ *
+ * Written out rather than left to WGSL's `determinant`. The specification gives that builtin no
+ * accuracy at all ("Infinite ULP"), each backend expands it its own way, and no CPU model can stand
+ * in for it. This expression's accuracy is what `dot` and `cross` inherit from their operations. It
+ * is exactly zero for a column of zeros at any rotation, because every term of the expansion
+ * carries a factor from that column, even where the backend fuses the products.
+ *
+ * A caller dividing by a determinant tests that very number, not another expansion of it. Two
+ * expansions agree in exact arithmetic but not in f32, and near a singular matrix one can read zero
+ * where the other does not.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mat3_determinant = CodeChunk.from(
+    //language=WGSL
+    `
+fn mat3_determinant(m: mat3x3<f32>) -> f32 {
+    return dot(m[0], cross(m[1], m[2]));
+}
+`, []);

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.d.ts

@@ -1,5 +1,10 @@
 /**
- * The largest and smallest singular values of a 3×3 matrix.
+ * The largest and smallest singular values of a 3×3 matrix. **Expensive but correct**: a couple of
+ * hundred ALU operations, a transcendental pair and a handful of square roots, where the longest
+ * and shortest column (`mat4_extract_scale`) cost three lengths. Those are the same numbers for any
+ * rotation times a scale, and the real-time paths (virtual geometry's cut, the probe clipmap's
+ * bricks) read the columns and accept that a shear goes unaccounted. Reach for this only where a
+ * shear has to be measured, and not per instance per view per frame.
  *
  * They are what "how much does this transform stretch a distance" actually means: a vector's length
  * is scaled by something between σ_min and σ_max, and both bounds are attained. Column lengths are
@@ -7,23 +12,60 @@
  * `[[1,0,0],[k,1,0],[0,0,1]]`, every column has length 1 or √(1+k²) while the true ratio grows
  * without bound in `k`. A shear has no scale in any column and stretches space anyway.
  *
- * Computed as the square roots of the eigenvalues of `MᵀM`, which is symmetric and positive
- * semi-definite, through the closed form for a symmetric 3×3 (Smith 1961). No iteration, no
- * branching past the diagonal case, and **exact for a uniform scale**: `MᵀM` is then `s²I`, the
- * off-diagonal sum is zero, and both values come back as `s`. That matters more than the general
- * case — a conservative bound that answered 5.2 for an unscaled instance would over-refine every
- * ordinary object in a scene to buy correctness for a sheared one.
- *
- * **Not a degeneracy test.** σ_min is zero exactly when the matrix is singular *in exact
- * arithmetic*, and this once said so without the qualifier. In f32 it holds only on the diagonal
- * branch: the trigonometric one computes the smallest eigenvalue as a difference of nearly equal
- * numbers, and the `sqrt` turns its absolute error of about `eps·σ_max²` into about
- * `sqrt(eps)·σ_max ≈ 3.4e-4·σ_max` in σ_min. A rotated matrix with one column of zeros therefore
- * comes back with a σ_min near 1e-4 rather than 0, and a caller testing `σ_min > 0` before
- * inverting is let through with the NaN it was guarding against
- * (`shader_vgeo_cut_collect`, REVIEW_LEDGER M3). A caller about to invert should test the
- * **determinant**, which is the number the inverse divides by and which is exactly zero whenever a
- * column is.
+ * **Method.** M is first scaled by the power of two that brings its largest entry into [1, 2), and
+ * the values are scaled back at the end. That is exact, and it keeps every square and product below
+ * far inside f32's range whatever the transform's scale.
+ *
+ * The eigenvalues of `MᵀM` are the squared singular values, and Smith's closed form (1961) gives
+ * them as `q + p·β` for the roots `β = 2cos(φ + 2πk/3)` of `β³ − 3β − det B`, with
+ * `B = (MᵀM − qI) / p`. Only one root is taken from that form: the one that stands apart from the
+ * other two, which is the largest when `det B ≥ 0` and the smallest otherwise (Scherzinger &
+ * Dohrmann 2008; Eberly, "A Robust Eigensolver for 3×3 Symmetric Matrices"). The other two are
+ * ill-conditioned where two roots meet: `det(B)/2` then sits at ±1, the edge of `acos`'s domain, so
+ * one rounding of it moves φ by `acos(1 − 2⁻²⁴)/3 ≈ 1.2e-4`, and those two roots by √3·p times
+ * that. For a beam-like scale p is a third of σ_max², which is enough to take σ_min to zero. The
+ * root that stands apart is stationary in φ at both edges, and lies at least √3 from the others,
+ * where the cubic's slope `3(β² − 1)` is at least 6. One Newton step there squares whatever error
+ * the device's `cos` and `acos` leave, which WGSL bounds only loosely.
+ *
+ * That root is used only for its eigenvector `v`. `B − βI` has rank two, and the longest cross
+ * product of two of its rows is normal to both. The complement of `v` is built from `v`'s own
+ * components (Eberly's `ComputeOrthogonalComplement`): `u` is `v` crossed with `e_y` or `e_x`,
+ * whichever `v` leans on less, and `w = v × u`. So `u` and `w` are off from `v` by no more than the
+ * rounding of `v`'s smaller components. That matters, because any component of `v` in the plane
+ * lets σ_max leak into the plane's values, which feel it squared and amplified by (σ_max / σ_mid)².
+ *
+ * Every value returned is measured on M itself, because a small singular value cannot come from
+ * `MᵀM`: its rounding is absolute, at the scale of σ_max² (Demmel & Veselić 1992). `v` and the plane
+ * split M into `|Mv|` and the 3×2 `[Mu Mw]`, whose larger singular value comes out of a 2×2 form
+ * with no cancellation in it. That gives σ_max and σ_mid, and σ_min = |det M| / (σ_max · σ_mid).
+ *
+ * **Contract.**
+ *
+ * - **Exact when `MᵀM` comes out diagonal**: any axis-aligned scale, the identity and a uniform
+ *   scale among them. Both values are then square roots of the diagonal's extremes, scaled back by
+ *   the same power of two, so a uniform scale returns σ_max equal to σ_min, and both are the column
+ *   lengths to the accuracy of the device's `sqrt`. That matters more than the general case: a
+ *   conservative bound that answered 5.2 for an unscaled instance would over-refine every ordinary
+ *   object in a scene to buy correctness for a sheared one.
+ * - **Otherwise each value carries a relative error of order `u·K`**, with `u = 2⁻²⁴` and
+ *   `K = |m₀|·|m₁|·|m₂| / |det M| ≥ 1`. `K` is 1 when the columns are orthogonal: a rotation times
+ *   any scale, whatever the ratio of the scales. Rounding in `det M`, and in the three images of M,
+ *   is first order in `u·K`. The eigenvector's own error enters at second order, amplified by
+ *   (σ_max / σ_mid)². With orthogonal columns `v` lies on an axis to within u / (σ_max / σ_mid), so
+ *   that term stays below u. Otherwise σ_max / σ_mid is itself bounded by a multiple of K, so the
+ *   term stays below u·K while u·K is small.
+ * - **Either direction for σ_min, so it can over-estimate, but never past the shortest column's
+ *   length** as f32 computes it. σ_max can only fall short, and never below the longest column's
+ *   length. Every column is an image of a unit vector, so its length lies in [σ_min, σ_max] exactly,
+ *   and the result is held to both bounds. It follows that σ_min ≤ σ_max.
+ * - **σ_min is zero exactly when `mat3_determinant(M)` is**, or when it underflows. A column or a
+ *   row of zeros gives exactly zero at every rotation. A matrix that is singular only in exact
+ *   arithmetic, such as a child turned under a flattened parent, has a determinant of rounding noise,
+ *   and so a σ_min of the same noise rather than zero. A caller about to divide by a determinant
+ *   tests that very number: another expansion can differ from this one in rounding, enough to
+ *   disagree about zero near a singular matrix.
+ * - Valid for any finite M. Values below f32's normal range flush where the device flushes.
  *
  * @type {CodeChunk}
  *

package/src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_mat3_singular_values.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,yCALU,SAAS,CA6DZ;0BA1FmB,gCAAgC"}
+{"version":3,"file":"chunk_mat3_singular_values.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/mat3/chunk_mat3_singular_values.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,yCALU,SAAS,CAuI0B;0BAhNnB,gCAAgC"}