@woosh/meep-engine 3.58.0 → 3.60.0

package/src/shade/renderer/shader/chunk/math/chunk_f16_round_stochastic.js

@@ -0,0 +1,43 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * Each component onto a value a half float holds exactly: the half above it with the probability of how far
+ * past the half below it the component lies, else the half below. Stochastic rounding.
+ *
+ * ```wgsl
+ * fn f16_round_stochastic(v: vec4<f32>, u: vec4<f32>) -> vec4<f32>
+ * ```
+ *
+ * `u` is uniform noise in [0, 1), a component each. A component a half holds is kept whatever its noise, and
+ * the result is `v` in expectation.
+ *
+ * Stored through halves, a blend `mix(history, x, α)` then moves in expectation however small its step. Rounded,
+ * it stops short of `x` by up to a ULP/α: half of that rounded to nearest, a whole one rounded toward zero, and
+ * one-sided. WGSL leaves rounding an f32 to a half to the implementation. An RTX 4090 and an RDNA2 iGPU were
+ * measured to round toward zero on every path: `pack2x16float`, `textureStore` and a render target's write. The
+ * result here is a half already, which any store keeps exactly. UE 5.4's TSR stores its history through
+ * `QuantizeForFloatRenderTarget` for the same reason.
+ *
+ * Within the half's finite range: past 65504 the half above is not finite.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_f16_round_stochastic = CodeChunk.from(
+    //language=WGSL
+    `
+fn f16_round_stochastic(v: vec4<f32>, u: vec4<f32>) -> vec4<f32> {
+    let magnitude = abs(v);
+
+    // a half's ULP at each magnitude and its inverse, powers of two from the exponent's field: 2^(e - 10) in a
+    // normal half's binade, 2^-24 among the subnormals
+    let exponent = max(bitcast<vec4<u32>>(magnitude) >> vec4<u32>(23u), vec4<u32>(113u));
+    let ulp = bitcast<vec4<f32>>((exponent - vec4<u32>(10u)) << vec4<u32>(23u));
+    let per_ulp = bitcast<vec4<f32>>((vec4<u32>(264u) - exponent) << vec4<u32>(23u));
+
+    // exact: scaled by a power of two
+    let steps = magnitude * per_ulp;
+    let below = floor(steps);
+
+    return sign(v) * (below + select(vec4<f32>(0.0), vec4<f32>(1.0), u < steps - below)) * ulp;
+}
+`);

package/src/shade/renderer/shader/chunk/noise/r/chunk_r2_canonical.d.ts

@@ -1,2 +1,8 @@
-export {};
+/**
+ We are sampling an R2 sequence - see http://extremelearning.com.au/unreasonable-effectiveness-of-quasirandom-sequences/
+ @see https://github.com/GameTechDev/XeGTAO/blob/a5b1686c7ea37788eeb3576b5be47f7c03db532c/Source/Rendering/Shaders/vaGTAO.hlsl#L74C71-L74C112
+ * @type {CodeChunk}
+ */
+export const chunk_r2_canonical: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
 //# sourceMappingURL=chunk_r2_canonical.d.ts.map

