@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/renderer/volumetrics/taa/shader_volumetrics_taa.js

@@ -1,335 +1,135 @@
-import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { chunk_color_clip_to_aabb4 } from "../../postprocess/taa/chunk_color_clip_to_aabb3.js";
-import { chunk_rgb_to_YCoCg } from "../../shader/chunk/color/YCoCg/chunk_rgb_to_YCoCg.js";
-import { chunk_YCoCg_to_rgb } from "../../shader/chunk/color/YCoCg/chunk_YCoCg_to_rgb.js";
-import { chunk_aabb4_normalized_dist } from "../../shader/chunk/geometry/aabb3/chunk_aabb4_normalized_dist.js";
-import { chunk_frustum_sample_point } from "../../shader/chunk/geometry/frustum/chunk_frustum_sample_point.js";
-import { chunk_filter_blackman_harris229 } from "../../shader/chunk/filter/chunk_filter_blackman_harris229.js";
-import { chunk_ndc_to_uv } from "../../shader/chunk/texture/chunk_ndc_to_uv.js";
-import { chunk_texel_coordinate_to_uv } from "../../shader/chunk/texture/chunk_texel_coordinate_to_uv.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { chunk_cluster_depth_from_z_slice } from "../../light/cluster/chunk_cluster_depth_from_z_slice.js";
-import { chunk_cluster_depth_to_z_slice } from "../../light/cluster/chunk_cluster_depth_to_z_slice.js";
-import { VOLUMETRICS_METADATA_STRUCT } from "../VOLUMETRICS_METADATA_STRUCT.js";
-import { chunk_volumetric_history_bounding_box } from "./chunk_volumetric_history_bounding_box.js";
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addTexture("t_current", "float", "3d")
-    .addTexture("t_history", "float", "3d")
-    .addStorageTexture("t_output", "rgba16float", "3d", "write-only")
-    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
-    .addUniform("camera_current", CAMERA_UNIFORM_STRUCT)
-    .addUniform("camera_previous", CAMERA_UNIFORM_STRUCT)
-;
-
-/**
- * 3D Blackman-Harris resample. The per-tap weight W(x) = exp(-2.29 * x * x) is provided by
- * chunk_filter_blackman_harris229 (filter_blackman_harris229). Weights precomputed for offsets -1, 0, 1.
- */
-const chunk_texture_sample_blackman_harris_3d = CodeChunk.from(
-    //language=WGSL
-    `
-fn texture_sample_blackman_harris_3d(
-    tInput: texture_3d<f32>, 
-    uvw: vec3f, 
-    tex_dim: vec3f
-) -> vec4f {
-    let sample_pos = uvw * tex_dim;
-    let center_pos = floor(sample_pos - 0.5) + 0.5;
-    let f = sample_pos - center_pos; // Fractional offset from center texel [-0.5, 0.5]
-
-    var color_sum = vec4f(0.0);
-    var weight_sum = 0.0;
-    
-    // precompute weights for offsets -1, 0, 1
-    // slignly higher register pressure, but cheaper on compute
-    let weights = mat3x3<f32>(
-        filter_blackman_harris229(-1.0 - f.x), filter_blackman_harris229(0.0 - f.x), filter_blackman_harris229(1.0 - f.x),
-        filter_blackman_harris229(-1.0 - f.y), filter_blackman_harris229(0.0 - f.y), filter_blackman_harris229(1.0 - f.y),
-        filter_blackman_harris229(-1.0 - f.z), filter_blackman_harris229(0.0 - f.z), filter_blackman_harris229(1.0 - f.z),
-    );
-    
-    // 3x3x3 Loop
-    // We iterate neighbor offsets -1, 0, 1
-    for (var z = 0; z < 3; z += 1) {
-        let wz = weights[2][z];
-        
-        for (var y = 0; y < 3; y += 1) {
-            let wy = weights[1][y];
-            
-            for (var x = 0; x < 3; x += 1) {
-                let wx = weights[0][x];
-                
-                let w = wx * wy * wz;
-                
-                let sample_offset = vec3(x - 1, y - 1, z - 1);
-                
-                let coord = vec3i(center_pos) + sample_offset;
-                
-                let coord_clamped = clamp(coord, vec3i(0), vec3i(tex_dim) - 1);
-                
-                // Boundary check (optional if texture is clamped, but good for compute)
-                // Assuming texture is clamped to edge or handled by logic
-                let texel = textureLoad(tInput, coord_clamped, 0);
-                
-                color_sum += texel * w;
-                weight_sum += w;
-            }
-        }
-    }
-    
-    // Normalize
-    return max(vec4f(0.0), color_sum / max(weight_sum, 1e-5));
-}
-    `,
-    [chunk_filter_blackman_harris229]
-);
-
-/**
- * Froxel coordinate -> a sample point for `frustum_sample_point`, NOT a froxel texture coordinate.
- *
- * That distinction is the whole reason this is not `volumetrics_position_world_to_froxel_uvw`
- * turned around. There `w` is slice space -- `log2(fma(depth, x, y)) * z`, corrected by the
- * cell-averaged content offset -- because it addresses the 3D texture. Here `w` is a LINEAR
- * fraction of the near..far range, because its only consumer is `frustum_sample_point`, which
- * mixes the near and far planes linearly. The two agree at the endpoints and nowhere between, so
- * feeding this `w` to a froxel textureSample reads the wrong slab.
- *
- * @see volumetrics_position_world_to_froxel_uvw
- * @type {CodeChunk}
- */
-const chunk_volumetrics_froxel_coord_to_frustum_uvw = CodeChunk.from(
-    //language=WGSL
-    `
-fn volumetrics_froxel_coord_to_frustum_uvw(
-    coord: vec3<u32>,
-    res: vec3<u32>,
-    camera: ${CAMERA_UNIFORM_STRUCT.wgsl_ref},
-    cluster_params: vec3f
-) -> vec3f {
-    let uv = texel_coordinate_to_uv(vec2f(coord.xy), res.xy);
-
-    // Logical near/far (clip_near_far), NOT the projection-derived range: the projection is
-    // infinite-far reverse-Z so its far resolves to ~3.4e38, which collapses z0_norm below to ~0
-    // (every slice maps to the near plane). This was the core reason TAA reprojection produced
-    // garbage. Matches the participating-media build shader.
-    let near_far = camera.clip_near_far;
-
-    let depth_raw = cluster_depth_from_z_slice(
-        f32(coord.z) + 0.5,
-        cluster_params,
-        f32(res.z)
-    );
-
-    // Use center of voxel
-    let view_depth = clamp(
-        depth_raw,
-        near_far.x,
-        near_far.y
-    );
-    
-    let z0_norm = (view_depth - near_far.x) / (near_far.y - near_far.x);
-            
-    return vec3f(uv, z0_norm);
-}    
-    `, [
-        chunk_texel_coordinate_to_uv,
-        chunk_cluster_depth_from_z_slice,
-    ]
-)
-
-const chunk_world_pos_from_froxel = CodeChunk.from(
-    //language=WGSL
-    `
-// Helper to get world position from voxel index
-fn world_pos_from_froxel(
-    coord: vec3<u32>,
-    res: vec3<u32>,
-    camera: ${CAMERA_UNIFORM_STRUCT.wgsl_ref},
-    cluster_params: vec3f,
-    frustum: array<vec4<f32>, 6>
-) -> vec3f {
-    let uvw = volumetrics_froxel_coord_to_frustum_uvw(coord, res, camera, cluster_params);
-
-    // Reconstruct the froxel-centre world position. frustum_sample_point intersects the
-    // interpolated L/R, B/T, N/F planes; X maps left->left and Z maps near->far directly, so only
-    // screen-Y is flipped vs world-Y (1.0 - uvw.y). The caller passes the metadata frustum, which
-    // carries a FINITE far plane — the camera's own projection is infinite-far reverse-Z (far plane
-    // zeroed), which frustum_sample_point cannot intersect. Mirrors the participating-media build
-    // shader's Y-only flip; replaces the old vec3(1.0) - uvw inside-out hack that mirrored X and Z.
-    return frustum_sample_point(frustum, vec3f(uvw.x, 1.0 - uvw.y, uvw.z));
-}
-`, [
-        chunk_volumetrics_froxel_coord_to_frustum_uvw,
-        chunk_frustum_sample_point,
-    ]);
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@compute @workgroup_size(8, 8, 4)
-fn main(@builtin(global_invocation_id) voxel_id: vec3<u32>) {
-
-    let resolution = textureDimensions(t_output);
-
-    if (any(voxel_id >= resolution)) {
-        return;
-    }
-
-    // 1. Current Color
-    let color_curr = textureLoad(t_current, voxel_id, 0);
-    let rgb_curr = color_curr.rgb;
-    let center_ycocg = rgb_to_YCoCg(rgb_curr);
-    let center_encoded = vec4(center_ycocg, color_curr.a);
-
-    // 2. Reprojection
-    let current_position_ws = world_pos_from_froxel(
-        voxel_id,
-        resolution,
-        camera_current,
-        volumetrics_metadata.froxel_cluster_parameters,
-        volumetrics_metadata.frustum
-    );
-    
-    // FIX: Calculate View Space explicitly to get the correct Depth metric (-View.z)
-    let prev_view = camera_previous.view_matrix * vec4f(current_position_ws, 1.0);
-    let prev_depth = -prev_view.z; // Ensure this is Positive
-    
-    let prev_clip = camera_previous.view_projection_matrix * vec4f(current_position_ws, 1.0);
-    let prev_ndc = prev_clip.xyz / prev_clip.w;
-
-    // Standard NDC to UV
-    let prev_uv = ndc_to_uv(prev_ndc.xy);
-
-    // Linear Depth to Slice
-    let prev_slice = cluster_depth_to_z_slice(
-        prev_depth,
-        volumetrics_metadata.froxel_cluster_parameters,
-        f32(resolution.z)
-    );
-
-    // prev_slice already lands at the reconstructed froxel's CENTRE — the reconstruction sampled
-    // cluster_depth_from_z_slice(voxel.z + 0.5), so for a static camera prev_slice == voxel.z + 0.5,
-    // whose texel-centre normalized coord is exactly prev_slice / res.z. Adding a further +0.5 here
-    // double-counted the texel-centre offset and sampled half a froxel too far in Z every frame: the
-    // history blurred slice z into z+1 and the 0.95 blend fed that error back (the visible noise).
-    let prev_w = prev_slice / f32(resolution.z);
-    let prev_uvw = vec3f(prev_uv, prev_w);
-    let current_uvw = (vec3f(voxel_id) + 0.5) / vec3f(resolution);   
-
-    // 3. Validity Check — reprojection must land inside the volume, and history must not be flagged
-    // for reset (first frame / resize / teleport); otherwise we fall back to the fresh sample.
-    let is_valid = all(prev_uvw >= vec3f(0.0))
-        && all(prev_uvw <= vec3f(1.0))
-        && volumetrics_metadata.history_reset == 0u;
-    
-    // How far the voxels have moved? Distances are measured in voxels
-    let velocity_voxels = (current_uvw - prev_uvw) * vec3f(resolution);
-
-    // beyond this distance in voxels - we consider history to be invalid
-    const TAA_VELOCITY_LIMIT_IN_VOXELS_XYZ = 16.0;
-    
-    // lower confidence in history when velocity is high
-    var velocity_confidence = saturate( 1.0 - length(velocity_voxels) / TAA_VELOCITY_LIMIT_IN_VOXELS_XYZ);
-
-
-    var final_color: vec4f;
-
-    if (!is_valid) {
-        final_color = color_curr;
-    } else {
-        // 5. Sample History using Blackman-Harris Filter
-        let history_raw = texture_sample_blackman_harris_3d(
-            t_history,
-            prev_uvw,
-            vec3f(resolution)
-        );
-
-        // 6. Clip History to Neighborhood
-        let history_ycocg = rgb_to_YCoCg(history_raw.rgb);
-        let history_encoded = vec4(history_ycocg, history_raw.a);
-
-        // 4. Neighborhood Clamping (Variance Based)
-        var aabb_min: vec4f;
-        var aabb_max: vec4f;
-        
-        // Gamma: 1.0 is standard, lower = less ghosting/more flicker
-        let variance_gamma = mix(
-            vec4(0.3, 0.5, 0.5, 0.3),
-            vec4(2.5, 3, 3, 2.5),
-            velocity_confidence * velocity_confidence
-        );
-    
-        volumetric_history_bounding_box(
-            t_current,
-            center_encoded,
-            voxel_id,
-            resolution,
-            variance_gamma, 
-            &aabb_min,
-            &aabb_max
-        );
-    
-
-        let history_clamped = color_clip_to_aabb4(
-            history_encoded, 
-            center_encoded,
-            aabb_min,
-            aabb_max
-        );
-        
-        
-        // We detect when clamp would occur and dampen the incoming sample's contribution to counteract it. 
-        // see "High Quality Temporal Supersampling" by Brian Karis, EpicGames SIGGRAPH 2014
-        let t_clamp = saturate(aabb4_normalized_dist_from_center(
-            center_encoded,
-            history_clamped,
-            aabb_min,
-            aabb_max,
-        ));
-        
-        // TODO take extinction into account for clamping, currently we only do scattering
-        
-        
-        // 7. Blend
-        const blend_base = 0.95;
-
-        var confidence = 1.0;
-                
-        // Detect clamping events, so we can reduce confidence in the blend
-        let confidence_factor = mix(1.0, 0.0, t_clamp * t_clamp * t_clamp);
-
-        confidence *= confidence_factor;
-        
-        let blend = blend_base * confidence;
-
-        let mixed = mix(center_encoded, history_clamped, blend);
-
-        final_color = vec4f(YCoCg_to_rgb(mixed.xyz), mixed.w);
-        
-    }
-                    
-    textureStore(t_output, voxel_id, final_color);
-}
-    `,
-    [
-        chunk_cluster_depth_to_z_slice,
-        chunk_rgb_to_YCoCg,
-        chunk_YCoCg_to_rgb,
-        chunk_color_clip_to_aabb4,
-        chunk_texture_sample_blackman_harris_3d,
-        chunk_world_pos_from_froxel,
-        chunk_ndc_to_uv,
-        chunk_volumetric_history_bounding_box,
-        chunk_aabb4_normalized_dist,
-    ]
-);
-
-export const shader_volumetrics_taa = ComputeShader.from({
-    label: "Volumetric TAA",
-    resources,
-    body
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_rgb_to_YCoCg } from "../../shader/chunk/color/YCoCg/chunk_rgb_to_YCoCg.js";
+import { chunk_YCoCg_to_rgb } from "../../shader/chunk/color/YCoCg/chunk_YCoCg_to_rgb.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../../texture/SAMPLER_LINEAR_UPSCALE.js";
+import { VOLUMETRICS_METADATA_STRUCT } from "../VOLUMETRICS_METADATA_STRUCT.js";
+import { chunk_volumetric_history_bounding_box } from "./chunk_volumetric_history_bounding_box.js";
+import { chunk_volumetrics_taa_reproject } from "./chunk_volumetrics_taa_reproject.js";
+import { chunk_volumetrics_taa_resolve } from "./chunk_volumetrics_taa_resolve.js";
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addTexture("t_current", "float", "3d")
+    .addTexture("t_history", "float", "3d")
+    // Trilinear, clamp to edge. The declared descriptor binds itself, so the graph pass passes
+    // nothing for it. The same descriptor the lighting and LUT passes sample their volumes with.
+    .addSampler("s_history", "filtering", SAMPLER_LINEAR_UPSCALE)
+    .addStorageTexture("t_output", "rgba16float", "3d", "write-only")
+    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
+    .addUniform("camera_current", CAMERA_UNIFORM_STRUCT)
+    .addUniform("camera_previous", CAMERA_UNIFORM_STRUCT)
+;
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(8, 8, 4)
+fn main(@builtin(global_invocation_id) voxel_id: vec3<u32>) {
+
+    let resolution = textureDimensions(t_output);
+
+    if (any(voxel_id >= resolution)) {
+        return;
+    }
+
+    // 1. Current Color
+    let color_curr = textureLoad(t_current, voxel_id, 0);
+    let rgb_curr = color_curr.rgb;
+    let center_ycocg = rgb_to_YCoCg(rgb_curr);
+    let center_encoded = vec4(center_ycocg, color_curr.a);
+
+    // 2. Reprojection: where this froxel was in last frame's grid, and its depth in that camera
+    let reprojection = volumetrics_taa_reproject(
+        voxel_id,
+        resolution,
+        camera_current,
+        camera_previous,
+        volumetrics_metadata.froxel_cluster_parameters,
+        volumetrics_metadata.frustum
+    );
+
+    let prev_uvw = reprojection.xyz;
+    let current_uvw = (vec3f(voxel_id) + 0.5) / vec3f(resolution);
+
+    // 3. Validity Check
+    let is_valid = volumetrics_taa_history_valid(reprojection, volumetrics_metadata.history_reset);
+
+    // 4. How far the froxel moved between the frames, in voxels of the grid
+    let velocity_voxels = (current_uvw - prev_uvw) * vec3f(resolution);
+
+    // At this speed and beyond the neighbourhood box is at its tightest gamma. The history is NOT
+    // rejected for speed: the resampled history is still the best estimate of the froxel, and the
+    // clip below keeps it inside what the neighbourhood allows.
+    const TAA_VELOCITY_LIMIT_IN_VOXELS_XYZ = 16.0;
+
+    let velocity_confidence = saturate( 1.0 - length(velocity_voxels) / TAA_VELOCITY_LIMIT_IN_VOXELS_XYZ);
+
+
+    var final_color: vec4f;
+
+    if (!is_valid) {
+        final_color = color_curr;
+    } else {
+        // 5. Fetch the history. Trilinear, because the fetch must be interpolating: a static
+        // camera lands exactly on a texel centre and must read back exactly that texel. The 3x3x3
+        // Blackman-Harris resample this replaced weighted the +-1 neighbours at 8.4% each even at
+        // a zero offset, so every frame convolved the accumulation with a 27-tap blur and the 0.95
+        // feedback compounded it to ~1.8 froxels of sigma along each axis. Karis uses that kernel
+        // to filter the CURRENT frame; history is fetched with an interpolating filter, Catmull-Rom
+        // in his and in this repo's 2D TAA. The max guards the clip: a box corner in YCoCg need not
+        // be a non-negative RGB, and that goes into next frame's history.
+        let history_raw = max(vec4f(0.0), textureSampleLevel(t_history, s_history, prev_uvw, 0.0));
+
+        // encoded the way the centre is: YCoCg scattering, extinction as is
+        let history_ycocg = rgb_to_YCoCg(history_raw.rgb);
+        let history_encoded = vec4(history_ycocg, history_raw.a);
+
+        // 6. Neighbourhood box, variance based, always containing the centre
+        var aabb_min: vec4f;
+        var aabb_max: vec4f;
+
+        // Gamma: 1.0 is standard, lower = less ghosting/more flicker
+        let variance_gamma = mix(
+            vec4(0.3, 0.5, 0.5, 0.3),
+            vec4(2.5, 3, 3, 2.5),
+            velocity_confidence * velocity_confidence
+        );
+    
+        volumetric_history_bounding_box(
+            t_current,
+            center_encoded,
+            voxel_id,
+            resolution,
+            variance_gamma, 
+            &aabb_min,
+            &aabb_max
+        );
+    
+
+        // 7. Clip the history to the neighbourhood and blend
+        let mixed = volumetrics_taa_resolve(center_encoded, history_encoded, aabb_min, aabb_max);
+
+        final_color = vec4f(YCoCg_to_rgb(mixed.xyz), mixed.w);
+        
+    }
+                    
+    textureStore(t_output, voxel_id, final_color);
+}
+    `,
+    [
+        chunk_rgb_to_YCoCg,
+        chunk_YCoCg_to_rgb,
+        chunk_volumetrics_taa_reproject,
+        chunk_volumetric_history_bounding_box,
+        chunk_volumetrics_taa_resolve,
+    ]
+);
+
+export const shader_volumetrics_taa = ComputeShader.from({
+    label: "Volumetric TAA",
+    resources,
+    body
 });

