From 802e97ee695de1bc8657c5cbca653bb2f13b90a8 Mon Sep 17 00:00:00 2001 From: skal Date: Mon, 9 Feb 2026 15:35:14 +0100 Subject: docs: Condense essential context files (856→599 lines) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extract detailed examples and untriaged tasks to on-demand docs. Created BACKLOG.md, ARCHITECTURE.md, CODING_STYLE.md, TOOLS_REFERENCE.md. Reduces always-loaded token budget by 30% while preserving all information. Co-Authored-By: Claude Sonnet 4.5 --- PROJECT_CONTEXT.md | 111 ++++++++++++++++++----------------------------------- 1 file changed, 37 insertions(+), 74 deletions(-) (limited to 'PROJECT_CONTEXT.md') diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 7df7587..181bffc 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -1,127 +1,90 @@ # 64k Demo Project -Goal: +## Goal - Produce a <=64k native demo binary - Same C++ codebase for Windows, macOS, Linux -Graphics: +## Graphics - WebGPU via wgpu-native - WGSL shaders - Hybrid rendering: Rasterized proxy geometry + SDF raymarching -Audio: +## Audio - 32 kHz, 16-bit stereo - Procedurally generated samples - Real-time additive synthesis from spectrograms (IDCT) - Variable tempo system with music time abstraction - Event-based pattern triggering for dynamic tempo scaling - Modifiable Loops and Patterns, w/ script to generate them (like a Tracker) -- Unified AudioEngine for lifecycle management (eliminates initialization fragility) +- Unified AudioEngine for lifecycle management -Constraints: +## Constraints - Size-sensitive - Minimal dependencies - Explicit control over all allocations -Style: +## Style - Demoscene - No engine abstractions --- -## Project Roadmap -**Note:** For detailed history of recently completed milestones, see `COMPLETED.md`. +## Current Status -### Current Status -- Audio system: Sample-accurate synchronization achieved. Uses hardware playback time as master clock. Variable tempo support integrated. **Pipeline optimized (Task #72)**: Zero heap allocations per frame, direct ring buffer writes, explicit clipping. Comprehensive test coverage maintained. +- Audio system: Sample-accurate synchronization. Hardware playback time as master clock. Variable tempo support. Pipeline optimized (Task #72): Zero heap allocations per frame, direct ring buffer writes. Comprehensive test coverage. - Build system: Optimized with proper asset dependency tracking -- Shader system: **Parameterization complete**: UniformHelper template, per-frame dynamic params, .seq syntax support. Modular with comprehensive compilation tests. **WGSL composability improved**: Common utilities extracted (`math/common_utils.wgsl`) with 12 call sites deduplicated across renderer shaders. -- 3D rendering: Hybrid SDF/rasterization with BVH acceleration and binary scene loader. **Object data loading and parsing pipeline enhanced for primitives (e.g., plane_distance).** -- Asset pipeline: Blender export script and binary scene ingestion supported -- Error handling: **Dual macro system**: `FATAL_XXX` for programming errors (abort), `CHECK_RETURN` for recoverable errors (graceful return). Messages stripped in STRIP_ALL builds. -- Testing: **32/33 tests passing (97%)** - Uniform buffer alignment fixed (Task #74). DemoEffectsTest fails due to wgpu_native library bug (not project code). +- Shader system: Parameterization complete (UniformHelper, .seq syntax). Modular with compilation tests. WGSL composability improved (`math/common_utils.wgsl`). +- 3D rendering: Hybrid SDF/rasterization with BVH acceleration and binary scene loader. Object data loading pipeline enhanced. +- Asset pipeline: Blender export script and binary scene ingestion +- Error handling: Dual macro system (`FATAL_XXX` for programming errors, `CHECK_RETURN` for recoverable errors) +- Testing: **32/33 tests passing (97%)** - DemoEffectsTest fails due to wgpu_native library bug --- + ## Next Up - **Task #5: Spectral Brush Editor** [IN PROGRESS] - - Create web-based tool for procedurally tracing audio spectrograms + - Web-based tool for procedurally tracing audio spectrograms - Replace large .spec assets with tiny C++ code (50-100× compression) - - Phase 1: C++ runtime (`spectral_brush.h/cc` - Bezier curves + Gaussian profiles) - - Phase 2: Editor UI (HTML/JS canvas, dual-layer visualization, keyboard shortcuts) - - Phase 3: File I/O (load .wav/.spec, export procedural_params.txt + C++ code) - - See `doc/SPECTRAL_BRUSH_EDITOR.md` for complete design + - See TODO.md and `doc/SPECTRAL_BRUSH_EDITOR.md` - **Visuals & Content** - - [ ] **Task #52: Procedural SDF Font**: Minimal bezier/spline set for [A-Z, 0-9] and SDF rendering - - [ ] **Task #53: Particles Shader Polish**: Improve visual quality of particles - - [ ] **Task #55: SDF Random Planes Intersection**: Implement `sdPolyhedron` (crystal/gem shapes) via plane intersection + - Task #52: Procedural SDF Font + - Task #53: Particles Shader Polish + - Task #55: SDF Random Planes Intersection - **Tooling & Optimization** - - [ ] **Task #54: Tracy Integration**: Integrate Tracy debugger for performance profiling + - Task #54: Tracy Integration --- + ## Design Docs Quick Reference For detailed documentation, use Read tool to load specific docs: -- **doc/TRACKER.md**: Audio pattern system with unit-less timing (1 unit = 4 beats). Text-based music score compiled to C++ runtime. -- **doc/3D.md**: Hybrid SDF raymarching with BVH acceleration and Position Based Dynamics physics. -- **doc/ASSET_SYSTEM.md**: Build-time asset packer with 16-byte alignment, enum-based O(1) retrieval, procedural generation support. -- **doc/BUILD.md**: Multi-platform builds (Debug/STRIP_ALL/FINAL_STRIP), cross-compilation, size reporting. -- **doc/SPECTRAL_BRUSH_EDITOR.md**: Web tool for tracing spectrograms with Bezier curves (50-100× compression). -- **doc/SEQUENCE.md**: .seq timeline format with BPM notation, priority modifiers, Gantt visualization. -- **doc/MASKING_SYSTEM.md**: Auxiliary texture registry for inter-effect screen-space partitioning. -- **doc/SCENE_FORMAT.md**: Binary scene format (SCN1) with object transforms, physics, mesh references. -- **doc/test_demo_README.md**: 16s audio/visual sync test tool with tempo variation and peak logging. -- **doc/CONTEXT_MAINTENANCE.md**: Context hygiene protocol (archive to COMPLETED.md monthly, keep Tier 1 files lean). - ---- -## Future Goals -- **Task #36: Blender Exporter**: Create script to export scenes to internal binary format. (Deprioritized) -- **Task #21: Shader Optimization** - - [ ] Use macros or code generation to factorize common WGSL code (normals, bump, lighting). - - [ ] Implement Tri-planar mapping for better procedural textures. -- [ ] **Task #18-B: GPU BVH & Shadows**: Optimize scene queries with a GPU-based BVH. -- **Phase 2: Advanced Size Optimization** - - [ ] **Task #22: Windows Native Platform**: Replace GLFW with minimal native Windows API. - - [ ] **Task #28: Spectrogram Quantization**: Quantize spectrograms to logarithmic frequency and uint16_t. - - [ ] **Task #35: CRT Replacement**: Investigation and implementation of CRT-free entry point. +- **doc/TRACKER.md**: Audio pattern system with unit-less timing +- **doc/3D.md**: Hybrid SDF raymarching with BVH acceleration +- **doc/ASSET_SYSTEM.md**: Build-time asset packer with 16-byte alignment +- **doc/BUILD.md**: Multi-platform builds (Debug/STRIP_ALL/FINAL_STRIP) +- **doc/SPECTRAL_BRUSH_EDITOR.md**: Web tool for tracing spectrograms +- **doc/SEQUENCE.md**: .seq timeline format with BPM notation +- **doc/MASKING_SYSTEM.md**: Auxiliary texture registry +- **doc/SCENE_FORMAT.md**: Binary scene format (SCN1) +- **doc/test_demo_README.md**: 16s audio/visual sync test tool +- **doc/CONTEXT_MAINTENANCE.md**: Context hygiene protocol --- -*For a detailed list of all completed tasks, see the git history.* ## Recently Completed (February 2026) -- **WGSL Uniform Buffer Validation (Task #75)** (February 9) - Standardized uniform buffer layout across all effects. Created validation tool (`validate_uniforms.py`) integrated into build. All effects now use `CommonPostProcessUniforms` (binding 2) + effect-specific params (binding 3). Added `UNIFORM_BUFFER_GUIDELINES.md`. +- **WGSL Uniform Buffer Validation (Task #75)** (Feb 9) - Standardized uniform buffer layout. Validation tool integrated into build. All effects use `CommonPostProcessUniforms` (binding 2) + effect-specific params (binding 3). Added `UNIFORM_BUFFER_GUIDELINES.md`. -- **Uniform Buffer Alignment (Task #74)** (February 9) - Fixed WGSL `vec3` alignment issues. Changed padding from `vec3` to three `f32` fields in multiple shaders. Demo runs with 0 validation errors. Test suite: 32/33 passing (97%). +- **Uniform Buffer Alignment (Task #74)** (Feb 9) - Fixed WGSL `vec3` alignment issues. Demo runs with 0 validation errors. -- **Shader Parametrization (Task #73)** (February 8) - Full uniform parameter system with .seq syntax. FlashEffect, ChromaAberrationEffect, GaussianBlurEffect now support dynamic parameters. Size: ~400-500 bytes. See `doc/COMPLETED.md` for details. +- **Shader Parametrization (Task #73)** (Feb 8) - Full uniform parameter system with .seq syntax. FlashEffect, ChromaAberrationEffect, GaussianBlurEffect support dynamic parameters. Size: ~400-500 bytes. -## Architectural Overview - -### Hybrid 3D Renderer -- **Core Idea**: Uses standard rasterization to draw proxy hulls (boxes), then raymarches inside the fragment shader to find the exact SDF surface. -- **Transforms**: Uses `inv_model` matrices to perform all raymarching in local object space, handling rotation and non-uniform scaling correctly. -- **Shadows**: Instance-based shadow casting with self-shadowing prevention (`skip_idx`). - -### Sequence & Effect System -- **Effect**: Abstract base for visual elements. Supports `compute` and `render` phases. -- **Sequence**: Timeline of effects with start/end times. -- **MainSequence**: Top-level coordinator and framebuffer manager. -- **seq_compiler**: Transpiles `assets/demo.seq` into C++ `timeline.cc`. +--- -### Asset & Build System -- **asset_packer**: Embeds binary assets (like `.spec` files) into C++ arrays. -- **Runtime Manager**: O(1) retrieval with lazy procedural generation support. -- **Automation**: `gen_assets.sh`, `build_win.sh`, and `check_all.sh` for multi-platform validation. +For detailed architecture, see `doc/ARCHITECTURE.md`. -### Audio Engine -- **Synthesis**: Real-time additive synthesis from spectrograms via FFT-based IDCT (O(N log N)). Stereo output (32kHz, 16-bit, interleaved L/R). Uses orthonormal DCT-II/DCT-III transforms with Numerical Recipes reordering method. -- **Variable Tempo**: Music time abstraction with configurable tempo_scale. Tempo changes don't affect pitch. -- **Event-Based Tracker**: Individual TrackerEvents trigger as separate voices with dynamic beat calculation. Notes within patterns respect tempo scaling. -- **Backend Abstraction**: `AudioBackend` interface with `MiniaudioBackend` (production), `MockAudioBackend` (testing), and `WavDumpBackend` (offline rendering). -- **Dynamic Updates**: Double-buffered spectrograms for live thread-safe updates. -- **Procedural Library**: Melodies and spectral filters (noise, comb) generated at runtime. -- **Pattern System**: TrackerPatterns contain lists of TrackerEvents (beat, sample_id, volume, pan). Events trigger individually based on elapsed music time. \ No newline at end of file +For completed tasks history, see `doc/COMPLETED.md` and git history. -- cgit v1.2.3