@woosh/meep-engine 3.12.0 → 3.13.0

package/src/shade/renderer/animation/skinning/shader_meshlet_apply_skinning.js

@@ -1,371 +1,375 @@
-import { mat4x4f, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import {
-    MESHLET_METADATA_FLAGS
-} from "../../geometry/meshlet/encoding/MESHLET_METADATA_FLAGS.js";
-import {
-    MESHLET_METADATA_STRUCT
-} from "../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
-import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
-import { chunk_mat4_inverse } from "../../shader/chunk/geometry/mat4/chunk_mat4_inverse.js";
-import {
-    chunk_meshlet_compute_attribute_section_offset
-} from "../../shader/chunk/geometry/meshlet/chunk_meshlet_compute_attribute_section_offset.js";
-import {
-    chunk_decode_vertex_normal
-} from "../../shader/chunk/geometry/normal/chunk_decode_vertex_normal.js";
-import {
-    chunk_encode_vertex_normal
-} from "../../shader/chunk/geometry/normal/chunk_encode_vertex_normal.js";
-import {
-    chunk_decode_vertex_tangent
-} from "../../shader/chunk/geometry/normal/tangent/chunk_decode_vertex_tangent.js";
-import {
-    chunk_encode_vertex_tangent
-} from "../../shader/chunk/geometry/normal/tangent/chunk_encode_vertex_tangent.js";
-import {
-    chunk_dual_quat_transform_direction
-} from "../../shader/chunk/geometry/quaternion/dual/chunk_dual_quat_transform_direction.js";
-import {
-    chunk_dual_quat_transform_point
-} from "../../shader/chunk/geometry/quaternion/dual/chunk_dual_quat_transform_point.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { chunk_skin_blend_mesh_local } from "./chunk_skin_blend_mesh_local.js";
-import { SKINNING_BINDING_STRUCT } from "./SKINNING_BINDING_STRUCT.js";
-
-/**
- * Workgroup size — also the per-meshlet vertex stride. Each thread
- * handles vertex `local_id`, then loops by `WORKGROUP_SIZE` for
- * meshlets larger than the workgroup.
- */
-export const SKINNING_WORKGROUP_SIZE = 64;
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    // First workgroup of the current sub-dispatch. WebGPU caps
-    // `dispatchWorkgroups` along each dimension at the device's
-    // `maxComputeWorkgroupsPerDimension` (65535 minimum per the
-    // spec, often higher in practice), so the host paginates large
-    // totals into multiple dispatches and increments this offset
-    // between them. The shader adds it to `wg_id.x` before indexing
-    // `dispatch_lookup`, so the per-pair mapping stays a flat array
-    // regardless of how many sub-dispatches it gets split into.
-    .addUniform('dispatch_offset', u32)
-    .addStorageBuffer('meshlet_data', WebGPUArray.from(u32), true)
-    .addStorageBuffer('meshlet_metadata', WebGPUArray.from(MESHLET_METADATA_STRUCT), false)
-    .addStorageBuffer('skin_matrices', WebGPUArray.from(mat4x4f), false)
-    .addStorageBuffer('prev_skin_matrices', WebGPUArray.from(mat4x4f), false)
-    .addStorageBuffer('skinning_bindings', WebGPUArray.from(SKINNING_BINDING_STRUCT), false)
-    .addStorageBuffer('dispatch_lookup', WebGPUArray.from(u32), false)
-    // Per-meshlet base u32-word offset into the side-buffer that
-    // holds previous-frame mesh-local positions. Sentinel
-    // `0xFFFFFFFF` for non-clone meshlets — those skip the
-    // prev-position write entirely, since the velocity post-pass
-    // will fall back to per-object math for them.
-    .addStorageBuffer('prev_position_offsets', WebGPUArray.from(u32), false)
-    .addStorageBuffer('prev_positions', WebGPUArray.from(u32), true)
-    // Scene-graph state — read-only. We need the SkinnedMesh's
-    // `transforms` row to source the live `mesh.transform_global`
-    // for the post-DQ position cancellation (see commentary in main).
-    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false);
-
-// One workgroup per (binding, meshlet) pair. The host builds
-// `dispatch_lookup` as a flat (binding_index, meshlet_local) pair
-// table and dispatches one workgroup per pair, so workgroup_id.x
-// directly indexes the table.
-//
-// Skinning math is dual-quaternion: each of the 4 per-vertex joints
-// contributes a DQ (built from its skin matrix), the four DQs blend
-// by weight (with antipodal correction), and the result transforms
-// position via the full screw motion and normal/tangent via just the
-// rotation part. DQ blending avoids the candy-wrapper artifacts of
-// linear matrix blending and lets normals + tangents transform with
-// the same blended frame, no matrix inversion or gimbal-style
-// interpolation issues.
-//
-// Per-attribute compression handling: Position is always
-// uncompressed (one entry per vertex, vertex_count*3 words). For
-// Normal and Tangent, the meshlet flags say whether they were
-// collapsed to a single shared entry across all vertices. Per-vertex
-// skinning into a shared slot would race, so the shader skips the
-// write for any attribute where the flag is set — the cloned slot
-// keeps the source's value and lighting on those vertices uses an
-// undeformed direction. For typical character meshes
-// normals/tangents vary per vertex and so don't get the all-equal
-// collapse, so this skip rarely engages in practice.
-//
-// SkinningJoints + SkinningWeights are read-only here. They CAN be
-// compressed — a meshlet where every vertex shares the same joint
-// palette (e.g. simple test meshes that bind every vertex to the
-// same two bones) collapses Joints to one shared u32-pair, and the
-// shader then has to broadcast that single entry across all vertex
-// reads instead of striding by 2 words per vertex. Same logic for
-// Weights (less common in practice — weights usually vary per
-// vertex even on simple meshes — but the flag handling is free).
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@compute @workgroup_size(${SKINNING_WORKGROUP_SIZE},1,1)
-fn main(
-    @builtin(workgroup_id) wg_id: vec3<u32>,
-    @builtin(local_invocation_index) local_id: u32,
-) {
-    // dispatch_offset lets the host paginate large dispatches —
-    // WebGPU's per-dimension cap is 65535 workgroups, but a busy
-    // scene's (binding, meshlet) pair total can exceed that.
-    let pair_index = wg_id.x + dispatch_offset;
-    let lookup_base = pair_index * 2u;
-    let binding_index = dispatch_lookup[lookup_base];
-    let meshlet_local = dispatch_lookup[lookup_base + 1u];
-
-    let binding = skinning_bindings[binding_index];
-
-    // The glTF skinning formula's leftmost factor is
-    // inverse(meshNode.worldMatrix), which lands the per-vertex
-    // output in mesh-local space ready for the rasterizer's
-    // mesh.world re-application (see
-    // chunk_mesh_resolve_vertex_position_world.js). It goes into
-    // each *matrix*, not onto the blended position — see
-    // chunk_skin_blend_mesh_local for why the difference is the
-    // whole ball game. Both positions and directions therefore come
-    // out of the blend already in mesh-local space, and the
-    // rasterizer's own transforms take them to world.
-    //
-    // mesh_instance_index is the row of the SkinnedMesh in the
-    // meshes table; mesh.node is its transforms-table row.
-    // Workgroup-uniform (one binding per workgroup), so the load +
-    // inverse amortize across every vertex this workgroup
-    // processes.
-    let mesh = scene_read_mesh(&scene_database, binding.mesh_instance_index);
-    let mesh_node = scene_read_node(&scene_database, mesh.node);
-    let inv_mesh_world = mat4_inverse(mesh_node.global);
-
-    let source_meshlet = meshlet_metadata[binding.source_meshlet_metadata_offset + meshlet_local];
-    let clone_meshlet  = meshlet_metadata[binding.clone_meshlet_metadata_offset + meshlet_local];
-
-    let vertex_count = source_meshlet.vertex_count;
-
-    // Both source and clone share an attribute layout (the clone is a
-    // memcpy of the source's bytes with addresses patched), so attribute
-    // offsets relative to each meshlet's attribute section are identical.
-    let source_attr_section = meshlet_compute_attribute_section_offset(source_meshlet);
-    let clone_attr_section  = meshlet_compute_attribute_section_offset(clone_meshlet);
-
-    // Walk the per-attribute layout, capturing the offset of each
-    // attribute we'll need. Order matches ENCODED_ORDERED_ATTRIBUTES:
-    // Position, Normal, Tangent, Color, UV0, UV1, SkinningJoints,
-    // SkinningWeights. Conditional skips for the compressible ones —
-    // when collapsed, the slot is a single shared entry rather than
-    // vertex_count entries.
-    let position_offset = 0u;
-    var attr_offset: u32 = vertex_count * 3u;
-
-    let normal_offset = attr_offset;
-    let normal_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_NORMAL}u) != 0u;
-    attr_offset = attr_offset + select(vertex_count, 1u, normal_compressed);
-
-    let tangent_offset = attr_offset;
-    let tangent_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_TANGENT}u) != 0u;
-    attr_offset = attr_offset + select(vertex_count, 1u, tangent_compressed);
-
-    let color_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_COLOR}u) != 0u;
-    attr_offset = attr_offset + select(vertex_count, 1u, color_compressed);
-
-    let uv0_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_TEXTURE_COORDINATES_0}u) != 0u;
-    attr_offset = attr_offset + select(vertex_count * 2u, 2u, uv0_compressed);
-
-    let uv1_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_TEXTURE_COORDINATES_1}u) != 0u;
-    attr_offset = attr_offset + select(vertex_count, 1u, uv1_compressed);
-
-    let joints_offset = attr_offset;
-    let joints_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_SKINNING_JOINTS}u) != 0u;
-    attr_offset = attr_offset + select(vertex_count * 2u, 2u, joints_compressed);
-
-    let weights_offset = attr_offset;
-    let weights_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_SKINNING_WEIGHTS}u) != 0u;
-
-    let skin_base = binding.skin_matrix_offset;
-
-    // Resolve the clone meshlet's per-meshlet base offset in the
-    // prev_positions side-buffer (or sentinel if this meshlet
-    // somehow isn't a clone — shouldn't happen in practice since
-    // the skinning shader only runs on (clone, skinned) pairs, but
-    // the check costs one load and one branch). Lifted out of the
-    // vertex loop because it's per-meshlet, not per-vertex.
-    let clone_meshlet_abs = binding.clone_meshlet_metadata_offset + meshlet_local;
-    let prev_pos_meshlet_base = prev_position_offsets[clone_meshlet_abs];
-    let has_prev_positions = prev_pos_meshlet_base != 0xFFFFFFFFu;
-
-    // Stride loop — one thread per WORKGROUP_SIZE-stride'd vertex slot.
-    // Most meshlets fit in a single iteration (vertex_count <=
-    // WORKGROUP_SIZE); larger ones cycle the workgroup over them.
-    var v: u32 = local_id;
-    loop {
-        if v >= vertex_count { break; }
-
-        // Joint indices: vec4<u16> packed into 2 u32s. When the
-        // attribute is compressed (every vertex of this meshlet
-        // shares the same palette), there's one shared pair at
-        // joints_offset rather than per-vertex strides; broadcast
-        // that single entry to every thread.
-        let joints_local_offset = select(v * 2u, 0u, joints_compressed);
-        let joints_addr = source_attr_section + joints_offset + joints_local_offset;
-        let raw_j0 = meshlet_data[joints_addr];
-        let raw_j1 = meshlet_data[joints_addr + 1u];
-        let j0 = raw_j0 & 0xFFFFu;
-        let j1 = (raw_j0 >> 16u) & 0xFFFFu;
-        let j2 = raw_j1 & 0xFFFFu;
-        let j3 = (raw_j1 >> 16u) & 0xFFFFu;
-
-        // Joint weights: vec4<unorm8> packed into 1 u32. Half the
-        // bandwidth of the previous f16×4 layout, sufficient
-        // precision for typical character skinning (step size
-        // ~0.4%, well under any visible artefact threshold).
-        // unpack4x8unorm returns vec4<f32> in [0, 1] with
-        // components matching byte 0..3 of the packed u32.
-        let weights_local_offset = select(v, 0u, weights_compressed);
-        let weights_addr = source_attr_section + weights_offset + weights_local_offset;
-        let weights = unpack4x8unorm(meshlet_data[weights_addr]);
-
-        // Build per-joint dual quaternions from the joint matrices, then
-        // blend with antipodal correction. The result represents the
-        // weighted-average screw motion the four matrices encode.
-        let dq_blend = skin_blend_mesh_local(
-            inv_mesh_world,
-            skin_matrices[skin_base + j0],
-            skin_matrices[skin_base + j1],
-            skin_matrices[skin_base + j2],
-            skin_matrices[skin_base + j3],
-            weights,
-        );
-
-        // Position: full screw motion (rotation + translation).
-        let pos_addr = source_attr_section + position_offset + v * 3u;
-        let p = vec3f(
-            bitcast<f32>(meshlet_data[pos_addr]),
-            bitcast<f32>(meshlet_data[pos_addr + 1u]),
-            bitcast<f32>(meshlet_data[pos_addr + 2u]),
-        );
-        // Position: full screw motion, already mesh-local — the
-        // rasterizer reapplies mesh.world to every mesh's vertices,
-        // skinned or not.
-        let p_skinned = dual_quat_transform_point(dq_blend, p);
-
-        let clone_pos_addr = clone_attr_section + position_offset + v * 3u;
-        meshlet_data[clone_pos_addr]      = bitcast<u32>(p_skinned.x);
-        meshlet_data[clone_pos_addr + 1u] = bitcast<u32>(p_skinned.y);
-        meshlet_data[clone_pos_addr + 2u] = bitcast<u32>(p_skinned.z);
-
-        // Previous-frame mesh-local position: same dual-quat math,
-        // but driven by prev_skin_matrices instead of skin_matrices.
-        // Written to the side-buffer at the per-meshlet base
-        // offset + v * 3 u32 words. The velocity post-pass reads
-        // these to interpolate per-vertex skin deformation across
-        // the rasterized triangle (vs. just the rigid mesh.global
-        // → mesh.prev_global delta that Stage 1's path captures).
-        //
-        // Skipping the write when there's no slot for this meshlet
-        // (non-clone — shouldn't be hit by this shader's dispatch
-        // set, but the guard is cheap). The dual-quat build is
-        // also skipped to save the per-joint work.
-        if has_prev_positions {
-            // Mesh-local for the same reason the current-frame
-            // position is — the velocity pass reads these through
-            // the same rasterizer transform, so the space they live
-            // in has to match.
-            let prev_dq_blend = skin_blend_mesh_local(
-                inv_mesh_world,
-                prev_skin_matrices[skin_base + j0],
-                prev_skin_matrices[skin_base + j1],
-                prev_skin_matrices[skin_base + j2],
-                prev_skin_matrices[skin_base + j3],
-                weights,
-            );
-
-            let p_prev_skinned = dual_quat_transform_point(prev_dq_blend, p);
-
-            let prev_addr = prev_pos_meshlet_base + v * 3u;
-            prev_positions[prev_addr]      = bitcast<u32>(p_prev_skinned.x);
-            prev_positions[prev_addr + 1u] = bitcast<u32>(p_prev_skinned.y);
-            prev_positions[prev_addr + 2u] = bitcast<u32>(p_prev_skinned.z);
-        }
-
-        // Normal: rotation only. Skip when the source compressed it
-        // down to a single shared slot — per-vertex writes to that
-        // slot would race, and the rotated direction would be
-        // mostly-meaningless anyway since every vertex would compute
-        // a different one.
-        //
-        // Mesh-local like the position, and left there: the
-        // rasterizer applies the inverse-transpose of mesh.world's
-        // 3x3 to it, which is the glTF normal transform and takes a
-        // mesh-local direction to world (see fragment_gbuffer.js).
-        if !normal_compressed {
-            let n_raw_addr = source_attr_section + normal_offset + v;
-            let n = decode_vertex_normal(meshlet_data[n_raw_addr]);
-            let n_skinned = normalize(dual_quat_transform_direction(dq_blend, n));
-
-            let clone_n_addr = clone_attr_section + normal_offset + v;
-            meshlet_data[clone_n_addr] = encode_vertex_normal(n_skinned);
-        }
-
-        // Tangent: rotation only on the xyz; w (handedness) is a
-        // topological property, copied through unchanged.
-        if !tangent_compressed {
-            let t_raw_addr = source_attr_section + tangent_offset + v;
-            let t = decode_vertex_tangent(meshlet_data[t_raw_addr]);
-            let t_skinned_dir = normalize(dual_quat_transform_direction(dq_blend, t.xyz));
-
-            let clone_t_addr = clone_attr_section + tangent_offset + v;
-            meshlet_data[clone_t_addr] = encode_vertex_tangent(vec4f(t_skinned_dir, t.w));
-        }
-
-        v = v + ${SKINNING_WORKGROUP_SIZE}u;
-    }
-}
-`, [
-        MESHLET_METADATA_STRUCT.declaration_chunk,
-        SKINNING_BINDING_STRUCT.declaration_chunk,
-        chunk_meshlet_compute_attribute_section_offset,
-        chunk_skin_blend_mesh_local,
-        chunk_dual_quat_transform_point,
-        chunk_dual_quat_transform_direction,
-        chunk_decode_vertex_normal,
-        chunk_encode_vertex_normal,
-        chunk_decode_vertex_tangent,
-        chunk_encode_vertex_tangent,
-        chunk_scene_database_access,
-        chunk_mat4_inverse,
-    ]
-);
-
-/**
- * Compute shader that deforms cloned meshlet vertex regions in place
- * using the per-frame skin matrices the prep pass produced. One
- * workgroup per (binding, meshlet) pair, dispatched against a flat
- * `dispatch_lookup` table the host builds when bindings change.
- *
- * Skins position (full transform) plus normal and tangent (rotation
- * only) per vertex via dual-quaternion blending — the blended DQ
- * captures the four per-vertex joints' screw motions weighted by
- * the per-vertex `SkinningWeights`, and applies cleanly to both
- * positions and unit-direction attributes without the matrix-blend
- * candy-wrapper artifacts that would otherwise show up in the
- * normal-transformed lighting.
- *
- * Source bytes stay untouched — other instances pointed at the
- * source render normally. Per-meshlet bounds aren't refreshed by
- * this pass; meshlets that animate outside the source bounds may
- * cull incorrectly until a future bounds-refresh phase lands.
- *
- * Dispatch via `shader.dispatch({ group_count_x: total_meshlet_count, ... })`
- * where `total_meshlet_count` is the sum of `meshlet_count` across
- * every registered binding. Skip when `total_meshlet_count === 0`.
- */
-export const shader_meshlet_apply_skinning = ComputeShader.from({
-    label: "Skinning/MeshletApplySkinning",
-    resources,
-    body,
-});
+import { mat4x4f, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import {
+    MESHLET_METADATA_FLAGS
+} from "../../geometry/meshlet/encoding/MESHLET_METADATA_FLAGS.js";
+import {
+    MESHLET_METADATA_STRUCT
+} from "../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
+import { chunk_mat4_inverse } from "../../shader/chunk/geometry/mat4/chunk_mat4_inverse.js";
+import {
+    chunk_meshlet_compute_attribute_section_offset
+} from "../../shader/chunk/geometry/meshlet/chunk_meshlet_compute_attribute_section_offset.js";
+import {
+    chunk_decode_vertex_normal
+} from "../../shader/chunk/geometry/normal/chunk_decode_vertex_normal.js";
+import {
+    chunk_encode_vertex_normal
+} from "../../shader/chunk/geometry/normal/chunk_encode_vertex_normal.js";
+import {
+    chunk_decode_vertex_tangent
+} from "../../shader/chunk/geometry/normal/tangent/chunk_decode_vertex_tangent.js";
+import {
+    chunk_encode_vertex_tangent
+} from "../../shader/chunk/geometry/normal/tangent/chunk_encode_vertex_tangent.js";
+import {
+    chunk_dual_quat_transform_direction
+} from "../../shader/chunk/geometry/quaternion/dual/chunk_dual_quat_transform_direction.js";
+import {
+    chunk_dual_quat_transform_point
+} from "../../shader/chunk/geometry/quaternion/dual/chunk_dual_quat_transform_point.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { chunk_skin_blend_mesh_local } from "./chunk_skin_blend_mesh_local.js";
+import { SKINNING_BINDING_STRUCT } from "./SKINNING_BINDING_STRUCT.js";
+
+/**
+ * Workgroup size — also the per-meshlet vertex stride. Each thread
+ * handles vertex `local_id`, then loops by `WORKGROUP_SIZE` for
+ * meshlets larger than the workgroup.
+ */
+export const SKINNING_WORKGROUP_SIZE = 64;
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer. Skinning is
+// paginated into sub-dispatches when the workload exceeds maxComputeWorkgroupsPerDimension, so the
+// buffer was allocated once per chunk to carry one integer.
+resources.setImmediate("dispatch_offset", u32);
+resources.createGroup()
+    // First workgroup of the current sub-dispatch. WebGPU caps
+    // `dispatchWorkgroups` along each dimension at the device's
+    // `maxComputeWorkgroupsPerDimension` (65535 minimum per the
+    // spec, often higher in practice), so the host paginates large
+    // totals into multiple dispatches and increments this offset
+    // between them. The shader adds it to `wg_id.x` before indexing
+    // `dispatch_lookup`, so the per-pair mapping stays a flat array
+    // regardless of how many sub-dispatches it gets split into.
+    .addStorageBuffer('meshlet_data', WebGPUArray.from(u32), true)
+    .addStorageBuffer('meshlet_metadata', WebGPUArray.from(MESHLET_METADATA_STRUCT), false)
+    .addStorageBuffer('skin_matrices', WebGPUArray.from(mat4x4f), false)
+    .addStorageBuffer('prev_skin_matrices', WebGPUArray.from(mat4x4f), false)
+    .addStorageBuffer('skinning_bindings', WebGPUArray.from(SKINNING_BINDING_STRUCT), false)
+    .addStorageBuffer('dispatch_lookup', WebGPUArray.from(u32), false)
+    // Per-meshlet base u32-word offset into the side-buffer that
+    // holds previous-frame mesh-local positions. Sentinel
+    // `0xFFFFFFFF` for non-clone meshlets — those skip the
+    // prev-position write entirely, since the velocity post-pass
+    // will fall back to per-object math for them.
+    .addStorageBuffer('prev_position_offsets', WebGPUArray.from(u32), false)
+    .addStorageBuffer('prev_positions', WebGPUArray.from(u32), true)
+    // Scene-graph state — read-only. We need the SkinnedMesh's
+    // `transforms` row to source the live `mesh.transform_global`
+    // for the post-DQ position cancellation (see commentary in main).
+    .addStorageBuffer('scene_database', WebGPUArray.from(u32), false);
+
+// One workgroup per (binding, meshlet) pair. The host builds
+// `dispatch_lookup` as a flat (binding_index, meshlet_local) pair
+// table and dispatches one workgroup per pair, so workgroup_id.x
+// directly indexes the table.
+//
+// Skinning math is dual-quaternion: each of the 4 per-vertex joints
+// contributes a DQ (built from its skin matrix), the four DQs blend
+// by weight (with antipodal correction), and the result transforms
+// position via the full screw motion and normal/tangent via just the
+// rotation part. DQ blending avoids the candy-wrapper artifacts of
+// linear matrix blending and lets normals + tangents transform with
+// the same blended frame, no matrix inversion or gimbal-style
+// interpolation issues.
+//
+// Per-attribute compression handling: Position is always
+// uncompressed (one entry per vertex, vertex_count*3 words). For
+// Normal and Tangent, the meshlet flags say whether they were
+// collapsed to a single shared entry across all vertices. Per-vertex
+// skinning into a shared slot would race, so the shader skips the
+// write for any attribute where the flag is set — the cloned slot
+// keeps the source's value and lighting on those vertices uses an
+// undeformed direction. For typical character meshes
+// normals/tangents vary per vertex and so don't get the all-equal
+// collapse, so this skip rarely engages in practice.
+//
+// SkinningJoints + SkinningWeights are read-only here. They CAN be
+// compressed — a meshlet where every vertex shares the same joint
+// palette (e.g. simple test meshes that bind every vertex to the
+// same two bones) collapses Joints to one shared u32-pair, and the
+// shader then has to broadcast that single entry across all vertex
+// reads instead of striding by 2 words per vertex. Same logic for
+// Weights (less common in practice — weights usually vary per
+// vertex even on simple meshes — but the flag handling is free).
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(${SKINNING_WORKGROUP_SIZE},1,1)
+fn main(
+    @builtin(workgroup_id) wg_id: vec3<u32>,
+    @builtin(local_invocation_index) local_id: u32,
+) {
+    // dispatch_offset lets the host paginate large dispatches —
+    // WebGPU's per-dimension cap is 65535 workgroups, but a busy
+    // scene's (binding, meshlet) pair total can exceed that.
+    let pair_index = wg_id.x + dispatch_offset;
+    let lookup_base = pair_index * 2u;
+    let binding_index = dispatch_lookup[lookup_base];
+    let meshlet_local = dispatch_lookup[lookup_base + 1u];
+
+    let binding = skinning_bindings[binding_index];
+
+    // The glTF skinning formula's leftmost factor is
+    // inverse(meshNode.worldMatrix), which lands the per-vertex
+    // output in mesh-local space ready for the rasterizer's
+    // mesh.world re-application (see
+    // chunk_mesh_resolve_vertex_position_world.js). It goes into
+    // each *matrix*, not onto the blended position — see
+    // chunk_skin_blend_mesh_local for why the difference is the
+    // whole ball game. Both positions and directions therefore come
+    // out of the blend already in mesh-local space, and the
+    // rasterizer's own transforms take them to world.
+    //
+    // mesh_instance_index is the row of the SkinnedMesh in the
+    // meshes table; mesh.node is its transforms-table row.
+    // Workgroup-uniform (one binding per workgroup), so the load +
+    // inverse amortize across every vertex this workgroup
+    // processes.
+    let mesh = scene_read_mesh(&scene_database, binding.mesh_instance_index);
+    let mesh_node = scene_read_node(&scene_database, mesh.node);
+    let inv_mesh_world = mat4_inverse(mesh_node.global);
+
+    let source_meshlet = meshlet_metadata[binding.source_meshlet_metadata_offset + meshlet_local];
+    let clone_meshlet  = meshlet_metadata[binding.clone_meshlet_metadata_offset + meshlet_local];
+
+    let vertex_count = source_meshlet.vertex_count;
+
+    // Both source and clone share an attribute layout (the clone is a
+    // memcpy of the source's bytes with addresses patched), so attribute
+    // offsets relative to each meshlet's attribute section are identical.
+    let source_attr_section = meshlet_compute_attribute_section_offset(source_meshlet);
+    let clone_attr_section  = meshlet_compute_attribute_section_offset(clone_meshlet);
+
+    // Walk the per-attribute layout, capturing the offset of each
+    // attribute we'll need. Order matches ENCODED_ORDERED_ATTRIBUTES:
+    // Position, Normal, Tangent, Color, UV0, UV1, SkinningJoints,
+    // SkinningWeights. Conditional skips for the compressible ones —
+    // when collapsed, the slot is a single shared entry rather than
+    // vertex_count entries.
+    let position_offset = 0u;
+    var attr_offset: u32 = vertex_count * 3u;
+
+    let normal_offset = attr_offset;
+    let normal_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_NORMAL}u) != 0u;
+    attr_offset = attr_offset + select(vertex_count, 1u, normal_compressed);
+
+    let tangent_offset = attr_offset;
+    let tangent_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_TANGENT}u) != 0u;
+    attr_offset = attr_offset + select(vertex_count, 1u, tangent_compressed);
+
+    let color_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_COLOR}u) != 0u;
+    attr_offset = attr_offset + select(vertex_count, 1u, color_compressed);
+
+    let uv0_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_TEXTURE_COORDINATES_0}u) != 0u;
+    attr_offset = attr_offset + select(vertex_count * 2u, 2u, uv0_compressed);
+
+    let uv1_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_TEXTURE_COORDINATES_1}u) != 0u;
+    attr_offset = attr_offset + select(vertex_count, 1u, uv1_compressed);
+
+    let joints_offset = attr_offset;
+    let joints_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_SKINNING_JOINTS}u) != 0u;
+    attr_offset = attr_offset + select(vertex_count * 2u, 2u, joints_compressed);
+
+    let weights_offset = attr_offset;
+    let weights_compressed = (source_meshlet.flags & ${MESHLET_METADATA_FLAGS.ATTRIBUTE_COMPRESSED_SKINNING_WEIGHTS}u) != 0u;
+
+    let skin_base = binding.skin_matrix_offset;
+
+    // Resolve the clone meshlet's per-meshlet base offset in the
+    // prev_positions side-buffer (or sentinel if this meshlet
+    // somehow isn't a clone — shouldn't happen in practice since
+    // the skinning shader only runs on (clone, skinned) pairs, but
+    // the check costs one load and one branch). Lifted out of the
+    // vertex loop because it's per-meshlet, not per-vertex.
+    let clone_meshlet_abs = binding.clone_meshlet_metadata_offset + meshlet_local;
+    let prev_pos_meshlet_base = prev_position_offsets[clone_meshlet_abs];
+    let has_prev_positions = prev_pos_meshlet_base != 0xFFFFFFFFu;
+
+    // Stride loop — one thread per WORKGROUP_SIZE-stride'd vertex slot.
+    // Most meshlets fit in a single iteration (vertex_count <=
+    // WORKGROUP_SIZE); larger ones cycle the workgroup over them.
+    var v: u32 = local_id;
+    loop {
+        if v >= vertex_count { break; }
+
+        // Joint indices: vec4<u16> packed into 2 u32s. When the
+        // attribute is compressed (every vertex of this meshlet
+        // shares the same palette), there's one shared pair at
+        // joints_offset rather than per-vertex strides; broadcast
+        // that single entry to every thread.
+        let joints_local_offset = select(v * 2u, 0u, joints_compressed);
+        let joints_addr = source_attr_section + joints_offset + joints_local_offset;
+        let raw_j0 = meshlet_data[joints_addr];
+        let raw_j1 = meshlet_data[joints_addr + 1u];
+        let j0 = raw_j0 & 0xFFFFu;
+        let j1 = (raw_j0 >> 16u) & 0xFFFFu;
+        let j2 = raw_j1 & 0xFFFFu;
+        let j3 = (raw_j1 >> 16u) & 0xFFFFu;
+
+        // Joint weights: vec4<unorm8> packed into 1 u32. Half the
+        // bandwidth of the previous f16×4 layout, sufficient
+        // precision for typical character skinning (step size
+        // ~0.4%, well under any visible artefact threshold).
+        // unpack4x8unorm returns vec4<f32> in [0, 1] with
+        // components matching byte 0..3 of the packed u32.
+        let weights_local_offset = select(v, 0u, weights_compressed);
+        let weights_addr = source_attr_section + weights_offset + weights_local_offset;
+        let weights = unpack4x8unorm(meshlet_data[weights_addr]);
+
+        // Build per-joint dual quaternions from the joint matrices, then
+        // blend with antipodal correction. The result represents the
+        // weighted-average screw motion the four matrices encode.
+        let dq_blend = skin_blend_mesh_local(
+            inv_mesh_world,
+            skin_matrices[skin_base + j0],
+            skin_matrices[skin_base + j1],
+            skin_matrices[skin_base + j2],
+            skin_matrices[skin_base + j3],
+            weights,
+        );
+
+        // Position: full screw motion (rotation + translation).
+        let pos_addr = source_attr_section + position_offset + v * 3u;
+        let p = vec3f(
+            bitcast<f32>(meshlet_data[pos_addr]),
+            bitcast<f32>(meshlet_data[pos_addr + 1u]),
+            bitcast<f32>(meshlet_data[pos_addr + 2u]),
+        );
+        // Position: full screw motion, already mesh-local — the
+        // rasterizer reapplies mesh.world to every mesh's vertices,
+        // skinned or not.
+        let p_skinned = dual_quat_transform_point(dq_blend, p);
+
+        let clone_pos_addr = clone_attr_section + position_offset + v * 3u;
+        meshlet_data[clone_pos_addr]      = bitcast<u32>(p_skinned.x);
+        meshlet_data[clone_pos_addr + 1u] = bitcast<u32>(p_skinned.y);
+        meshlet_data[clone_pos_addr + 2u] = bitcast<u32>(p_skinned.z);
+
+        // Previous-frame mesh-local position: same dual-quat math,
+        // but driven by prev_skin_matrices instead of skin_matrices.
+        // Written to the side-buffer at the per-meshlet base
+        // offset + v * 3 u32 words. The velocity post-pass reads
+        // these to interpolate per-vertex skin deformation across
+        // the rasterized triangle (vs. just the rigid mesh.global
+        // → mesh.prev_global delta that Stage 1's path captures).
+        //
+        // Skipping the write when there's no slot for this meshlet
+        // (non-clone — shouldn't be hit by this shader's dispatch
+        // set, but the guard is cheap). The dual-quat build is
+        // also skipped to save the per-joint work.
+        if has_prev_positions {
+            // Mesh-local for the same reason the current-frame
+            // position is — the velocity pass reads these through
+            // the same rasterizer transform, so the space they live
+            // in has to match.
+            let prev_dq_blend = skin_blend_mesh_local(
+                inv_mesh_world,
+                prev_skin_matrices[skin_base + j0],
+                prev_skin_matrices[skin_base + j1],
+                prev_skin_matrices[skin_base + j2],
+                prev_skin_matrices[skin_base + j3],
+                weights,
+            );
+
+            let p_prev_skinned = dual_quat_transform_point(prev_dq_blend, p);
+
+            let prev_addr = prev_pos_meshlet_base + v * 3u;
+            prev_positions[prev_addr]      = bitcast<u32>(p_prev_skinned.x);
+            prev_positions[prev_addr + 1u] = bitcast<u32>(p_prev_skinned.y);
+            prev_positions[prev_addr + 2u] = bitcast<u32>(p_prev_skinned.z);
+        }
+
+        // Normal: rotation only. Skip when the source compressed it
+        // down to a single shared slot — per-vertex writes to that
+        // slot would race, and the rotated direction would be
+        // mostly-meaningless anyway since every vertex would compute
+        // a different one.
+        //
+        // Mesh-local like the position, and left there: the
+        // rasterizer applies the inverse-transpose of mesh.world's
+        // 3x3 to it, which is the glTF normal transform and takes a
+        // mesh-local direction to world (see fragment_gbuffer.js).
+        if !normal_compressed {
+            let n_raw_addr = source_attr_section + normal_offset + v;
+            let n = decode_vertex_normal(meshlet_data[n_raw_addr]);
+            let n_skinned = normalize(dual_quat_transform_direction(dq_blend, n));
+
+            let clone_n_addr = clone_attr_section + normal_offset + v;
+            meshlet_data[clone_n_addr] = encode_vertex_normal(n_skinned);
+        }
+
+        // Tangent: rotation only on the xyz; w (handedness) is a
+        // topological property, copied through unchanged.
+        if !tangent_compressed {
+            let t_raw_addr = source_attr_section + tangent_offset + v;
+            let t = decode_vertex_tangent(meshlet_data[t_raw_addr]);
+            let t_skinned_dir = normalize(dual_quat_transform_direction(dq_blend, t.xyz));
+
+            let clone_t_addr = clone_attr_section + tangent_offset + v;
+            meshlet_data[clone_t_addr] = encode_vertex_tangent(vec4f(t_skinned_dir, t.w));
+        }
+
+        v = v + ${SKINNING_WORKGROUP_SIZE}u;
+    }
+}
+`, [
+        MESHLET_METADATA_STRUCT.declaration_chunk,
+        SKINNING_BINDING_STRUCT.declaration_chunk,
+        chunk_meshlet_compute_attribute_section_offset,
+        chunk_skin_blend_mesh_local,
+        chunk_dual_quat_transform_point,
+        chunk_dual_quat_transform_direction,
+        chunk_decode_vertex_normal,
+        chunk_encode_vertex_normal,
+        chunk_decode_vertex_tangent,
+        chunk_encode_vertex_tangent,
+        chunk_scene_database_access,
+        chunk_mat4_inverse,
+    ]
+);
+
+/**
+ * Compute shader that deforms cloned meshlet vertex regions in place
+ * using the per-frame skin matrices the prep pass produced. One
+ * workgroup per (binding, meshlet) pair, dispatched against a flat
+ * `dispatch_lookup` table the host builds when bindings change.
+ *
+ * Skins position (full transform) plus normal and tangent (rotation
+ * only) per vertex via dual-quaternion blending — the blended DQ
+ * captures the four per-vertex joints' screw motions weighted by
+ * the per-vertex `SkinningWeights`, and applies cleanly to both
+ * positions and unit-direction attributes without the matrix-blend
+ * candy-wrapper artifacts that would otherwise show up in the
+ * normal-transformed lighting.
+ *
+ * Source bytes stay untouched — other instances pointed at the
+ * source render normally. Per-meshlet bounds aren't refreshed by
+ * this pass; meshlets that animate outside the source bounds may
+ * cull incorrectly until a future bounds-refresh phase lands.
+ *
+ * Dispatch via `shader.dispatch({ group_count_x: total_meshlet_count, ... })`
+ * where `total_meshlet_count` is the sum of `meshlet_count` across
+ * every registered binding. Skip when `total_meshlet_count === 0`.
+ */
+export const shader_meshlet_apply_skinning = ComputeShader.from({
+    label: "Skinning/MeshletApplySkinning",
+    resources,
+    body,
+});