package/src/shade/util/texture_mip_extent.d.ts

@@ -0,0 +1,49 @@
+/**
+ * One dimension of a texture at `level`.
+ *
+ * Halving, floored at 1 — a 1024-wide texture is still 1 texel wide at level 10 and at level 20.
+ * Trivial, and re-derived in enough places that getting it wrong is a real event rather than a
+ * hypothetical one.
+ *
+ * @param {number} size texels, at the base level
+ * @param {number} level
+ * @returns {number} texels, at `level`
+ */
+export function texture_mip_size(size: number, level: number): number;
+/**
+ * The extent of a texture at `level`.
+ *
+ * **Only a 3D texture's depth halves.** The third component of an array texture is a layer count,
+ * and every layer carries every mip — so it does not shrink with the others. That single distinction
+ * is the reason this exists as a named thing: written out by hand it reads as an obvious `>> level`
+ * on all three components, and that mistake under-reported a six-layer cube map's memory by close to
+ * half and would have uploaded its levels at the wrong extent.
+ *
+ * @param {number} width texels, at the base level
+ * @param {number} height texels, at the base level
+ * @param {number} depth_or_layers depth for a 3D texture, layer count otherwise
+ * @param {GPUTextureDimension|string} dimension
+ * @param {number} level
+ * @returns {number[]} `[width, height, depthOrArrayLayers]` at `level`, in the shape
+ * `GPUExtent3D` takes
+ */
+export function texture_mip_extent(width: number, height: number, depth_or_layers: number, dimension: GPUTextureDimension | string, level: number): number[];
+/**
+ * The number of levels in a texture's full mip chain.
+ *
+ * The count that {@link texture_mip_extent} implies: the chain runs until every halving axis has
+ * reached 1, so it is as long as the longest axis that halves. **Only a 3D texture's depth halves**
+ * — the same distinction, one derivative up. Written as `max(width, height)` it silently truncates
+ * every volume deeper than it is wide: a 4x4x16 has five levels and that reading gives three, while
+ * `texture_mip_extent` will happily report the extent of all five.
+ *
+ * A zero-sized texture has no levels. Any other size has at least one, which is what the `+ 1` is.
+ *
+ * @param {number} width texels, at the base level
+ * @param {number} height texels, at the base level
+ * @param {number} depth_or_layers depth for a 3D texture, layer count otherwise
+ * @param {GPUTextureDimension|string} dimension
+ * @returns {number}
+ */
+export function texture_mip_level_count(width: number, height: number, depth_or_layers: number, dimension: GPUTextureDimension | string): number;
+//# sourceMappingURL=texture_mip_extent.d.ts.map

