[xrAnimation] Implement true GPU instancing for bone rendering

Replaced CPU-side per-bone geometry generation with proper GPU instancing:

**Before:**
- Generated ~37,000+ vertices CPU-side every frame
- 47 bones × (24 octahedron verts + 2 spheres × 384 verts each)
- Heavy CPU load, inefficient memory transfers

**After (True GPU Instancing):**
- Generate unit geometry ONCE at initialization:
  - Unit octahedron: 24 vertices (generated once)
  - Unit sphere: ~384 vertices (generated once)
- Per-frame: Only upload 47 transform matrices + colors (InstanceData)
- GPU draws: 2 draw calls total (one for octahedrons, one for spheres)

**Performance Improvement:**
- Vertex data uploaded: ~37,000 verts → 408 verts (unit geometry)
- Per-frame uploads: 47 × 80 bytes = 3,760 bytes (transforms + colors only)
- Draw calls: Same bone shape rendered 47 times with ONE draw call

**Implementation Details:**

1. **New Shaders** (src/xrAnimation/tools/renderer/shaders/bone_instanced.{vert,frag}):
   - Per-vertex: position + normal (unit geometry)
   - Per-instance: mat4 transform + vec4 color

2. **Unit Geometry Generation** (GenerateUnitOctahedron/GenerateUnitSphere):
   - Called once in Initialize()
   - Stored in GPU buffers permanently

3. **Instance Buffer Management**:
   - Uploads per-instance transforms + colors each frame
   - Combined buffer for bones and spheres (drawn with different firstInstance)

4. **Instanced Draw Calls**:
   - vkCmdDraw(cmd, unit_octahedron_vertex_count, bone_count, 0, 0)
   - vkCmdDraw(cmd, unit_sphere_vertex_count, sphere_count, 0, bone_count)

**Files Changed:**
- src/xrAnimation/tools/renderer/DebugRenderer.{h,cpp}: GPU instancing implementation
- src/xrAnimation/tools/renderer/shaders/bone_instanced.{vert,frag}: Instanced shaders
- src/xrAnimation/tools/CMakeLists.txt: Added shader compilation for bone_instanced

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: yohjimane

src/xrAnimation/AnimationECS_Components.h

@@ -251,6 +251,9 @@ struct SkeletonMetadata
     // Skeleton hierarchy (parent indices, -1 for roots)
     std::vector<int> joint_parents;
 
+    // Pre-computed children per joint (for O(1) child lookup instead of O(N) linear search)
+    std::vector<std::vector<int>> joint_children;
+
     // Extended bone metadata (physics shapes, IK constraints, rest lengths, etc.)
     XRay::Animation::ExtendedBoneMetadataCollection metadata;
 
@@ -265,9 +268,26 @@ struct SkeletonMetadata
     void Clear()
     {
         joint_parents.clear();
+        joint_children.clear();
         metadata.clear();
         skeleton = nullptr;
     }
+
+    // Build the joint_children map from joint_parents (call after populating joint_parents)
+    void BuildChildrenMap()
+    {
+        joint_children.clear();
+        joint_children.resize(joint_parents.size());
+
+        for (size_t i = 0; i < joint_parents.size(); ++i)
+        {
+            int parent = joint_parents[i];
+            if (parent >= 0 && static_cast<size_t>(parent) < joint_children.size())
+            {
+                joint_children[parent].push_back(static_cast<int>(i));
+            }
+        }
+    }
 };
 
 } // namespace AnimationECS

src/xrAnimation/AnimationECS_DebugRender.cpp

@@ -47,19 +47,17 @@ void SkeletonDebugRenderSystem::Render(entt::registry& registry, IDebugDrawConte
             buffers.models.begin(), buffers.models.end());
 
         // Render this skeleton instance
