Update the code snippets to better match the example code. Where it doesn't explain why it doesn't.

Author: gpx1000

en/Advanced_glTF/Debugging_Visual_Auditing/02_debug_drawers.adoc

@@ -274,7 +274,7 @@ void draw_bone_bodies(
                         ? DYNAMIC_COLOR
                         : KINEMATIC_COLOR;
 
-        glm::mat4 body_transform = pose_to_matrix(pose);
+        glm::mat4 body_transform = pose.to_matrix();
 
         const ColliderDef& def = bone_body.collider_def;
         if (def.shape == ColliderDef::Shape::CAPSULE) {
@@ -293,20 +293,25 @@ void draw_bone_bodies(
 }
 ----
 
-For physics constraints, most physics engines provide a query API to retrieve the constraint's anchor points and axis direction. Drawing a constraint as a line between its two anchor points plus a small indicator for the constraint axis gives you enough information to visually verify that the constraint setup is correct:
+For physics constraints, the `PhysicsWorld` interface does not expose a generic constraint query API, since constraint introspection is highly engine-specific in Jolt. The code below is **pseudocode** showing the pattern you would implement by casting your constraint handles to the concrete Jolt type (`JPH::Constraint*`) and reading `mPoint1`, `mHingeAxis1`, etc. directly:
 
 [source,cpp]
 ----
+// PSEUDOCODE — illustrates the pattern; get_constraint_debug_info() is not part
+// of the PhysicsWorld interface. Implement by casting to JPH::SwingTwistConstraint*
+// or JPH::HingeConstraint* and reading Jolt-specific members directly.
+
 const glm::vec3 CONSTRAINT_COLOR = { 0.0f, 0.5f, 1.0f }; // Blue for constraints
 const glm::vec3 LIMIT_COLOR      = { 1.0f, 0.0f, 1.0f }; // Magenta for limits
 
 void draw_constraints(
     DebugDrawer&              drawer,
-    const PhysicsWorld&       physics_world,
     const std::vector<void*>& constraint_handles)
 {
     for (void* constraint : constraint_handles) {
-        ConstraintDebugInfo info = physics_world.get_constraint_debug_info(constraint);
+        // Cast to the concrete Jolt type and extract anchor/axis data
+        // (ConstraintDebugInfo is a project-specific helper struct, not part of Jolt)
+        ConstraintDebugInfo info = extract_constraint_debug_info(constraint);
 
         // Draw a line connecting the two constraint anchor points
         drawer.draw_line(info.anchor_a, info.anchor_b, CONSTRAINT_COLOR);

en/Advanced_glTF/Debugging_Visual_Auditing/03_skinning_heatmaps.adoc

@@ -15,61 +15,67 @@ The heatmap is rendered by replacing the standard PBR fragment shader with a dia
 
 [source,slang]
 ----
-// Vertex shader: pass through position and skinning attributes
-struct VertexOut {
-    float4     position  : SV_Position;
-    float4     weights   : TEXCOORD0;  // The four bone weights
-    uint4      joints    : TEXCOORD1;  // The four bone indices
-};
+// Camera data — declared as a push constant for simplicity.
+struct CameraPushConstants { float4x4 view_proj; };
+[[vk::push_constant]] CameraPushConstants camera;
 
-// Vertex input mirrors the InputVertex layout
-struct InputVertex {
+// Vertex data without embedded joint indices/weights —
+// joint data is stored in separate parallel buffers (same pattern as skinning.slang).
+struct Vertex {
     float3 position;
     float3 normal;
     float4 tangent;
     float2 texcoord;
-    uint4  joint_indices;
-    float4 joint_weights;
 };
 
-[[vk::binding(0, 0)]] StructuredBuffer<InputVertex>    vertices;
-[[vk::binding(1, 0)]] StructuredBuffer<float4x4>     joint_matrices;
-[[vk::binding(2, 0)]] StructuredBuffer<float4>       joint_colors; // One color per joint
+// Five bindings: vertex geometry, joint matrices, joint indices, joint weights, joint colors.
+[[vk::binding(0, 0)]] StructuredBuffer<Vertex>    vertices;
+[[vk::binding(1, 0)]] StructuredBuffer<float4x4>  joint_matrices;  // For world position
+[[vk::binding(2, 0)]] StructuredBuffer<uint4>     joint_indices;
+[[vk::binding(3, 0)]] StructuredBuffer<float4>    joint_weights;
+[[vk::binding(4, 0)]] StructuredBuffer<float4>    joint_colors;   // One RGBA per joint
+
+// Vertex shader passes joint data to the fragment stage for coloring.
+struct VertexOut {
+    float4 position : SV_Position;
+    float4 weights  : TEXCOORD0;
+    uint4  joints   : TEXCOORD1;
+};
 
 [shader("vertex")]
 VertexOut vertex_main(uint vertex_id : SV_VertexID)
 {
-    InputVertex v = vertices[vertex_id];
+    Vertex v   = vertices[vertex_id];
+    uint4 j_idx = joint_indices[vertex_id];
+    float4 j_w  = joint_weights[vertex_id];
 
-    // Apply skinning to get world position (same as Chapter 3)
+    // Apply skinning to get world position (same LBS as skinning.slang)
     float4x4 skin_matrix =
-        v.joint_weights.x * joint_matrices[v.joint_indices.x] +
-        v.joint_weights.y * joint_matrices[v.joint_indices.y] +
-        v.joint_weights.z * joint_matrices[v.joint_indices.z] +
-        v.joint_weights.w * joint_matrices[v.joint_indices.w];
+        j_w.x * joint_matrices[j_idx.x] +
+        j_w.y * joint_matrices[j_idx.y] +
+        j_w.z * joint_matrices[j_idx.z] +
+        j_w.w * joint_matrices[j_idx.w];
 
     VertexOut out;
     out.position = mul(camera.view_proj, mul(skin_matrix, float4(v.position, 1.0)));
-    out.weights  = v.joint_weights;
-    out.joints   = v.joint_indices;
+    out.weights  = j_w;
+    out.joints   = j_idx;
     return out;
 }
 
-// Fragment shader: colorize by dominant joint
-// Each joint gets a unique color from a lookup table.
+// Colors each pixel by the dominant (highest-weight) joint using a per-joint color table.
 [shader("fragment")]
 float4 fragment_dominant_bone(VertexOut input) : SV_Target
 {
-    // Find the joint with the highest weight
-    uint   dominant_joint = 0;
-    float  max_weight     = input.weights.x;
+    uint  dominant = 0;
+    float max_w    = input.weights.x;
 
-    if (input.weights.y > max_weight) { max_weight = input.weights.y; dominant_joint = 1; }
-    if (input.weights.z > max_weight) { max_weight = input.weights.z; dominant_joint = 2; }
-    if (input.weights.w > max_weight) { max_weight = input.weights.w; dominant_joint = 3; }
+    if (input.weights.y > max_w) { max_w = input.weights.y; dominant = 1; }
+    if (input.weights.z > max_w) { max_w = input.weights.z; dominant = 2; }
+    if (input.weights.w > max_w) { max_w = input.weights.w; dominant = 3; }
 
-    uint actual_joint_idx = input.joints[dominant_joint];
-    return joint_colors[actual_joint_idx];
+    uint actual_joint = input.joints[dominant];
+    return joint_colors[actual_joint];
 }
 ----
 

en/Advanced_glTF/Morph_Targets_Facial_Animation/02_shape_key_ingestion.adoc

@@ -215,9 +215,10 @@ A common pattern is to maintain a per-mesh `std::vector<float>` of morph weights
 [source,cpp]
 ----
 struct MorphWeightBlock {
-    float weights[64]; // Support up to 64 active morph targets
-    uint32_t active_count;
-    uint32_t _pad[3];
+    float    weights[24];     // Up to 24 active morph targets
+    uint32_t activeCount;     // How many entries in weights[] are valid
+    uint32_t applySkinning;   // 1 = also apply skeletal skinning, 0 = morph only
+    uint32_t pad[2];          // Align to 16 bytes
 };
 ----
 

en/Advanced_glTF/Morph_Targets_Facial_Animation/03_bindless_morph_buffers.adoc

@@ -191,30 +191,39 @@ Here is the extended shader in Slang. The key additions are the `morphTargets` b
 
 [source,slang]
 ----
-// Bindless array of morph target displacement buffers.
-// Each buffer contains one vec3 per vertex in the mesh.
-[[vk::binding(0, 1)]]
-StructuredBuffer<float3> morphTargets[];
+// morph_accumulate.slang — combines morph target accumulation with skeletal skinning.
+// Requires: VK_EXT_descriptor_indexing, runtimeDescriptorArray.
 
-// Weights for the currently active morph targets.
+// Same C-array struct layout as skinning.slang (matches GPU buffer memory layout).
+struct InputVertex  { float p[3]; float n[3]; float uv[2]; float t[4]; };
+struct OutputVertex { float p[3]; float n[3]; float uv[2]; float t[4]; };
+
+// Set 0: per-mesh buffers (same 5-binding layout as the base skinning shader)
+[[vk::binding(0, 0)]] StructuredBuffer<InputVertex>    base_vertices;
+[[vk::binding(1, 0)]] RWStructuredBuffer<OutputVertex> output_vertices;
+[[vk::binding(2, 0)]] StructuredBuffer<float4x4>       joint_matrices;
+[[vk::binding(3, 0)]] StructuredBuffer<uint4>          joint_indices;
+[[vk::binding(4, 0)]] StructuredBuffer<float4>         joint_weights;
+
+// Set 1: runtime-length array of morph delta buffers (one StructuredBuffer per target).
+// MorphDelta uses a C-array to match GPU buffer layout.
+struct MorphDelta { float d[3]; };
+[[vk::binding(0, 1)]] StructuredBuffer<MorphDelta> morph_targets[];
+
+// MorphWeightBlock must match SkinPushConstants::MorphWeightBlock in renderer_advanced_types.h.
 struct MorphWeightBlock {
-    float    weights[64];
-    uint32_t active_count;
-    uint32_t pad[3];
+    float    weights[24];     // Blending weights for the active targets
+    uint32_t active_count;    // How many entries in weights[] are valid
+    uint32_t apply_skinning;  // 1 = also apply skeletal skinning, 0 = morph only
+    uint32_t pad[2];
 };
-[[vk::push_constant]]
+
 struct PushConstants {
-    // From Chapter 3: skeleton joint matrix indices
-    uint32_t vertex_count;
-    uint32_t joint_count;
-    // Morph target indices (which slots in morphTargets[] are active)
-    uint32_t morph_indices[64];
+    uint32_t         vertex_count;
+    uint32_t         morph_indices[24]; // Which descriptor slot each active target lives in
     MorphWeightBlock morph_weights;
-} pc;
-
-[[vk::binding(0, 0)]] StructuredBuffer<InputVertex>  base_vertices;
-[[vk::binding(1, 0)]] RWStructuredBuffer<OutputVertex> output_vertices;
-[[vk::binding(2, 0)]] StructuredBuffer<float4x4> joint_matrices;
+};
+[[vk::push_constant]] PushConstants pc;
 
 [shader("compute")]
 [numthreads(64, 1, 1)]
@@ -224,39 +233,55 @@ void main(uint3 dispatch_id : SV_DispatchThreadID)
     if (vertex_idx >= pc.vertex_count) return;
 
     InputVertex base = base_vertices[vertex_idx];
+    float3 base_pos = float3(base.p[0], base.p[1], base.p[2]);
+    float3 base_nrm = float3(base.n[0], base.n[1], base.n[2]);
+    float4 base_tan = float4(base.t[0], base.t[1], base.t[2], base.t[3]);
 
-    // --- Step 1: Apply morph target displacements ---
-    float3 morphed_position = base.position;
-    float3 morphed_normal   = base.normal;
+    // --- Pass 1: morph target accumulation ---
+    float3 morphed_position = base_pos;
+    float3 morphed_normal   = base_nrm;
 
     for (uint m = 0; m < pc.morph_weights.active_count; ++m) {
-        uint   target_slot = pc.morph_indices[m];
-        float  weight      = pc.morph_weights.weights[m];
-        if (weight < 1e-5f) continue;
+        float weight = pc.morph_weights.weights[m];
+        if (abs(weight) < 1e-5f) continue;
 
-        // NonUniformResourceIndex is required when indexing bindless arrays
-        // with a non-uniform value (different invocations may use different indices)
-        float3 delta = morphTargets[NonUniformResourceIndex(target_slot)][vertex_idx];
+        uint slot = pc.morph_indices[m];
+        // NonUniformResourceIndex: different threads may use different descriptor slots.
+        MorphDelta delta_raw = morph_targets[NonUniformResourceIndex(slot)][vertex_idx];
+        float3 delta = float3(delta_raw.d[0], delta_raw.d[1], delta_raw.d[2]);
         morphed_position += weight * delta;
-        // Normal deltas would go here if you have a second morphNormals[] array
     }
 
-    // --- Step 2: Skeletal skinning (same as Chapter 3) ---
-    float4x4 skin_matrix =
-        base.joint_weights.x * joint_matrices[base.joint_indices.x] +
-        base.joint_weights.y * joint_matrices[base.joint_indices.y] +
-        base.joint_weights.z * joint_matrices[base.joint_indices.z] +
-        base.joint_weights.w * joint_matrices[base.joint_indices.w];
+    // --- Pass 2: skeletal skinning (same LBS as skinning.slang) ---
+    uint4  j_idx = joint_indices[vertex_idx];
+    float4 j_w   = joint_weights[vertex_idx];
 
-    float4 world_pos = mul(skin_matrix, float4(morphed_position, 1.0));
-    float3 world_nrm = normalize(mul(float3x3(skin_matrix), morphed_normal));
+    float4x4 skin_matrix =
+        j_w.x * joint_matrices[j_idx.x] +
+        j_w.y * joint_matrices[j_idx.y] +
+        j_w.z * joint_matrices[j_idx.z] +
+        j_w.w * joint_matrices[j_idx.w];
+
+    float3x3 skin_rot = float3x3(
+        skin_matrix[0].xyz, skin_matrix[1].xyz, skin_matrix[2].xyz);
+
+    float3 final_position = morphed_position;
+    float3 final_normal   = morphed_normal;
+    float3 final_tangent  = base_tan.xyz;
+    if (pc.morph_weights.apply_skinning != 0u) {
+        final_position = mul(skin_matrix, float4(morphed_position, 1.0)).xyz;
+        final_normal   = normalize(mul(skin_rot, morphed_normal));
+        final_tangent  = normalize(mul(skin_rot, base_tan.xyz));
+    }
 
-    // Write to output buffer (shared with rasterizer, ray tracing, physics)
+    // Write to output buffer element-by-element (C-array structs require this).
     OutputVertex out;
-    out.position = world_pos.xyz;
-    out.normal   = world_nrm;
-    out.tangent  = base.tangent;
-    out.texcoord = base.texcoord;
+    out.p[0] = final_position.x;  out.p[1] = final_position.y;  out.p[2] = final_position.z;
+    out.n[0] = final_normal.x;    out.n[1] = final_normal.y;    out.n[2] = final_normal.z;
+    out.t[0] = final_tangent.x;   out.t[1] = final_tangent.y;
+    out.t[2] = final_tangent.z;   out.t[3] = base_tan.w;
+    out.uv[0] = base.uv[0];       out.uv[1] = base.uv[1];
+
     output_vertices[vertex_idx] = out;
 }
 ----
@@ -273,7 +298,7 @@ The morph system integrates into the frame loop naturally:
 4. **Dispatch.** Bind the descriptor set (which has all morph target buffers registered), push constants, and dispatch the compute shader. One thread per vertex.
 5. **Barrier.** Issue a `VkBufferMemoryBarrier2` on the output buffer (same as Chapter 3) before the rasterizer or ray tracing pass reads from it.
 
-The only part that requires care is the per-frame push constant size. If you have up to 64 active morph targets, the push constants become large—64 indices (256 bytes) plus 64 weights (256 bytes) plus metadata equals over 512 bytes. The Vulkan specification guarantees a minimum of 128 bytes of push constant space, but most desktop GPUs support 256 bytes, and high-end GPUs support 256 bytes or more. If you exceed the available push constant space, move the weight data into a small uniform buffer instead.
+The only part that requires care is the per-frame push constant size. With up to 24 active morph targets, `PushConstants` contains 24 indices (96 bytes) plus `MorphWeightBlock` with 24 weights (96 bytes) plus metadata — roughly 200 bytes total. The Vulkan specification guarantees a minimum of 128 bytes of push constant space, but most desktop GPUs support 256 bytes or more. The 24-target cap was chosen to stay within that budget. If you need more simultaneous targets, move the weight data into a small uniform buffer instead.
 
 == Morph Targets and Skeletal Rigs Together