diff options
| -rw-r--r-- | CLAUDE.md | 6 | ||||
| -rw-r--r-- | GEMINI.md | 6 | ||||
| -rw-r--r-- | PROJECT_CONTEXT.md | 111 | ||||
| -rw-r--r-- | TODO.md | 254 | ||||
| -rw-r--r-- | doc/ARCHITECTURE.md | 60 | ||||
| -rw-r--r-- | doc/BACKLOG.md | 197 | ||||
| -rw-r--r-- | doc/CODING_STYLE.md | 109 | ||||
| -rw-r--r-- | doc/CONTRIBUTING.md | 69 | ||||
| -rw-r--r-- | doc/HOWTO.md | 86 | ||||
| -rw-r--r-- | doc/TOOLS_REFERENCE.md | 89 |
10 files changed, 598 insertions, 389 deletions
@@ -32,6 +32,12 @@ # # Testing & Tools: # doc/test_demo_README.md - test_demo tool documentation +# +# Architecture & Reference: +# doc/ARCHITECTURE.md - Detailed system architecture +# doc/CODING_STYLE.md - Code style examples +# doc/BACKLOG.md - Untriaged future goals +# doc/TOOLS_REFERENCE.md - Developer tools reference # ============================================ # TIER 4: HISTORICAL ARCHIVE (Load Rarely) @@ -33,6 +33,12 @@ # # Testing & Tools: # @doc/test_demo_README.md - test_demo tool documentation +# +# Architecture & Reference: +# @doc/ARCHITECTURE.md - Detailed system architecture +# @doc/CODING_STYLE.md - Code style examples +# @doc/BACKLOG.md - Untriaged future goals +# @doc/TOOLS_REFERENCE.md - Developer tools reference # ============================================ # TIER 4: HISTORICAL ARCHIVE (Load Rarely) 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<f32>` 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<f32>` 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. @@ -8,44 +8,33 @@ This file tracks prioritized tasks with detailed attack plans. ## Priority 1: Spectral Brush Editor (Task #5) [IN PROGRESS] -**Goal:** Create a web-based tool for procedurally tracing audio spectrograms. Replaces large `.spec` binary assets with tiny procedural C++ code (50-100× compression). +**Goal:** Web-based tool for procedurally tracing audio spectrograms. Replaces large `.spec` binary assets with tiny procedural C++ code (50-100× compression). **Design Document:** See `doc/SPECTRAL_BRUSH_EDITOR.md` for complete architecture. -**Core Concept: "Spectral Brush"** -- **Central Curve** (Bezier): Traces time-frequency path through spectrogram -- **Vertical Profile**: Shapes "brush stroke" around curve (Gaussian, Decaying Sinusoid, Noise) +**Core Concept:** Bezier curves trace time-frequency paths. Gaussian profiles shape "brush strokes" around curves. -**Workflow:** -``` -.wav → Load in editor → Trace with Bezier curves → Export procedural_params.txt + C++ code -``` +**Workflow:** `.wav` → Load in editor → Trace with Bezier curves → Export `procedural_params.txt` + C++ code ### Phase 1: C++ Runtime (Foundation) -- [ ] **Files:** `src/audio/spectral_brush.h`, `src/audio/spectral_brush.cc` +- [ ] Files: `src/audio/spectral_brush.h`, `src/audio/spectral_brush.cc` - [ ] Define API (`ProfileType`, `draw_bezier_curve()`, `evaluate_profile()`) - [ ] Implement linear Bezier interpolation - [ ] Implement Gaussian profile evaluation -- [ ] Implement home-brew deterministic RNG (for future noise support) +- [ ] Implement home-brew deterministic RNG - [ ] Add unit tests (`src/tests/test_spectral_brush.cc`) - [ ] **Deliverable:** Compiles, tests pass ### Phase 2: Editor Core -- [ ] **Files:** `tools/spectral_editor/index.html`, `script.js`, `style.css`, `dct.js` (reuse from old editor) +- [ ] Files: `tools/spectral_editor/index.html`, `script.js`, `style.css`, `dct.js` - [ ] HTML structure (canvas, controls, file input) - [ ] Canvas rendering (dual-layer: reference + procedural) -- [ ] Bezier curve editor (click to place, drag to adjust, delete control points) +- [ ] Bezier curve editor (click, drag, delete control points) - [ ] Profile controls (Gaussian sigma slider) - [ ] Real-time spectrogram rendering - [ ] Audio playback (IDCT → Web Audio API) -- [ ] Undo/Redo system (action history with snapshots) -- [ ] **Keyboard shortcuts:** - - Key '1': Play procedural sound - - Key '2': Play original .wav - - Space: Play/pause - - Ctrl+Z: Undo - - Ctrl+Shift+Z: Redo - - Delete: Remove control point +- [ ] Undo/Redo system +- [ ] Keyboard shortcuts (1=play procedural, 2=play original, Space, Ctrl+Z, Delete) - [ ] **Deliverable:** Interactive editor, can trace .wav files ### Phase 3: File I/O @@ -61,213 +50,74 @@ This file tracks prioritized tasks with detailed attack plans. - [ ] Decaying sinusoid profile (metallic sounds) - [ ] Noise profile (textured sounds) - [ ] Composite profiles (add/subtract/multiply) -- [ ] Multi-dimensional Bezier ({freq, amplitude, decay, ...}) -- [ ] Frequency snapping (snap to musical notes) -- [ ] Generic `gen_from_params()` code generation -**Design Decisions:** -- Linear Bezier interpolation (Phase 1), cubic later -- Soft parameter limits in UI (not enforced) -- Home-brew RNG (small, deterministic) -- Single function per sound (generic loader later) -- Start with Bezier + Gaussian only +**Design Decisions:** Linear Bezier (Phase 1), cubic later. Soft parameter limits. Home-brew RNG. Single function per sound initially. **Size Impact:** 50-100× compression (5 KB .spec → ~100 bytes C++ code) --- ## Priority 2: 3D System Enhancements (Task #18) -**Goal:** Establish a pipeline for importing complex 3D scenes to replace hardcoded geometry. **Progress:** C++ pipeline for loading and processing object-specific data (like plane_distance) is now in place. Shader integration for SDFs is pending. + +**Goal:** Establish pipeline for importing complex 3D scenes to replace hardcoded geometry. + +**Progress:** C++ pipeline for loading object-specific data (plane_distance) is in place. Shader integration for SDFs pending. + +--- ## 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. +**Goal:** Refactor `ShaderComposer` and WGSL assets to support granular, reusable snippets. Ongoing task for shader code hygiene. ### Sub-task: Split common_uniforms.wgsl (Low Priority) -- **Current**: `common_uniforms.wgsl` contains 4 structs (CommonUniforms, GlobalUniforms, ObjectData, ObjectsBuffer) -- **Goal**: Split into separate files for granular #include - - `common_uniforms/common.wgsl` - CommonUniforms only - - `common_uniforms/global.wgsl` - GlobalUniforms only - - `common_uniforms/object.wgsl` - ObjectData + ObjectsBuffer -- **Benefit**: Shaders only include what they need, reducing compiled size -- **Impact**: Minimal (most shaders only use CommonUniforms anyway) -- **Priority**: Low (nice-to-have for code organization) +**Current:** `common_uniforms.wgsl` contains 4 structs (CommonUniforms, GlobalUniforms, ObjectData, ObjectsBuffer) -### Sub-task: Type-safe shader composition (Low Priority) -- **Problem**: Recurrent error of forgetting `ShaderComposer::Get().Compose({}, code)` and using raw `code` directly - - Happened in: `create_post_process_pipeline`, `gpu_create_render_pass`, `gpu_create_compute_pass`, `CircleMaskEffect` - - Runtime error only (crashes demo, but tests may pass) -- **Solution**: Use strong typing to make it a compile-time error - ```cpp - class ComposedShader { - private: - std::string code_; - friend class ShaderComposer; - explicit ComposedShader(std::string code) : code_(std::move(code)) {} - public: - const char* c_str() const { return code_.c_str(); } - }; - ``` -- **Changes needed**: - - `ShaderComposer::Compose()` returns `ComposedShader` instead of `std::string` - - All shader creation functions take `const ComposedShader&` instead of `const char*` - - Cannot pass raw string to shader functions (compile error) -- **Benefits**: - - Impossible to forget composition (type mismatch) - - Self-documenting API (signature shows shader must be composed) - - Catches errors at compile-time instead of runtime -- **Trade-offs**: - - More verbose code (`auto shader = ShaderComposer::Get().Compose(...)`) - - Small overhead (extra std::string copy, but negligible) -- **Priority**: Low (recurrent but rare, easy to catch in testing) +**Goal:** Split into separate files: +- `common_uniforms/common.wgsl` - CommonUniforms only +- `common_uniforms/global.wgsl` - GlobalUniforms only +- `common_uniforms/object.wgsl` - ObjectData + ObjectsBuffer -## Phase 2: Size Optimization (Final Goal) - -- [ ] **Task #34: Full STL Removal**: Replace all remaining `std::vector`, `std::map`, and `std::string` usage with custom minimal containers or C-style arrays to allow for CRT replacement. (Minimal Priority - deferred to end). +**Benefit:** Shaders only include what they need, reducing compiled size -- [ ] **Task #22: Windows Native Platform**: Replace GLFW with direct Win32 API calls for the final 64k push. +**Impact:** Minimal (most shaders only use CommonUniforms) -- [ ] **Task #28: Spectrogram Quantization**: Research optimal frequency bin distribution and implement quantization. +**Priority:** Low (nice-to-have) -- [ ] **Task #35: CRT Replacement**: investigation and implementation of CRT-free entry point. +### Sub-task: Type-safe shader composition (Low Priority) +**Problem:** Recurrent error of forgetting `ShaderComposer::Get().Compose({}, code)` and using raw `code` directly. Runtime error only (crashes demo, tests may pass). -## Future Goals & Ideas (Untriaged) +**Solution:** Use strong typing to make it compile-time error: +```cpp +class ComposedShader { + private: + std::string code_; + friend class ShaderComposer; + explicit ComposedShader(std::string code) : code_(std::move(code)) {} + public: + const char* c_str() const { return code_.c_str(); } +}; +``` -### Audio Tools -- [ ] **Task #64: specplay Enhancements**: Extend audio analysis tool with new features - - **Priority 1**: Spectral visualization (ASCII art), waveform display, frequency analysis, dynamic range - - **Priority 2**: Diff mode (compare .wav vs .spec), batch mode (CSV report, find clipping) - - **Priority 3**: WAV export (.spec → .wav), normalization - - **Priority 4**: Spectral envelope, harmonic analysis, onset detection - - **Priority 5**: Interactive mode (seek, loop, volume control) - - See `tools/specplay_README.md` for detailed feature list +**Changes:** +- `ShaderComposer::Compose()` returns `ComposedShader` instead of `std::string` +- All shader creation functions take `const ComposedShader&` instead of `const char*` +- Cannot pass raw string to shader functions (compile error) -- [ ] **Task #65: Data-Driven Tempo Control**: Move tempo variation from code to data files - - **Current**: `g_tempo_scale` is hardcoded in `main.cc` with manual animation curves - - **Goal**: Define tempo curves in `.seq` or `.track` files for data-driven tempo control - - **Approach A**: Add TEMPO directive to `.seq` format - - Example: `TEMPO 0.0 1.0`, `TEMPO 10.0 2.0`, `TEMPO 20.0 1.0` (time, scale pairs) - - seq_compiler generates tempo curve array in timeline.cc - - **Approach B**: Add tempo column to music.track - - Each pattern trigger can specify tempo_scale override - - tracker_compiler generates tempo events in music_data.cc - - **Benefits**: Non-programmers can edit tempo, easier iteration, version control friendly - - **Priority**: Low (current hardcoded approach works, but less flexible) +**Benefits:** Impossible to forget composition (type mismatch). Self-documenting API. Compile-time error. -- [ ] **Task #67: DCT/FFT Performance Benchmarking**: Add timing measurements to audio tests - - **Goal**: Compare performance of different DCT/IDCT implementations - - **Location**: Add timing code to `test_dct.cc` or `test_fft.cc` - - **Measurements**: - - Reference IDCT/FDCT (naive O(N²) implementation) - - FFT-based DCT/IDCT (current O(N log N) implementation) - - Future x86_64 SIMD-optimized versions (when implemented) - - **Output Format**: - - Average time per transform (microseconds) - - Throughput (transforms per second) - - Speedup factor vs reference implementation - - **Test Sizes**: DCT_SIZE=512 (production), plus 128, 256, 1024 for scaling analysis - - **Implementation**: - - Use `std::chrono::high_resolution_clock` for timing - - Run each test 1000+ iterations to reduce noise - - Report min/avg/max times - - Guard with `#if !defined(STRIP_ALL)` to avoid production overhead - - **Benefits**: Quantify FFT speedup, validate SIMD optimizations, identify regressions - - **Priority**: Very Low (nice-to-have for future optimization work) +**Trade-offs:** More verbose code. Small overhead (extra std::string copy, negligible). -- [ ] **Task #69: Convert Audio Pipeline to Clipped Int16**: Use clipped int16 for all audio processing - - **Current**: Audio pipeline uses float32 throughout (generation, mixing, synthesis, output) - - **Goal**: Convert to clipped int16 for faster/easier processing and reduced memory footprint - - **Rationale**: - - Simpler arithmetic (no float operations) - - Smaller memory footprint (2 bytes vs 4 bytes per sample) - - Hardware-native format (most audio devices use int16) - - Eliminates float→int16 conversion at output stage - - Natural clipping behavior (overflow wraps/clips automatically) - - **Scope**: - - Output path: Definitely convert (backends, WAV dump) - - Synthesis: Consider keeping float32 for quality (IDCT produces float) - - Mixing: Could use int16 with proper overflow handling - - Asset storage: Already int16 in .spec files - - **Implementation Phases**: - 1. **Phase 1: Output Only** (Minimal change, ~50 lines) - - Convert `synth_render()` output from float to int16 - - Update `MiniaudioBackend` and `WavDumpBackend` to accept int16 - - Keep all internal processing as float - - **Benefit**: Eliminates final conversion step - 2. **Phase 2: Mixing Stage** (Moderate change, ~200 lines) - - Convert voice mixing to int16 arithmetic - - Add saturation/clipping logic - - Keep IDCT output as float, convert after synthesis - - **Benefit**: Faster mixing, reduced memory bandwidth - 3. **Phase 3: Full Pipeline** (Large change, ~500+ lines) - - Convert spectrograms from float to int16 storage - - Modify IDCT to output int16 directly - - All synthesis in int16 - - **Benefit**: Maximum size reduction and performance - - **Trade-offs**: - - Quality loss: 16-bit resolution vs 32-bit float precision - - Dynamic range: Limited to [-32768, 32767] - - Clipping: Must handle overflow carefully in mixing stage - - Code complexity: Saturation arithmetic more complex than float - - **Testing Requirements**: - - Verify no audible quality degradation - - Ensure clipping behavior matches float version - - Check mixing overflow doesn't cause artifacts - - Validate WAV dumps bit-identical to hardware output - - **Size Impact**: - - Phase 1: Negligible (~50 bytes) - - Phase 2: Small reduction (~100-200 bytes, faster code) - - Phase 3: Large reduction (50% memory, ~1-2KB code savings) - - **Priority**: Low (final optimization, after size budget is tight) - - **Notes**: - - This is a FINAL optimization task, only if 64k budget requires it - - Quality must be validated - may not be worth the trade-off - - Consider keeping float for procedural generation quality +**Priority:** Low (recurrent but rare, easy to catch in testing) -### Developer Tools -- [ ] **Task #66: External Asset Loading for Debugging**: mmap() asset files instead of embedded data - - **Current**: All assets embedded in `assets_data.cc` (regenerate on every asset change) - - **Goal**: Load assets from external files in debug builds for faster iteration - - **Scope**: macOS only, non-STRIP_ALL builds only - - **Implementation**: - - Add `DEMO_ENABLE_EXTERNAL_ASSETS` CMake option - - Modify `GetAsset()` to check for external file first (e.g., `assets/final/<name>`) - - Use `mmap()` to map file into memory (replaces `uint8_t asset[]` array) - - Fallback to embedded data if file not found - - **Benefits**: Edit shaders/assets without regenerating assets_data.cc (~10s rebuild) - - **Trade-offs**: Adds runtime file I/O, only useful during development - - **Priority**: Low (current workflow acceptable, but nice-to-have for rapid iteration) +--- -### Visual Effects -- [ ] **Task #73: Extend Shader Parametrization** [IN PROGRESS - 2/4 complete] - - **Goal**: Extend uniform parameter system to ChromaAberrationEffect, GaussianBlurEffect, DistortEffect, SolarizeEffect - - **Pattern**: Follow FlashEffect implementation (UniformHelper, params struct, .seq syntax) - - **Completed**: ChromaAberrationEffect (offset_scale, angle), GaussianBlurEffect (strength) - - **Remaining**: DistortEffect, SolarizeEffect - - **Priority**: Medium (quality-of-life improvement for artists) - - **Estimated Impact**: ~200-300 bytes per effect -- [ ] **Task #52: Procedural SDF Font**: Minimal bezier/spline set for [A-Z, 0-9] and SDF rendering. -- [ ] **Task #55: SDF Random Planes Intersection**: Implement `sdPolyhedron` (crystal/gem shapes) via plane intersection. -- [ ] **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. -- [ ] **Task #60: OOP Refactoring**: Investigate if more C++ code can be made object-oriented without size penalty (vs functional style). -- [ ] **Task #61: GPU Procedural Generation**: Implement system to generate procedural data (textures, geometry) on GPU and read back to CPU. -- [ ] **Task #62: Physics Engine Enhancements (PBD & Rotation)**: - - [ ] **Task #62.1: Quaternion Rotation**: Implement quaternion-based rotation for `Object3D` and incorporate angular momentum into physics. - - [ ] **Task #62.2: Position Based Dynamics (PBD)**: Refactor solver to re-evaluate velocity after resolving all collisions and constraints. -- [ ] **Task #63: Refactor large files**: Split `src/gpu/gpu.cc`, `src/3d/visual_debug.cc` and `src/gpu/effect.cc` into sub-functionalities. (`src/3d/renderer.cc` was also over 500 lines and was taken care of in the past) +## Phase 2: Size Optimization (Final Goal) -### Performance Optimization -- [ ] **Task #70: SIMD x86_64 Implementation**: Implement critical functions using intrinsics for x86_64 platforms. - - **Goal**: Optimize hot paths for audio and procedural generation. - - **Scope**: - - IDCT/FDCT transforms - - Audio mixing and voice synthesis - - CPU-side procedural texture/geometry generation - - **Constraint**: Non-critical; fallback to generic C++ must be maintained. - - **Priority**: Very Low +- [ ] **Task #34: Full STL Removal** - Replace remaining `std::vector`, `std::map`, `std::string` with custom containers +- [ ] **Task #22: Windows Native Platform** - Replace GLFW with Win32 API +- [ ] **Task #28: Spectrogram Quantization** - Research optimal frequency distribution +- [ ] **Task #35: CRT Replacement** - Investigation and implementation of CRT-free entry --- -## Future Goals +For untriaged future goals and ideas, see `doc/BACKLOG.md`. diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md new file mode 100644 index 0000000..1a32300 --- /dev/null +++ b/doc/ARCHITECTURE.md @@ -0,0 +1,60 @@ +# Architectural Overview + +Detailed system architecture for the 64k demo project. + +--- + +## 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. + +--- + +## 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. diff --git a/doc/BACKLOG.md b/doc/BACKLOG.md new file mode 100644 index 0000000..403ecc9 --- /dev/null +++ b/doc/BACKLOG.md @@ -0,0 +1,197 @@ +# Future Goals & Ideas (Untriaged) + +This file contains low-priority tasks and ideas that have not yet been triaged for active development. + +--- + +## Audio Tools + +### Task #64: specplay Enhancements +Extend audio analysis tool with new features: +- **Priority 1**: Spectral visualization (ASCII art), waveform display, frequency analysis, dynamic range +- **Priority 2**: Diff mode (compare .wav vs .spec), batch mode (CSV report, find clipping) +- **Priority 3**: WAV export (.spec → .wav), normalization +- **Priority 4**: Spectral envelope, harmonic analysis, onset detection +- **Priority 5**: Interactive mode (seek, loop, volume control) + +See `tools/specplay_README.md` for detailed feature list. + +### Task #65: Data-Driven Tempo Control +Move tempo variation from code to data files. + +**Current**: `g_tempo_scale` is hardcoded in `main.cc` with manual animation curves + +**Goal**: Define tempo curves in `.seq` or `.track` files + +**Approach A**: Add TEMPO directive to `.seq` format +- Example: `TEMPO 0.0 1.0`, `TEMPO 10.0 2.0`, `TEMPO 20.0 1.0` +- seq_compiler generates tempo curve array in timeline.cc + +**Approach B**: Add tempo column to music.track +- Each pattern trigger can specify tempo_scale override +- tracker_compiler generates tempo events in music_data.cc + +**Benefits**: Non-programmers can edit tempo, easier iteration, version control friendly + +**Priority**: Low (current approach works) + +### Task #67: DCT/FFT Performance Benchmarking +Add timing measurements to audio tests. + +**Goal**: Compare performance of different DCT/IDCT implementations + +**Location**: Add timing code to `test_dct.cc` or `test_fft.cc` + +**Measurements**: +- Reference IDCT/FDCT (naive O(N²)) +- FFT-based DCT/IDCT (current O(N log N)) +- Future x86_64 SIMD-optimized versions + +**Output Format**: +- Average time per transform (microseconds) +- Throughput (transforms per second) +- Speedup factor vs reference + +**Test Sizes**: DCT_SIZE=512 (production), plus 128, 256, 1024 for scaling + +**Implementation**: +- Use `std::chrono::high_resolution_clock` +- Run 1000+ iterations to reduce noise +- Report min/avg/max times +- Guard with `#if !defined(STRIP_ALL)` + +**Priority**: Very Low (nice-to-have) + +### Task #69: Convert Audio Pipeline to Clipped Int16 +Use clipped int16 for all audio processing. + +**Current**: Float32 throughout (generation, mixing, synthesis, output) + +**Goal**: Convert to int16 for faster processing and reduced memory + +**Rationale**: +- Simpler arithmetic (no float operations) +- Smaller memory footprint (2 bytes vs 4 bytes) +- Hardware-native format (most audio devices use int16) +- Eliminates float→int16 conversion at output +- Natural clipping behavior + +**Scope**: +- Output path: Definitely convert (backends, WAV dump) +- Synthesis: Consider keeping float32 for quality +- Mixing: Could use int16 with overflow handling +- Asset storage: Already int16 in .spec files + +**Implementation Phases**: +1. **Phase 1: Output Only** (~50 lines) - Convert `synth_render()` output to int16 +2. **Phase 2: Mixing Stage** (~200 lines) - Convert voice mixing to int16 arithmetic +3. **Phase 3: Full Pipeline** (~500+ lines) - Convert spectrograms to int16 storage + +**Trade-offs**: +- Quality loss: 16-bit vs 32-bit float precision +- Dynamic range: Limited to [-32768, 32767] +- Clipping: Must handle overflow carefully +- Code complexity: Saturation arithmetic + +**Testing Requirements**: +- Verify no audible quality degradation +- Ensure clipping behavior matches float version +- Check mixing overflow doesn't cause artifacts +- Validate WAV dumps bit-identical + +**Size Impact**: +- Phase 1: Negligible (~50 bytes) +- Phase 2: ~100-200 bytes +- Phase 3: 50% memory, ~1-2KB code savings + +**Priority**: Low (final optimization only if 64k budget requires it) + +**Notes**: Quality must be validated - may not be worth trade-off + +--- + +## Developer Tools + +### Task #66: External Asset Loading for Debugging +mmap() asset files instead of embedded data. + +**Current**: All assets embedded in `assets_data.cc` (regenerate on every change) + +**Goal**: Load assets from external files in debug builds for faster iteration + +**Scope**: macOS only, non-STRIP_ALL builds only + +**Implementation**: +- Add `DEMO_ENABLE_EXTERNAL_ASSETS` CMake option +- Modify `GetAsset()` to check for external file first (e.g., `assets/final/<name>`) +- Use `mmap()` to map file into memory +- Fallback to embedded data if file not found + +**Benefits**: Edit shaders/assets without regenerating assets_data.cc (~10s rebuild) + +**Trade-offs**: Adds runtime file I/O, only useful during development + +**Priority**: Low (current workflow acceptable) + +--- + +## Visual Effects + +### Task #73: Extend Shader Parametrization [IN PROGRESS - 2/4 complete] +Extend uniform parameter system to remaining effects. + +**Goal**: Add parametrization to DistortEffect, SolarizeEffect + +**Pattern**: Follow FlashEffect implementation (UniformHelper, params struct, .seq syntax) + +**Completed**: ChromaAberrationEffect (offset_scale, angle), GaussianBlurEffect (strength) + +**Priority**: Medium (quality-of-life for artists) + +**Estimated Impact**: ~200-300 bytes per effect + +### Task #52: Procedural SDF Font +Minimal bezier/spline set for [A-Z, 0-9] and SDF rendering. + +### Task #55: SDF Random Planes Intersection +Implement `sdPolyhedron` (crystal/gem shapes) via plane intersection. + +### 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. + +### Task #60: OOP Refactoring +Investigate if more C++ code can be made object-oriented without size penalty (vs functional style). + +### Task #61: GPU Procedural Generation +Implement system to generate procedural data (textures, geometry) on GPU and read back to CPU. + +### Task #62: Physics Engine Enhancements (PBD & Rotation) +- **Task #62.1**: Quaternion rotation for `Object3D` with angular momentum +- **Task #62.2**: Position Based Dynamics (PBD) - Re-evaluate velocity after resolving collisions/constraints + +### Task #63: Refactor Large Files +Split `src/gpu/gpu.cc`, `src/3d/visual_debug.cc` and `src/gpu/effect.cc` into sub-functionalities. + +--- + +## Performance Optimization + +### Task #70: SIMD x86_64 Implementation +Implement critical functions using intrinsics for x86_64 platforms. + +**Goal**: Optimize hot paths for audio and procedural generation + +**Scope**: +- IDCT/FDCT transforms +- Audio mixing and voice synthesis +- CPU-side procedural texture/geometry generation + +**Constraint**: Non-critical; fallback to generic C++ must be maintained + +**Priority**: Very Low diff --git a/doc/CODING_STYLE.md b/doc/CODING_STYLE.md new file mode 100644 index 0000000..533cffb --- /dev/null +++ b/doc/CODING_STYLE.md @@ -0,0 +1,109 @@ +# Coding Style Examples + +Detailed examples for the project's C++ coding style. + +--- + +## Core Rules Examples + +### Const Placement +```cpp +const T* name // Correct +const T *name // Wrong +``` + +### Pre-Increment +```cpp +++x // Correct +x++ // Wrong (except when postfix needed) +``` + +### Operator Spacing +```cpp +x = (a + b) * c; // Correct - spaces around all operators +x=(a+b)*c; // Wrong - no spaces +``` + +### No Auto (except complex iterators) +```cpp +int count = get_count(); // Correct +auto count = get_count(); // Wrong + +for (auto it = map.begin(); ...) // OK - complex iterator type +``` + +### No C++ Casts +```cpp +(int)value // Correct +static_cast<int>(value) // Wrong +``` + +--- + +## Preprocessor Style + +```cpp +#if defined(MY_TAG) + // code here +#endif /* defined(MY_TAG) */ +``` + +Always use `defined()` and closing comment. + +--- + +## Struct Initialization + +### Good +```cpp +const WGPUDescriptor desc = { + .format = g_format, + .dimension = WGPUTextureViewDimension_2D, +}; +``` + +### Bad +```cpp +WGPUDescriptor desc = {}; +desc.format = g_format; +desc.dimension = WGPUTextureViewDimension_2D; +``` + +Use designated initializers, not field-by-field assignment. + +--- + +## Class Keywords Indentation + +```cpp +class MyClass { + public: // 1 space indent + void foo(); + + private: // 1 space indent + int field_; +}; +``` + +--- + +## Comments + +### Function Comments +```cpp +// Initializes the audio engine with default settings. +void audio_init() { + ... +} +``` + +One-line comment for non-obvious functions. + +### File Headers +```cpp +// demo64k - 64 kilobyte demo +// src/audio/synth.cc +// Audio synthesis engine +``` + +Three-line header for all source files. diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 7490fe6..de6378a 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -1,5 +1,7 @@ # Contributing Guidelines +--- + ## Commit Policy ### Verify Before Committing @@ -8,7 +10,6 @@ ```bash ./scripts/check_all.sh ``` -Runs tests, builds tools, cross-compiles Windows. **Manual:** ```bash @@ -26,18 +27,9 @@ cd build && ctest --output-on-failure cmake -S . -B build_debug_check -DDEMO_ENABLE_DEBUG_LOGS=ON cmake --build build_debug_check -j4 ``` -Must compile without errors. **Debug macros** (`src/util/debug.h`): -- `DEBUG_LOG_AUDIO`, `DEBUG_LOG_RING_BUFFER`, `DEBUG_LOG_TRACKER` -- `DEBUG_LOG_SYNTH`, `DEBUG_LOG_3D`, `DEBUG_LOG_ASSETS`, `DEBUG_LOG_GPU` - -Example: -```cpp -#if defined(DEBUG_LOG_AUDIO) - DEBUG_AUDIO("[CALLBACK #%d] frames=%d\n", ++count, frames); -#endif -``` +- `DEBUG_LOG_AUDIO`, `DEBUG_LOG_RING_BUFFER`, `DEBUG_LOG_TRACKER`, `DEBUG_LOG_SYNTH`, `DEBUG_LOG_3D`, `DEBUG_LOG_ASSETS`, `DEBUG_LOG_GPU` ### Code Formatting ```bash @@ -50,6 +42,8 @@ Never format `third_party/`. - 3-line header comment - Max 500 lines (split if larger) +--- + ## Coding Style ### Core Rules @@ -61,36 +55,9 @@ Never format `third_party/`. - No `auto` (except complex iterators) - No C++ casts (`static_cast`, `reinterpret_cast`) -### Preprocessor -```cpp -#if defined(MY_TAG) - ... -#endif /* defined(MY_TAG) */ -``` - -### Struct Initialization -```cpp -// Good -const WGPUDescriptor desc = { - .format = g_format, - .dimension = WGPUTextureViewDimension_2D, -}; - -// Bad -WGPUDescriptor desc = {}; -desc.format = g_format; -desc.dimension = WGPUTextureViewDimension_2D; -``` - -### Class Keywords -```cpp - private: // 1 space indent - int field_; -``` +See `doc/CODING_STYLE.md` for detailed examples. -### Comments -- 1-line comment for non-obvious functions -- 3-line header for all source files +--- ## Development Protocols @@ -170,18 +137,18 @@ After hierarchy changes (moving files, renaming), verify: ./scripts/gen_coverage_report.sh ``` -Update scripts with hardcoded paths. +--- ## Uniform Buffer Checklist -To ensure consistency and prevent alignment-related issues, follow these guidelines when working with uniform buffers: +To ensure consistency and prevent alignment-related issues: -1. **Define WGSL Structs:** Clearly define uniform structs in WGSL, paying close attention to type alignment (`f32`, `vec2`, `vec3`, `vec4`) and using explicit padding (`_pad0: vec2<f32>`) where necessary. -2. **Mirror in C++:** Create corresponding C++ structs that mirror the WGSL struct's definitions. -3. **`static_assert` for Size:** Every C++ struct corresponding to a WGSL uniform buffer **must** have a `static_assert` verifying its size matches the expected WGSL size. Use `sizeof(MyStruct) == EXPECTED_SIZE`. -4. **Standard Bindings:** - * **Binding 2:** Always use `CommonPostProcessUniforms` (or a similar common structure) for general per-frame data (resolution, time, beat, etc.). - * **Binding 3:** Use effect-specific parameter structs for unique effect data. -5. **Shader Consistency:** Ensure WGSL shaders correctly declare and use uniforms at the specified bindings (`@group(0) @binding(2)` for common uniforms, `@group(0) @binding(3)` for effect parameters). -6. **Validation Script:** Run `tools/validate_uniforms.py` as part of your development workflow to catch any discrepancies in size or alignment between C++ and WGSL definitions. Ensure this script passes without errors. -7. **Documentation:** Refer to `doc/UNIFORM_BUFFER_GUIDELINES.md` for detailed information on WGSL alignment rules and best practices. +1. **Define WGSL Structs:** Pay attention to type alignment (`f32`, `vec2`, `vec3`, `vec4`) and use explicit padding where necessary. +2. **Mirror in C++:** Create corresponding C++ structs that mirror WGSL definitions. +3. **`static_assert` for Size:** Every C++ struct must have a `static_assert` verifying size matches WGSL. +4. **Standard Bindings:** + - **Binding 2:** Always use `CommonPostProcessUniforms` for per-frame data (resolution, time, beat). + - **Binding 3:** Use effect-specific parameter structs for unique data. +5. **Shader Consistency:** Ensure WGSL shaders correctly declare uniforms at specified bindings. +6. **Validation Script:** Run `tools/validate_uniforms.py` to catch discrepancies. +7. **Documentation:** Refer to `doc/UNIFORM_BUFFER_GUIDELINES.md` for detailed alignment rules. diff --git a/doc/HOWTO.md b/doc/HOWTO.md index 2595258..876d7dc 100644 --- a/doc/HOWTO.md +++ b/doc/HOWTO.md @@ -2,6 +2,8 @@ Common commands for building and testing. +--- + ## Building ### Debug Build @@ -11,10 +13,7 @@ cmake --build build -j4 ./build/demo64k ``` -Options: -- `--fullscreen`: Run in fullscreen -- `--resolution WxH`: Set window size (e.g., 1024x768) -- `--seek TIME`: Jump to timestamp (debug builds only) +Options: `--fullscreen`, `--resolution WxH`, `--seek TIME` (debug only) Keyboard: `Esc` (exit), `F` (toggle fullscreen) @@ -50,24 +49,29 @@ cmake --build build_final -j4 cmake -S . -B build -DDEMO_BUILD_TESTS=ON -DDEMO_BUILD_TOOLS=ON cmake --build build -j4 ``` -Enables tests and tools without stripping debug features. -**Note**: `DEMO_ALL_OPTIONS=ON` enables tests, tools, AND `STRIP_ALL`, which removes debug-only code (e.g., `test_demo` PeakMeterEffect). Use selective flags for debugging. +**Note:** `DEMO_ALL_OPTIONS=ON` enables tests, tools, AND `STRIP_ALL`, which removes debug-only code. Use selective flags for debugging. + +--- ## Build System -**Dependency Tracking**: CMake tracks 42 demo + 17 test assets. Editing shaders/audio auto-triggers rebuild. +**Dependency Tracking:** CMake tracks 42 demo + 17 test assets. Editing shaders/audio auto-triggers rebuild. -**Header Organization**: +**Header Organization:** - `asset_manager_dcl.h`: Forward declarations - `asset_manager.h`: Core API (GetAsset/DropAsset) - `asset_manager_utils.h`: Typed helpers +--- + ## Git Clone ```bash git clone ssh://git@51.38.51.127/~/demo.git ``` +--- + ## Audio System ### AudioEngine API @@ -92,10 +96,7 @@ audio_shutdown(); - `seek(time)`: Jump to timestamp (debug only) **Direct Synth APIs** (performance-critical): -- `synth_register_spectrogram()`: Register samples -- `synth_trigger_voice()`: Trigger playback -- `synth_get_output_peak()`: Get audio level -- `synth_render()`: Low-level rendering +- `synth_register_spectrogram()`, `synth_trigger_voice()`, `synth_get_output_peak()`, `synth_render()` **Testing:** ```cpp @@ -105,6 +106,8 @@ engine.update(1.0f); engine.shutdown(); ``` +--- + ## Auxiliary Texture Masking Share textures between effects: @@ -118,6 +121,8 @@ WGPUTextureView view = demo_->get_auxiliary_view("mask_name"); ``` See `doc/MASKING_SYSTEM.md` for details. +--- + ## Demo Timeline Edit `assets/demo.seq`: @@ -127,6 +132,8 @@ SEQUENCE 0.0 0 ``` Rebuild to update timeline. +--- + ## Testing **Run all tests:** @@ -142,56 +149,7 @@ cd build && ctest - `SynthEngineTest`: Audio synthesis - `SequenceSystemTest`: Timeline logic -## Code Coverage (macOS) -```bash -brew install lcov -./scripts/gen_coverage_report.sh [target_dir] -``` - -## Tools - -### Windows Cross-Compilation -```bash -./scripts/fetch_win_deps.sh -./scripts/build_win.sh -./scripts/run_win.sh -``` - -### spectool (Audio Analysis) -```bash -cmake -S . -B build -DDEMO_BUILD_TOOLS=ON -cmake --build build -j4 - -# Analyze -./build/spectool analyze input.wav output.spec - -# Play -./build/spectool play input.spec -``` - -### specview (Visualization) -```bash -./build/specview input.spec -``` - -### specplay (Diagnostic) -```bash -./build/specplay input.spec -# or -./build/specplay input.wav -``` -Output: Peak, RMS, clipping detection. - -### Submodule Updates -```bash -cd third_party/wgpu-native -git fetch -git checkout trunk -git reset --hard origin/trunk -cd ../.. -git add third_party/wgpu-native -git commit -m "chore: Update wgpu-native" -``` +--- ## Asset Management @@ -218,3 +176,7 @@ const uint8_t* data = GetAsset(AssetId::KICK_1, &size); ``` Build system auto-runs `asset_packer` when asset lists change. + +--- + +For developer tools reference (spectool, Windows cross-compilation, code coverage), see `doc/TOOLS_REFERENCE.md`. diff --git a/doc/TOOLS_REFERENCE.md b/doc/TOOLS_REFERENCE.md new file mode 100644 index 0000000..61412a9 --- /dev/null +++ b/doc/TOOLS_REFERENCE.md @@ -0,0 +1,89 @@ +# Developer Tools Reference + +Comprehensive reference for all developer tools in the project. + +--- + +## Windows Cross-Compilation + +```bash +# Fetch dependencies +./scripts/fetch_win_deps.sh + +# Build Windows binary +./scripts/build_win.sh + +# Run with Wine +./scripts/run_win.sh +``` + +--- + +## spectool (Audio Analysis) + +```bash +# Build +cmake -S . -B build -DDEMO_BUILD_TOOLS=ON +cmake --build build -j4 + +# Analyze WAV → .spec +./build/spectool analyze input.wav output.spec + +# Play .spec file +./build/spectool play input.spec +``` + +--- + +## specview (Visualization) + +```bash +# View spectrogram +./build/specview input.spec +``` + +Displays spectrogram visualization. + +--- + +## specplay (Diagnostic) + +```bash +# Analyze .spec file +./build/specplay input.spec + +# Or analyze .wav file +./build/specplay input.wav +``` + +Output: Peak, RMS, clipping detection. + +--- + +## Code Coverage (macOS) + +```bash +# Install lcov +brew install lcov + +# Generate coverage report +./scripts/gen_coverage_report.sh [target_dir] +``` + +Creates HTML coverage report. + +--- + +## Submodule Updates + +```bash +cd third_party/wgpu-native +git fetch +git checkout trunk +git reset --hard origin/trunk +cd ../.. +git add third_party/wgpu-native +git commit -m "chore: Update wgpu-native" +``` + +Updates wgpu-native to latest trunk. |