Ozz Animation Refactor

.gitattributes

@@ -20,3 +20,6 @@
 *.PDF	 diff=astextplain
 *.rtf	 diff=astextplain
 *.RTF	 diff=astextplain
+
+# Omit scripts to avoid messing up line endings
+*.sh text eol=lf

.gitignore

@@ -22,3 +22,9 @@
 
 # exclude doxygen output
 doc/doxygen/html/*
+
+# exclude ozz_utils folder
+ozz_utils/*
+src/intermediate/*
+intermediate/*
+src/xrAnimation/tests/testdata/*

.gitmodules

@@ -28,3 +28,12 @@
 [submodule "Externals/sse2rvv"]
 	path = Externals/sse2rvv
 	url = https://github.com/pattonkan/sse2rvv.git
+[submodule "Externals/ozz-animation"]
+	path = Externals/ozz-animation
+	url = https://github.com/guillaumeblanc/ozz-animation.git
+[submodule "Externals/entt"]
+	path = Externals/entt
+	url = https://github.com/skypjack/entt.git
+[submodule "Externals/glfw"]
+	path = Externals/glfw
+	url = https://github.com/glfw/glfw.git

AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md – Assistant Quick Guide
+
+## Mission Snapshot
+- Modernise OpenXRay's animation runtime by integrating ozz-animation while keeping legacy behaviour intact.
+- xrAnimation module owns the façade around `OzzKinematics`, converter tools, parity tests, and the in-engine `.ozzx` visual.
+- Converter CLI already produces `.ozz/.ozzx` assets from legacy `.ogf/.omf`; viewer tooling validates bind pose and animation parity.
+- Minimum Viable Product is shipped: the runtime façade, converter, and bundle visual now mirror legacy behaviour for the shipped fixtures.
+
+## Active Priorities
+1. Harden the MVP: keep regression suites green, extend automation around `.ozzx` bundle loading, and react quickly to edge cases raised in gameplay smoke tests.
+2. Capture and publish lightweight telemetry comparing legacy vs. Ozz frame costs; feed the numbers back into docs and tuning guidelines.
+3. Shape the next phase (threading, GPU skinning, richer metadata) by collecting follow-up requirements and documenting the proposed roadmap.
+
+## Workflow Expectations
+- Read existing memory (docs, notes) before running commands or changing files.
+- Prefer Debug/Mixed builds for iteration; use engine containers (`xr_vector`, `shared_str`, etc.) and `Msg()` for logging.
+- After every code or doc change: rebuild the affected targets and rerun their tests without waiting for a prompt.
+- Keep responses concise, factual, and professional; update documentation immediately when behaviour changes.
+
+## Build & Test Quickstart
+- Configure (if needed): `cmake -S xray-16 -B ozz_utils -DCMAKE_BUILD_TYPE=Debug`
+- Build animation targets: `cmake --build ozz_utils --target ozz_kinematics_tests xrAnimation_converter_tests -j`
+- Run suites: `ctest --test-dir ozz_utils --output-on-failure`
+- Focused test loop: `ozz_utils/bin/Debug/ozz_kinematics_tests --gtest_filter=OzzKinematicsParity.*`
+
+## Handy Tools & Scripts
+- `convert_assets.sh` (repo root) -> regenerates sample `.ozz` skeletons/animations.
+- `xray_to_ozz_converter` CLI handles skeleton/animation/batch conversion.
+- `ozz_animation_viewer` (Debug build) can dump bind poses, JSON animation samples, and headless previews for parity checks.
+- Blender snippets in `AGENT_COMMANDS.md` extract rest-pose matrices for cross-validation when needed.
+
+## Where To Look Next
+- Detailed guidance: `src/xrAnimation/AGENT_DOCS.md`
+- Command recipes: `src/xrAnimation/AGENT_COMMANDS.md`
+- Roadmap & priorities: `src/xrAnimation/AGENT_NEXT_STEPS.md`
+- Historical context: `src/xrAnimation/CLAUDE.md`
+

CMakeLists.txt

@@ -11,6 +11,7 @@ project(OpenXRay
     HOMEPAGE_URL "https://github.com/OpenXRay/xray-16"
     LANGUAGES CXX C
 )
+include(CTest)
 
 option(BUILD_SHARED_LIBS "Build shared libraries"     ${BUILD_SHARED_LIBS_DEFAULT_VALUE})
 
@@ -21,7 +22,18 @@ option(XRAY_ENABLE_TRACY "Enable tracy profiler"      OFF)
 include(XRay.Build)
 include(XRay.Packaging)
 
+add_compile_definitions(
+    $<$<CONFIG:ReleaseMasterGold>:MASTER_GOLD>
+    $<$<NOT:$<BOOL:${BUILD_SHARED_LIBS}>>:XRAY_STATIC_BUILD>
+)
+
 add_subdirectory(Externals)
+if(BUILD_TESTING)
+    get_property(_ozz_tests DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} PROPERTY TESTS)
+    foreach(_test IN LISTS _ozz_tests)
+        set_tests_properties(${_test} PROPERTIES DISABLED TRUE)
+    endforeach()
+endif()
 add_subdirectory(src)
 add_subdirectory(res)
 add_subdirectory(misc)

COMPUTE_INFRASTRUCTURE_STATUS.md

@@ -0,0 +1,148 @@
+# Detail Manager Compute Infrastructure - Implementation Status
+
+## Completed Components
+
+### 1. GPU Data Structures (`DetailManager_Compute.h`)
+✅ **DetailInstanceGPU** (128 bytes, cache-aligned)
+- Transform data: position, scale, rotation_y
+- Rendering data: lighting (c_hemi, c_sun), object_id, vis_id, color_rgb
+- Bounding data: AABB min/max, sphere radius
+- Metadata: slot coordinates, flags, fade distance
+
+✅ **FrustumGPU** (64 bytes)
+- 6 frustum planes extracted from view-projection matrix
+
+✅ **DetailCullParams** (64 bytes)
+- Camera position/direction
+- Fade limits (start/end squared distances)
+- SSA thresholds for culling/LOD
+- Frame number for temporal effects
+
+✅ **IndirectDrawArgs**
+- Matches D3D11_DRAW_INDEXED_ARGUMENTS layout
+- `instance_count` written by compute shader
+
+### 2. Compute Shader (`detail_cull.cs`)
+✅ **Culling Pipeline** (256 threads per group)
+1. Distance culling (fade_limit_sqr)
+2. Frustum culling (sphere vs 6 planes)
+3. SSA (Screen Space Area) culling
+4. Sort into 3 visibility lists by vis_id (still/wave1/wave2)
+5. Atomic counter updates
+6. Output to UAV buffers
+
+✅ **Functions:**
+- `SphereInsidePlane()` - Plane/sphere intersection
+- `FrustumCullSphere()` - 6-plane frustum test
+- `ComputeSSA()` - Screen-space area for LOD
+
+### 3. Manager Class (`DetailManager_Compute.h`)
+✅ **DetailComputeManager**
+- Instance management (Begin/Add/End)
+- GPU buffer allocation (structured buffers, UAVs, SRVs)
+- Compute dispatch (culling pass)
+- Indirect rendering support
+- Statistics tracking
+
+✅ **GPU Resources:**
+- Instance buffer (all instances) + SRV
+- Visible indices buffers [3] + UAVs + SRVs
+- Counter buffer (atomic) + UAV
+- Indirect args buffers [3] + UAVs
+- Constant buffer (cull params)
+- Compute shader reference
+
+✅ **Utility Functions:**
+- `BuildFrustumGPU()` - Extract planes from VP matrix
+- `ConvertToGPUInstance()` - CPU SlotItem → GPU format
+
+## Next Steps
+
+### Phase 1: Implementation (Current)
+- [ ] Create `DetailManager_Compute.cpp` with buffer creation/destruction
+- [ ] Implement `CreateBuffers()` - allocate structured buffers
+- [ ] Implement `UploadInstances()` - CPU→GPU transfer
+- [ ] Implement `DispatchCulling()` - bind resources & dispatch compute
+- [ ] Implement `RenderIndirect()` - DrawIndexedInstancedIndirect calls
+- [ ] Compile shader: `detail_cull.cs` → compiled bytecode
+
+### Phase 2: Integration
+- [ ] Add compute path toggle to `DetailManager.h`
+- [ ] Integrate with existing `cache_Decompress()` to build instance list
+- [ ] Replace `UpdateVisibleM()` with compute dispatch
+- [ ] Hook into `hw_Render()` for indirect draws
+- [ ] Add console commands for enable/disable/stats
+
+### Phase 3: Testing & Optimization
+- [ ] Verify visual parity with CPU path
+- [ ] Profile GPU/CPU times
+- [ ] Benchmark instance counts (10K, 100K, 500K)
+- [ ] Tune thread group size (current: 256)
+- [ ] Add GPU timestamps for perf tracking
+
+## Architecture Benefits
+
+### Memory Efficiency
+- CPU: ~80 bytes per SlotItem (pointers, matrices, scattered data)
+- GPU: 128 bytes per instance (cache-aligned, contiguous)
+- Structured buffers avoid pre-multiplied VB/IB waste
+
+### Performance Gains
+- **Culling**: GPU parallel > CPU serial
+- **Draw Calls**: 3 indirect draws vs 100s of batched draws
+- **Bandwidth**: No constant buffer spam (64×4 float4s per batch)
+- **Scalability**: 100K+ instances possible
+
+### Flexibility
+- Easy to add Hi-Z occlusion culling (future)
+- Temporal anti-aliasing support (frame counter)
+- GPU-driven LOD selection
+- Foundation for grass state texture
+
+## File Structure
+
+```
+src/Layers/xrRender/
+├── DetailManager_Compute.h       ✅ Created (GPU structs, manager class)
+└── DetailManager_Compute.cpp     ⏳ Next (implementation)
+
+res/gamedata/shaders/r5/
+└── detail_cull.cs                ✅ Created (frustum culling)
+
+Documentation/
+├── GRASS_RENDERING_ARCHITECTURE.md   ✅ Created (design doc)
+└── COMPUTE_INFRASTRUCTURE_STATUS.md  ✅ This file
+```
+
+## Shader Compilation
+
+The compute shader needs to be compiled:
+```
+input:  res/gamedata/shaders/r5/detail_cull.cs
+output: <shader_cache>/detail_cull_cs.cso
+```
+
+Engine should auto-compile on first load, or use shader compiler tool.
+
+## Configuration
+
+Future console variables:
+```
+r_detail_compute       1/0   - Enable GPU compute path
+r_detail_compute_stats 1/0   - Show culling statistics
+r_detail_max_instances 100000 - Max instances to allocate
+```
+
+## Notes
+
+- All structures are tightly packed for GPU efficiency
+- Frustum extraction follows standard VP matrix decomposition
+- SSA calculation matches existing CPU logic for consistency
+- Vis_id splitting (0/1/2) preserves animation system
+- Indirect args allow GPU to control draw count dynamically
+
+---
+
+**Status**: Infrastructure complete, ready for implementation phase
+**Branch**: `yohji/feat/mt-detailmanager`
+**Last Updated**: 2025-10-09