package/src/shade/renderer/shader/chunk/noise/r/chunk_r2_canonical.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_r2_canonical.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/noise/r/chunk_r2_canonical.js"],"names":[],"mappings":""}
+{"version":3,"file":"chunk_r2_canonical.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/noise/r/chunk_r2_canonical.js"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,iCAFU,SAAS,CASjB;0BAdwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/noise/r/chunk_r2_canonical.js

@@ -5,7 +5,7 @@ import { CodeChunk } from "../../../compiler/CodeChunk.js";
  @see https://github.com/GameTechDev/XeGTAO/blob/a5b1686c7ea37788eeb3576b5be47f7c03db532c/Source/Rendering/Shaders/vaGTAO.hlsl#L74C71-L74C112
  * @type {CodeChunk}
  */
-const chunk_r2_canonical = CodeChunk.from(
+export const chunk_r2_canonical = CodeChunk.from(
     //language=WGSL
     `
 fn r2_canonical(index:u32) -> vec2<f32> {

package/src/shade/renderer/shader/chunk/random/chunk_jitter_from_vectors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Two numbers in [0, 1] from two vectors and the frame: a hash of their bits with the frame index mixed in,
+ * for a pass with no screen texel to take blue noise at, such as a forward fragment or the water. A point
+ * and its normal hash to the same pair within a frame and to another the next. Reads `view`.
+ *
+ * ```wgsl
+ * fn jitter_from_vectors(v0: vec3<f32>, v1: vec3<f32>) -> vec2<f32>
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_jitter_from_vectors: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_jitter_from_vectors.d.ts.map

package/src/shade/renderer/shader/chunk/random/chunk_jitter_from_vectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_jitter_from_vectors.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/random/chunk_jitter_from_vectors.js"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,wCAFU,SAAS,CAqBjB;0BAjCwB,6BAA6B"}

package/src/shade/renderer/shader/chunk/random/chunk_jitter_from_vectors.js

@@ -0,0 +1,37 @@
+import { VIEW_RESOURCE } from "../../../view/VIEW_RESOURCE.js";
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+import { chunk_murmur3_vec3u } from "./murmur/chunk_murmur3_vec3u.js";
+
+/**
+ * Two numbers in [0, 1] from two vectors and the frame: a hash of their bits with the frame index mixed in,
+ * for a pass with no screen texel to take blue noise at, such as a forward fragment or the water. A point
+ * and its normal hash to the same pair within a frame and to another the next. Reads `view`.
+ *
+ * ```wgsl
+ * fn jitter_from_vectors(v0: vec3<f32>, v1: vec3<f32>) -> vec2<f32>
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_jitter_from_vectors = CodeChunk.from(
+    //language=WGSL
+    `
+fn jitter_from_vectors(v0:vec3<f32>, v1: vec3<f32>) -> vec2<f32>{
+    let u0 = bitcast<vec3<u32>>(v0);
+    let u1 = bitcast<vec3<u32>>(v1);
+
+    var h0 = u0 ^ u1;
+
+    // add temporal component
+    h0.x ^= view.frame_index;
+
+    let h1 = murmur3_vec3u(h0);
+
+    return unpack2x16unorm(h1);
+}
+    `, [
+        chunk_murmur3_vec3u,
+    ]
+);
+
+chunk_jitter_from_vectors.requireResource(VIEW_RESOURCE);

package/src/shade/renderer/shader/chunk/random/reservoir/chunk_pick2_wrs_mat2x4.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Two of eight, picked.
+ * @type {WebGPUStruct}
+ */
+export const PICK2_STRUCT: WebGPUStruct;
+/**
+ * Two of eight weighted items, picked by weighted reservoir sampling instead of blending all eight
+ * (Brick4's selection, PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.1):
+ *
+ * ```wgsl
+ * fn pick2_wrs_mat2x4(weights: mat2x4<f32>, noise: vec2<f32>) -> Pick2
+ * ```
+ *
+ * One draw of `sample_discrete_wrs_mat2x4` over the weights with `noise.x`; the drawn weight is zeroed
+ * and a second draw made with `noise.y`; the pair blends by the second's share of their weights. A
+ * single weight that is not zero is drawn once, the second draw's weight is zero, and the blend is 0.
+ * Noise is [0, 1).
+ *
+ * The drawn weights are read and cleared through masks rather than by indexing the matrix with a value,
+ * which would put it in local memory: 3% of the probe clipmap's diffuse on the AMD iGPU, measured.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_pick2_wrs_mat2x4: CodeChunk;
+import { WebGPUStruct } from "../../../type/WebGPUStruct.js";
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_pick2_wrs_mat2x4.d.ts.map

package/src/shade/renderer/shader/chunk/random/reservoir/chunk_pick2_wrs_mat2x4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_pick2_wrs_mat2x4.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/random/reservoir/chunk_pick2_wrs_mat2x4.js"],"names":[],"mappings":"AAKA;;;GAGG;AACH,2BAFU,YAAY,CAOV;AAEZ;;;;;;;;;;;;;;;;;GAiBG;AACH,qCAFU,SAAS,CA4BhB;6BA3D0B,+BAA+B;0BADlC,gCAAgC"}

package/src/shade/renderer/shader/chunk/random/reservoir/chunk_pick2_wrs_mat2x4.js

@@ -0,0 +1,61 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { WebGPUStruct } from "../../../type/WebGPUStruct.js";
+import { f32, vec2u } from "../../../type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { chunk_sample_discrete_wrs_mat2x4 } from "./chunk_sample_discrete_wrs_mat2x4.js";
+
+/**
+ * Two of eight, picked.
+ * @type {WebGPUStruct}
+ */
+export const PICK2_STRUCT = WebGPUStruct.from({
+    /** the two picked, 0 to 7, the first drawn first */
+    indices: vec2u,
+    /** the second's share of the pair, w₂ / (w₁ + w₂): 0 where only one weight is not zero */
+    blend: f32,
+}, "Pick2");
+
+/**
+ * Two of eight weighted items, picked by weighted reservoir sampling instead of blending all eight
+ * (Brick4's selection, PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §9.1):
+ *
+ * ```wgsl
+ * fn pick2_wrs_mat2x4(weights: mat2x4<f32>, noise: vec2<f32>) -> Pick2
+ * ```
+ *
+ * One draw of `sample_discrete_wrs_mat2x4` over the weights with `noise.x`; the drawn weight is zeroed
+ * and a second draw made with `noise.y`; the pair blends by the second's share of their weights. A
+ * single weight that is not zero is drawn once, the second draw's weight is zero, and the blend is 0.
+ * Noise is [0, 1).
+ *
+ * The drawn weights are read and cleared through masks rather than by indexing the matrix with a value,
+ * which would put it in local memory: 3% of the probe clipmap's diffuse on the AMD iGPU, measured.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_pick2_wrs_mat2x4 = CodeChunk.from(
+    //language=WGSL
+    `
+fn pick2_wrs_mat2x4(weights: mat2x4<f32>, noise: vec2<f32>) -> ${PICK2_STRUCT.wgsl_ref} {
+    var u = noise.x;
+
+    let first = u32(sample_discrete_wrs_mat2x4(weights, &u));
+    let first_low = select(vec4<f32>(0.0), vec4<f32>(1.0), vec4<u32>(0u, 1u, 2u, 3u) == vec4<u32>(first));
+    let first_high = select(vec4<f32>(0.0), vec4<f32>(1.0), vec4<u32>(4u, 5u, 6u, 7u) == vec4<u32>(first));
+    let weight0 = dot(weights[0], first_low) + dot(weights[1], first_high);
+
+    // the first cleared out, and a second draw with fresh entropy
+    let remaining = mat2x4<f32>(weights[0] * (1.0 - first_low), weights[1] * (1.0 - first_high));
+
+    u = noise.y;
+
+    let second = u32(sample_discrete_wrs_mat2x4(remaining, &u));
+    let second_low = select(vec4<f32>(0.0), vec4<f32>(1.0), vec4<u32>(0u, 1u, 2u, 3u) == vec4<u32>(second));
+    let second_high = select(vec4<f32>(0.0), vec4<f32>(1.0), vec4<u32>(4u, 5u, 6u, 7u) == vec4<u32>(second));
+    let weight1 = dot(remaining[0], second_low) + dot(remaining[1], second_high);
+
+    return ${PICK2_STRUCT.wgsl_ref}(vec2<u32>(first, second), weight1 / max(1e-6, weight0 + weight1));
+}
+`, [
+    PICK2_STRUCT.declaration_chunk,
+    chunk_sample_discrete_wrs_mat2x4,
+]);

package/src/shade/renderer/shader/chunk/spherical_harmonics/l1i/chunk_resolve_irradiance_sh_to_specular.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The radiance an L1 YCoCg SH holds toward `direction`, convolved with a GGX lobe of `alpha` (roughness²): the
+ * diffuse resolve ({@link chunk_resolve_irradiance_sh_to_diffuse}) with GGX's band-1 zonal factor
+ * (`sh2_approximate_GGX_zh`, MJP's fit) in place of the clamped cosine's 2/3. The SH is in the scale under which
+ * the diffuse resolve gives E/π, so this gives radiance.
+ *
+ * The chroma is the constant band's alone, rescaled by the ratio of the luma toward `direction` to the mean, as
+ * the diffuse resolve rescales it.
+ *
+ * - Where the zonal factor is 2/3 (alpha ≈ 0.8435) it is the diffuse resolve.
+ * - A field of constant radiance L gives L at every alpha.
+ *
+ * ```wgsl
+ * fn resolve_irradiance_sh_to_specular(shY: vec4<f32>, CoCg: vec2<f32>, direction: vec3<f32>, alpha: f32) -> vec3<f32>
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_resolve_irradiance_sh_to_specular: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_resolve_irradiance_sh_to_specular.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/l1i/chunk_resolve_irradiance_sh_to_specular.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_resolve_irradiance_sh_to_specular.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/l1i/chunk_resolve_irradiance_sh_to_specular.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,sDAFU,SAAS,CAoBjB;0BAxCwB,gCAAgC"}

package/src/shade/renderer/shader/chunk/spherical_harmonics/l1i/chunk_resolve_irradiance_sh_to_specular.js

@@ -0,0 +1,41 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_YCoCg_to_rgb } from "../../color/YCoCg/chunk_YCoCg_to_rgb.js";
+import { chunk_sh2_approximate_GGX_zh } from "../chunk_sh2_approximate_GGX_zh.js";
+
+/**
+ * The radiance an L1 YCoCg SH holds toward `direction`, convolved with a GGX lobe of `alpha` (roughness²): the
+ * diffuse resolve ({@link chunk_resolve_irradiance_sh_to_diffuse}) with GGX's band-1 zonal factor
+ * (`sh2_approximate_GGX_zh`, MJP's fit) in place of the clamped cosine's 2/3. The SH is in the scale under which
+ * the diffuse resolve gives E/π, so this gives radiance.
+ *
+ * The chroma is the constant band's alone, rescaled by the ratio of the luma toward `direction` to the mean, as
+ * the diffuse resolve rescales it.
+ *
+ * - Where the zonal factor is 2/3 (alpha ≈ 0.8435) it is the diffuse resolve.
+ * - A field of constant radiance L gives L at every alpha.
+ *
+ * ```wgsl
+ * fn resolve_irradiance_sh_to_specular(shY: vec4<f32>, CoCg: vec2<f32>, direction: vec3<f32>, alpha: f32) -> vec3<f32>
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_resolve_irradiance_sh_to_specular = CodeChunk.from(
+    //language=WGSL
+    `
+fn resolve_irradiance_sh_to_specular(shY: vec4<f32>, CoCg: vec2<f32>, direction: vec3<f32>, alpha: f32) -> vec3<f32> {
+    let g1 = sh2_approximate_GGX_zh(alpha).y;
+
+    // 2 pi times the radiance SH2 the store holds: band 0's basis constant, and band 1's under the lobe's factor
+    let Y = max(0.0, 6.283185307179586 * (0.28209479177387814 * shY.w + g1 * 0.4886025119029199 * dot(shY.xyz, direction)));
+
+    // correct color-reproduction, as the diffuse resolve does
+    let _CoCg = CoCg * 0.28209479177387814 * Y / (shY.w + 1e-6);
+
+    return max(YCoCg_to_rgb(vec3(Y, _CoCg)), vec3<f32>(0.0));
+}
+    `, [
+        chunk_sh2_approximate_GGX_zh,
+        chunk_YCoCg_to_rgb,
+    ]
+);

package/src/shade/renderer/shader/chunk/subgroup/chunk_subgroup_reserve_workgroup.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Claim a run of a workgroup list's places for each lane, one atomic per subgroup: the subgroup sums
+ * the lanes' `count`s, its first active lane adds the sum to `counter` with one `atomicAdd`, and each
+ * lane takes its run at its exclusive prefix over the subgroup.
+ *
+ * `fn subgroup_reserve_workgroup(counter: ptr<workgroup, atomic<u32>>, count: u32) -> u32`
+ *
+ * Returns the first place of the lane's run, `count` long; a lane that asks for none gets where its
+ * run would have been. Nothing is bounded here: the counter rises past whatever the list holds, and
+ * the caller decides what a place past its capacity means.
+ *
+ * Every lane of the subgroup calls it, asking or not, from subgroup-uniform control flow. Runs of
+ * different subgroups land in whatever order their atomics do. Nothing here assumes how subgroups map
+ * onto `local_invocation_index`.
+ *
+ * @see chunk_subgroup_append_slot for a list in storage, a place a lane
+ * @type {CodeChunk}
+ */
+export const chunk_subgroup_reserve_workgroup: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_subgroup_reserve_workgroup.d.ts.map

package/src/shade/renderer/shader/chunk/subgroup/chunk_subgroup_reserve_workgroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_subgroup_reserve_workgroup.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/subgroup/chunk_subgroup_reserve_workgroup.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,+CAFU,SAAS,CAoBhB;0BAtCuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/subgroup/chunk_subgroup_reserve_workgroup.js

@@ -0,0 +1,42 @@
+import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * Claim a run of a workgroup list's places for each lane, one atomic per subgroup: the subgroup sums
+ * the lanes' `count`s, its first active lane adds the sum to `counter` with one `atomicAdd`, and each
+ * lane takes its run at its exclusive prefix over the subgroup.
+ *
+ * `fn subgroup_reserve_workgroup(counter: ptr<workgroup, atomic<u32>>, count: u32) -> u32`
+ *
+ * Returns the first place of the lane's run, `count` long; a lane that asks for none gets where its
+ * run would have been. Nothing is bounded here: the counter rises past whatever the list holds, and
+ * the caller decides what a place past its capacity means.
+ *
+ * Every lane of the subgroup calls it, asking or not, from subgroup-uniform control flow. Runs of
+ * different subgroups land in whatever order their atomics do. Nothing here assumes how subgroups map
+ * onto `local_invocation_index`.
+ *
+ * @see chunk_subgroup_append_slot for a list in storage, a place a lane
+ * @type {CodeChunk}
+ */
+export const chunk_subgroup_reserve_workgroup = CodeChunk.from(
+    //language=WGSL
+    `
+fn subgroup_reserve_workgroup(counter: ptr<workgroup, atomic<u32>>, count: u32) -> u32 {
+    let offset = subgroupExclusiveAdd(count);
+    let total = subgroupAdd(count);
+
+    // elected before the branch, which then holds no subgroup operation and may be non-uniform
+    let elected = subgroupElect();
+
+    var base = 0u;
+
+    if (elected && total > 0u) {
+        base = atomicAdd(counter, total);
+    }
+
+    return subgroupBroadcastFirst(base) + offset;
+}
+`);
+
+chunk_subgroup_reserve_workgroup.addExtension(WebGPUExtensionType.Subgroups);

package/src/shade/renderer/texture/util/texture_fill_rectangle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"texture_fill_rectangle.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/util/texture_fill_rectangle.js"],"names":[],"mappings":"AAyMA;;;;;;;GAOG;AACH,8GAHW,MAAM,EAAE,cACR,MAAM,EAAE,QA2DlB"}
+{"version":3,"file":"texture_fill_rectangle.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/util/texture_fill_rectangle.js"],"names":[],"mappings":"AA6MA;;;;;;;GAOG;AACH,8GAHW,MAAM,EAAE,cACR,MAAM,EAAE,QAsElB"}