package/src/shade/util/texture_mip_extent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture_mip_extent.d.ts","sourceRoot":"","sources":["../../../../src/shade/util/texture_mip_extent.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,uCAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,0CARW,MAAM,UACN,MAAM,mBACN,MAAM,aACN,sBAAoB,MAAM,SAC1B,MAAM,GACJ,MAAM,EAAE,CAYpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,+CANW,MAAM,UACN,MAAM,mBACN,MAAM,aACN,sBAAoB,MAAM,GACxB,MAAM,CA0BlB"}

package/src/shade/util/texture_mip_extent.js

@@ -0,0 +1,87 @@
+import { assert } from "../../core/assert.js";
+
+/**
+ * One dimension of a texture at `level`.
+ *
+ * Halving, floored at 1 — a 1024-wide texture is still 1 texel wide at level 10 and at level 20.
+ * Trivial, and re-derived in enough places that getting it wrong is a real event rather than a
+ * hypothetical one.
+ *
+ * @param {number} size texels, at the base level
+ * @param {number} level
+ * @returns {number} texels, at `level`
+ */
+export function texture_mip_size(size, level) {
+    return Math.max(size >> level, 1);
+}
+
+/**
+ * The extent of a texture at `level`.
+ *
+ * **Only a 3D texture's depth halves.** The third component of an array texture is a layer count,
+ * and every layer carries every mip — so it does not shrink with the others. That single distinction
+ * is the reason this exists as a named thing: written out by hand it reads as an obvious `>> level`
+ * on all three components, and that mistake under-reported a six-layer cube map's memory by close to
+ * half and would have uploaded its levels at the wrong extent.
+ *
+ * @param {number} width texels, at the base level
+ * @param {number} height texels, at the base level
+ * @param {number} depth_or_layers depth for a 3D texture, layer count otherwise
+ * @param {GPUTextureDimension|string} dimension
+ * @param {number} level
+ * @returns {number[]} `[width, height, depthOrArrayLayers]` at `level`, in the shape
+ * `GPUExtent3D` takes
+ */
+export function texture_mip_extent(width, height, depth_or_layers, dimension, level) {
+    assert.isString(dimension, 'dimension');
+    assert.isNonNegativeInteger(level, 'level');
+
+    return [
+        texture_mip_size(width, level),
+        texture_mip_size(height, level),
+        dimension === "3d" ? texture_mip_size(depth_or_layers, level) : depth_or_layers,
+    ];
+}
+
+/**
+ * The number of levels in a texture's full mip chain.
+ *
+ * The count that {@link texture_mip_extent} implies: the chain runs until every halving axis has
+ * reached 1, so it is as long as the longest axis that halves. **Only a 3D texture's depth halves**
+ * — the same distinction, one derivative up. Written as `max(width, height)` it silently truncates
+ * every volume deeper than it is wide: a 4x4x16 has five levels and that reading gives three, while
+ * `texture_mip_extent` will happily report the extent of all five.
+ *
+ * A zero-sized texture has no levels. Any other size has at least one, which is what the `+ 1` is.
+ *
+ * @param {number} width texels, at the base level
+ * @param {number} height texels, at the base level
+ * @param {number} depth_or_layers depth for a 3D texture, layer count otherwise
+ * @param {GPUTextureDimension|string} dimension
+ * @returns {number}
+ */
+export function texture_mip_level_count(width, height, depth_or_layers, dimension) {
+    assert.isString(dimension, 'dimension');
+
+    assert.isNumber(width, 'width');
+    assert.isNumber(height, 'height');
+    assert.isNumber(depth_or_layers, 'depth_or_layers');
+
+    assert.notNaN(width, 'width');
+    assert.notNaN(height, 'height');
+    assert.notNaN(depth_or_layers, 'depth_or_layers');
+
+    assert.greaterThanOrEqual(width, 0, 'width');
+    assert.greaterThanOrEqual(height, 0, 'height');
+    assert.greaterThanOrEqual(depth_or_layers, 0, 'depth_or_layers');
+
+    const longest = dimension === "3d"
+        ? Math.max(width, height, depth_or_layers)
+        : Math.max(width, height);
+
+    if (longest === 0) {
+        return 0;
+    }
+
+    return Math.floor(Math.log2(longest)) + 1;
+}

package/src/shade/wgsl/emulator/WGSLJavaScriptCompiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WGSLJavaScriptCompiler.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLJavaScriptCompiler.js"],"names":[],"mappings":"AA8bA;IAEI;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,oBAFa,MAAM,CAMlB;CACJ;;UAtda,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS;WAClG,MAAM;WACN,MAAM;WACN,MAAM;WACN,MAAM;aACN,MAAM;cACN,QAAQ;YACR,MAAM"}
+{"version":3,"file":"WGSLJavaScriptCompiler.d.ts","sourceRoot":"","sources":["../../../../../src/shade/wgsl/emulator/WGSLJavaScriptCompiler.js"],"names":[],"mappings":"AA+bA;IAEI;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,oBAFa,MAAM,CAMlB;CACJ;;UAvda,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS;WAClG,MAAM;WACN,MAAM;WACN,MAAM;WACN,MAAM;aACN,MAAM;cACN,QAAQ;YACR,MAAM"}