-        RenderSkeleton(ctx, pose_models, metadata.joint_parents,
-                      inst_transform.world_transform, debug_state,
-                      metadata.metadata);
+        RenderSkeleton(ctx, pose_models, metadata,
+                      inst_transform.world_transform, debug_state);
     }
 }
 
 void SkeletonDebugRenderSystem::RenderSkeleton(
     IDebugDrawContext& ctx,
     const std::vector<ozz::math::Float4x4>& pose_models,
-    const std::vector<int>& skeleton_parents,
+    const SkeletonMetadata& skeleton_metadata,
     const ozz::math::Float4x4& instance_transform,
-    const SkeletonDebugState& debug_state,
-    const XRay::Animation::ExtendedBoneMetadataCollection& bone_metadata)
+    const SkeletonDebugState& debug_state)
 {
     if (pose_models.empty())
         return;
@@ -70,6 +68,11 @@ void SkeletonDebugRenderSystem::RenderSkeleton(
     const ozz::math::Float4 joint_color{0.92f, 0.35f, 0.35f, 0.65f}; // Red-orange
     const ozz::math::Float4 link_color{0.65f, 0.65f, 0.95f, 0.55f};  // Purple-blue
 
+    // Get references for easier access
+    const auto& skeleton_parents = skeleton_metadata.joint_parents;
+    const auto& joint_children = skeleton_metadata.joint_children;
+    const auto& bone_metadata = skeleton_metadata.metadata;
+
     // Lambda to compute rest length as fallback
     auto compute_rest_length = [&](int bone_index) -> float
     {
@@ -90,10 +93,10 @@ void SkeletonDebugRenderSystem::RenderSkeleton(
         if (result > kSkeletonDebugEpsilon)
             return result;
 
-        // Try child distance
-        for (size_t child = 0; child < skeleton_parents.size(); ++child)
+        // Try child distance using pre-computed children (O(1) instead of O(N))
+        if (bone_index < static_cast<int>(joint_children.size()))
         {
-            if (skeleton_parents[child] == bone_index)
+            for (int child : joint_children[bone_index])
             {
                 result = std::max(result, DistanceBetween(
                     pose_models[bone_index], pose_models[child]));
@@ -103,7 +106,17 @@ void SkeletonDebugRenderSystem::RenderSkeleton(
         return result;
     };
 
-    // Render each bone
+    // Collect all bone instances for batched rendering
+    std::vector<IDebugDrawContext::BoneInstance> bone_instances;
+    bone_instances.reserve(pose_models.size());
+
+    std::vector<IDebugDrawContext::SphereInstance> sphere_instances;
+    if (debug_state.show_joint_positions)
+    {
+        sphere_instances.reserve(pose_models.size() * 2);  // head + tail per bone
+    }
+
+    // First pass: collect all instances and draw lines
     for (size_t bone = 0; bone < pose_models.size(); ++bone)
     {
         const ozz::math::Float4x4& pose_transform = pose_models[bone];
@@ -147,17 +160,16 @@ void SkeletonDebugRenderSystem::RenderSkeleton(
         ozz::math::Float3 tail_position = bone_position;
         bool has_child = false;
 
-        // Find first child
-        for (size_t child = 0; child < skeleton_parents.size(); ++child)
+        // Find first child using pre-computed children map (O(1) instead of O(N))
+        if (bone < joint_children.size())
         {
-            if (skeleton_parents[child] == static_cast<int>(bone) &&
-                child < pose_models.size())
+            const auto& children = joint_children[bone];
+            if (!children.empty() && static_cast<size_t>(children[0]) < pose_models.size())
             {
                 const ozz::math::Float4x4 child_world =
-                    instance_transform * pose_models[child];
+                    instance_transform * pose_models[children[0]];
                 tail_position = ExtractTranslation(child_world);
                 has_child = true;
-                break;
             }
         }
 
@@ -208,15 +220,26 @@ void SkeletonDebugRenderSystem::RenderSkeleton(
             kSkeletonDefaultRadius * 0.4f,
             bone_length * 0.45f);
 
-        // Draw bone shape
-        const ozz::math::Float4 draw_color = (bone == 0) ? root_color : bone_color;
-        ctx.DrawBoneShape(bone_position, tail_position, joint_radius, draw_color);
+        // Collect bone instance for batched rendering
+        IDebugDrawContext::BoneInstance bone_inst;
+        bone_inst.head = bone_position;
+        bone_inst.tail = tail_position;
+        bone_inst.radius = joint_radius;
+        bone_inst.color = (bone == 0) ? root_color : bone_color;
+        bone_instances.push_back(bone_inst);
 
-        // Draw joint spheres
+        // Collect joint sphere instances if enabled
         if (debug_state.show_joint_positions)
         {
-            ctx.DrawSphere(bone_position, joint_radius, joint_color, 24);
-            ctx.DrawSphere(tail_position, joint_radius * 0.6f, joint_color, 24);
+            IDebugDrawContext::SphereInstance sphere_inst;
+            sphere_inst.center = bone_position;
+            sphere_inst.radius = joint_radius;
+            sphere_inst.color = joint_color;
+            sphere_instances.push_back(sphere_inst);
+
+            sphere_inst.center = tail_position;
+            sphere_inst.radius = joint_radius * 0.6f;
+            sphere_instances.push_back(sphere_inst);
         }
 
         // Draw axes at root bone
@@ -231,6 +254,17 @@ void SkeletonDebugRenderSystem::RenderSkeleton(
                 ozz::math::Float4{0.3f, 0.6f, 1.0f, 1.0f}); // Blue Z
         }
     }
+
+    // Second pass: render all collected instances in batches
+    if (!bone_instances.empty())
+    {
+        ctx.DrawBoneShapesInstanced(bone_instances.data(), bone_instances.size());
+    }
+
+    if (!sphere_instances.empty())
+    {
+        ctx.DrawSpheresInstanced(sphere_instances.data(), sphere_instances.size());
+    }
 }
 
 float SkeletonDebugRenderSystem::ComputeRestLength(

src/xrAnimation/AnimationECS_DebugRender.h

@@ -73,17 +73,15 @@ class SkeletonDebugRenderSystem
     /// </summary>
     /// <param name="ctx">Debug draw context</param>
     /// <param name="pose_models">Model-space transforms for each joint (current pose)</param>
-    /// <param name="skeleton_parents">Parent indices for each joint (-1 for roots)</param>
+    /// <param name="skeleton_metadata">Skeleton hierarchy, children map, and extended metadata</param>
     /// <param name="instance_transform">World transform for this instance</param>
     /// <param name="debug_state">Visualization settings</param>
-    /// <param name="bone_metadata">Extended metadata collection</param>
     static void RenderSkeleton(
         IDebugDrawContext& ctx,
         const std::vector<ozz::math::Float4x4>& pose_models,
-        const std::vector<int>& skeleton_parents,
+        const SkeletonMetadata& skeleton_metadata,
         const ozz::math::Float4x4& instance_transform,
-        const SkeletonDebugState& debug_state,
-        const XRay::Animation::ExtendedBoneMetadataCollection& bone_metadata);
+        const SkeletonDebugState& debug_state);
 
     /// <summary>
     /// Compute rest length for a bone (distance to parent or child).

src/xrAnimation/IDebugDrawContext.h

@@ -119,6 +119,53 @@ class IDebugDrawContext
                          const ozz::math::Float4& color_x,
                          const ozz::math::Float4& color_y,
                          const ozz::math::Float4& color_z) = 0;
+
+    // ========================================================================
+    // BATCHED/INSTANCED RENDERING API
+    // ========================================================================
+
+    /// <summary>
+    /// Instance data for bone shape rendering.
+    /// </summary>
+    struct BoneInstance {
+        ozz::math::Float3 head;     // Bone start position (joint/parent)
+        ozz::math::Float3 tail;     // Bone end position (child)
+        float radius;                // Bone thickness
+        ozz::math::Float4 color;    // RGBA color
+    };
+
+    /// <summary>
+    /// Instance data for sphere rendering.
+    /// </summary>
+    struct SphereInstance {
+        ozz::math::Float3 center;   // Sphere center position
+        float radius;                // Sphere radius
+        ozz::math::Float4 color;    // RGBA color
+    };
+
+    /// <summary>
+    /// Draw multiple bone shapes in a single batched call.
+    /// </summary>
+    /// <param name="instances">Array of bone instances to render</param>
+    /// <param name="count">Number of instances in the array</param>
+    /// <remarks>
+    /// Performance optimization: Reduces per-bone CPU overhead and consolidates
+    /// geometry generation and draw calls. Implementations should batch all bones
+    /// into a single vertex buffer and issue minimal draw calls.
+    /// </remarks>
+    virtual void DrawBoneShapesInstanced(const BoneInstance* instances, size_t count) = 0;
+
+    /// <summary>
+    /// Draw multiple spheres in a single batched call.
+    /// </summary>
+    /// <param name="instances">Array of sphere instances to render</param>
+    /// <param name="count">Number of instances in the array</param>
+    /// <remarks>
+    /// Performance optimization: Reduces per-sphere CPU overhead and consolidates
+    /// geometry generation and draw calls. Implementations should batch all spheres
+    /// into a single vertex buffer and issue minimal draw calls.
+    /// </remarks>
+    virtual void DrawSpheresInstanced(const SphereInstance* instances, size_t count) = 0;
 };
 
 } // namespace AnimationECS

src/xrAnimation/tools/CMakeLists.txt

@@ -203,6 +203,10 @@ if(_ozz_animation_viewer_supported AND Vulkan_FOUND)
         add_shader(ozz_animation_viewer shaded_bone.vert)
         add_shader(ozz_animation_viewer shaded_bone.frag)
 
+        # GPU instanced bone shaders
+        add_shader(ozz_animation_viewer bone_instanced.vert)
+        add_shader(ozz_animation_viewer bone_instanced.frag)
+
         # Skinned mesh instanced shaders
         add_shader(ozz_animation_viewer skinned_mesh_instanced.vert)
         add_shader(ozz_animation_viewer skinned_mesh_instanced.frag)

src/xrAnimation/tools/ozz_animation_viewer.cpp

@@ -2408,6 +2408,9 @@ void InitializeECSInstances(ViewerState& state, VulkanRenderer& renderer) {
                 skeleton_metadata.joint_parents[j] = static_cast<int>(parents[j]);
             }
 
+            // Build pre-computed children map for O(1) child lookups
+            skeleton_metadata.BuildChildrenMap();
+
             // Store skeleton pointer and metadata
             skeleton_metadata.skeleton = &state.skeleton;