| Age | Commit message (Collapse) | Author |
|---|
|
Implemented systematic fatal error checking infrastructure that can be
stripped for final builds. This addresses the need to remove all error
checking (abort() calls) from the production binary while maintaining
safety during development.
## New Infrastructure
### 1. CMake Option: DEMO_FINAL_STRIP
- New build mode for absolute minimum binary size
- Implies DEMO_STRIP_ALL (stricter superset)
- NOT included in DEMO_ALL_OPTIONS (manual opt-in only)
- Message printed during configuration
### 2. Header: src/util/fatal_error.h
- Systematic macro-based error checking
- Zero cost when FINAL_STRIP enabled (compiles to ((void)0))
- Full error messages with file:line info when enabled
- Five macros for different use cases:
- FATAL_CHECK(cond, msg, ...): Conditional checks (most common)
- FATAL_ERROR(msg, ...): Unconditional errors
- FATAL_UNREACHABLE(): Unreachable code markers
- FATAL_ASSERT(cond): Assertion-style invariants
- FATAL_CODE_BEGIN/END: Complex validation blocks
### 3. CMake Target: make final
- Convenience target for triggering final build
- Reconfigures with FINAL_STRIP and rebuilds demo64k
- Only available when NOT in FINAL_STRIP mode (prevents recursion)
### 4. Script: scripts/build_final.sh
- Automated final build workflow
- Creates build_final/ directory
- Shows size comparison with STRIP_ALL build (if available)
- Comprehensive warnings about stripped error checking
## Build Mode Hierarchy
| Mode | Error Checks | Debug Features | Size Opt |
|-------------|--------------|----------------|----------|
| Debug | ✅ | ✅ | ❌ |
| STRIP_ALL | ✅ | ❌ | ✅ |
| FINAL_STRIP | ❌ | ❌ | ✅✅ |
## Design Decisions (All Agreed Upon)
1. **FILE:LINE Info**: ✅ Include (worth 200 bytes for debugging)
2. **ALL_OPTIONS**: ❌ Manual opt-in only (too dangerous for testing)
3. **FATAL_ASSERT**: ✅ Add macro (semantic clarity for invariants)
4. **Strip Hierarchy**: ✅ STRIP_ALL keeps checks, FINAL_STRIP removes all
5. **Naming**: ✅ FATAL_* prefix (clear intent, conventional)
## Size Impact
Current: 10 abort() calls in production code
- ring_buffer.cc: 7 checks (~350 bytes)
- miniaudio_backend.cc: 3 checks (~240 bytes)
Estimated savings with FINAL_STRIP: ~500-600 bytes
## Documentation
Updated:
- doc/HOWTO.md: Added FINAL_STRIP build instructions
- doc/CONTRIBUTING.md: Added fatal error checking guidelines
- src/util/fatal_error.h: Comprehensive usage documentation
## Next Steps (Not in This Commit)
Phase 2: Convert ring_buffer.cc abort() calls to FATAL_CHECK()
Phase 3: Convert miniaudio_backend.cc abort() calls to FATAL_CHECK()
Phase 4: Systematic scan for remaining abort() calls
Phase 5: Verify size reduction with actual measurements
## Usage
# Convenience methods
make final # From normal build directory
./scripts/build_final.sh # Creates build_final/
# Manual
cmake -S . -B build_final -DDEMO_FINAL_STRIP=ON
cmake --build build_final
⚠️ WARNING: FINAL_STRIP builds have NO error checking.
Use ONLY for final release, never for development/testing.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
Split monolithic asset_manager.h (61 lines) into 3 focused headers:
- asset_manager_dcl.h: Forward declarations (AssetId, ProcGenFunc)
- asset_manager.h: Core API (GetAsset, DropAsset, AssetRecord)
- asset_manager_utils.h: Typed helpers (TextureAsset, MeshAsset)
Updated 17 source files to use appropriate headers:
- object.h: Uses dcl.h (only needs AssetId forward declaration)
- 7 files using TextureAsset/MeshAsset: Use utils.h
- 10 files using only GetAsset(): Keep asset_manager.h
Performance improvement:
- Before: Touch asset_manager.h → 4.82s (35 files rebuild)
- After: Touch asset_manager_utils.h → 2.01s (24 files rebuild)
- Improvement: 58% faster for common workflow (tweaking mesh/texture helpers)
Note: Touching base headers (dcl/core) still triggers ~33 file rebuilds
due to object.h dependency chain. Further optimization would require
reducing object.h's footprint (separate task).
Files changed:
- Created: asset_manager_dcl.h, asset_manager_utils.h
- Modified: asset_manager.h (removed structs), asset_manager.cc
- Updated: object.h, visual_debug.h, renderer_mesh.cc,
flash_cube_effect.cc, hybrid_3d_effect.cc, test files
|
|
Fixed critical bug causing mesh and bounding box stretching during rotation.
ROOT CAUSE:
quat::from_axis() did not normalize the input axis vector. When called
with non-unit vectors (e.g., {0.5, 1.0, 0.0}), it created invalid
quaternions that encoded scaling transformations instead of pure rotations.
SYMPTOMS:
- Mesh vertices stretched during rotation (non-uniform scaling)
- Bounding boxes deformed and stretched
- Transform matrices became non-orthogonal
ISSUE LOCATIONS:
- src/tests/test_mesh.cc:309 - axis {0.5, 1.0, 0.0} (length ≈1.118)
- src/gpu/effects/flash_cube_effect.cc:79 - axis {0.3, 1, 0.2} (length ≈1.044)
FIX:
Added automatic normalization in quat::from_axis():
a = a.normalize(); // Ensure axis is unit vector
RESULT:
- All quaternions now represent pure rotations
- No scaling artifacts during rotation
- Bounding boxes remain orthogonal
- Fixes Task A (test_mesh stretching bug)
SAFETY:
This change is backward compatible. Code that already passed normalized
axes will work identically (normalizing a unit vector = identity).
handoff(Claude): Rotation stretching bug fixed. Both shader normal
transformation (previous commit) and quaternion creation (this commit)
now work correctly. test_mesh should display properly rotated meshes
without distortion.
|
|
Added support for loading and rendering OBJ meshes.
- Updated asset_packer to parse .obj files into a binary format.
- Added MeshAsset and GetMeshAsset helper to asset_manager.
- Extended Object3D with mesh_asset_id and ObjectType::MESH.
- Implemented mesh rasterization pipeline in Renderer3D.
- Added a sample cube mesh and verified in test_3d_render.
|
|
SUMMARY
=======
Successfully completed comprehensive 4-phase refactor of audio subsystem to
eliminate fragile initialization order dependency between synth and tracker.
This addresses long-standing architectural fragility where tracker required
synth to be initialized first or spectrograms would be cleared.
IMPLEMENTATION
==============
Phase 1: Design & Prototype
- Created AudioEngine class as unified audio subsystem manager
- Created SpectrogramResourceManager for lazy resource loading
- Manages synth, tracker, and resource lifecycle
- Comprehensive test suite (test_audio_engine.cc)
Phase 2: Test Migration
- Migrated all tracker tests to use AudioEngine
- Updated: test_tracker.cc, test_tracker_timing.cc,
test_variable_tempo.cc, test_wav_dump.cc
- Pattern: Replace synth_init() + tracker_init() with engine.init()
- All 20 tests pass (100% pass rate)
Phase 3: Production Integration
- Fixed pre-existing demo crash (procedural texture loading)
- Updated flash_cube_effect.cc and hybrid_3d_effect.cc
- Migrated main.cc to use AudioEngine
- Replaced tracker_update() calls with engine.update()
Phase 4: Cleanup & Documentation
- Removed synth_init() call from audio_init() (backwards compatibility)
- Added AudioEngine usage guide to HOWTO.md
- Added audio initialization protocols to CONTRIBUTING.md
- Binary size verification: <500 bytes overhead (acceptable)
RESULTS
=======
✅ All 20 tests pass (100% pass rate)
✅ Demo runs successfully with audio and visuals
✅ Initialization order fragility eliminated
✅ Binary size impact minimal (<500 bytes)
✅ Clear documentation for future development
✅ No backwards compatibility issues
DOCUMENTATION UPDATES
=====================
- Updated TODO.md: Moved Task #56 to "Recently Completed"
- Updated PROJECT_CONTEXT.md: Added AudioEngine milestone
- Updated HOWTO.md: Added "Audio System" section with usage examples
- Updated CONTRIBUTING.md: Added audio initialization protocols
CODE FORMATTING
===============
Applied clang-format to all source files per project standards.
FILES CREATED
=============
- src/audio/audio_engine.h (new)
- src/audio/audio_engine.cc (new)
- src/audio/spectrogram_resource_manager.h (new)
- src/audio/spectrogram_resource_manager.cc (new)
- src/tests/test_audio_engine.cc (new)
KEY FILES MODIFIED
==================
- src/main.cc (migrated to AudioEngine)
- src/audio/audio.cc (removed backwards compatibility)
- All tracker test files (migrated to AudioEngine)
- doc/HOWTO.md (added usage guide)
- doc/CONTRIBUTING.md (added protocols)
- TODO.md (marked complete)
- PROJECT_CONTEXT.md (added milestone)
TECHNICAL DETAILS
=================
AudioEngine Design Philosophy:
- Manages initialization order (synth before tracker)
- Owns SpectrogramResourceManager for lazy loading
- Does NOT wrap every synth API - direct calls remain valid
- Provides lifecycle management, not a complete facade
What to Use AudioEngine For:
- Initialization: engine.init() instead of separate init calls
- Updates: engine.update(music_time) instead of tracker_update()
- Cleanup: engine.shutdown() for proper teardown
- Seeking: engine.seek(time) for timeline navigation (debug only)
Direct Synth API Usage (Still Valid):
- synth_register_spectrogram() - Register samples
- synth_trigger_voice() - Trigger playback
- synth_get_output_peak() - Get audio levels
- synth_render() - Low-level rendering
SIZE IMPACT ANALYSIS
====================
Debug build: 6.2MB
Size-optimized build: 5.0MB
Stripped build: 5.0MB
AudioEngine overhead: <500 bytes (0.01% of total)
BACKWARD COMPATIBILITY
======================
No breaking changes. Tests that need low-level control can still call
synth_init() directly. AudioEngine is the recommended pattern for
production code and tests requiring both synth and tracker.
handoff(Claude): Task #56 COMPLETE - All 4 phases finished. Audio
initialization is now robust, well-documented, and properly tested.
The fragile initialization order dependency has been eliminated.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
- Integrated stb_image for image decompression in asset_packer.
- Added GetTextureAsset helper in asset_manager.
- Updated procedural asset generation to include dimensions header for consistency.
- Updated test_assets to verify new asset format.
|
|
logging infrastructure
MILESTONE: Audio System Robustness & Debugging
Core Audio Backend Optimization:
- Fixed stop-and-go audio glitches caused by timing mismatch
- Core Audio optimized for 44.1kHz (10ms periods), but 32kHz expected ~13.78ms
- Added allowNominalSampleRateChange=TRUE to force OS-level 32kHz native
- Added performanceProfile=conservative for 4096-frame buffers (128ms)
- Result: Stable ~128ms callbacks, <1ms jitter, zero underruns
Ring Buffer Improvements:
- Increased capacity from 200ms to 400ms for tempo scaling headroom
- Added comprehensive bounds checking with abort() on violations
- Fixed tempo-scaled buffer fill: dt * g_tempo_scale
- Buffer maintains 400ms fullness during 2.0x acceleration
NOTE_ Parsing Fix & Sample Caching:
- Fixed is_note_name() checking only first letter (A-G)
- ASSET_KICK_1 was misidentified as A0 (27.5 Hz)
- Required "NOTE_" prefix to distinguish notes from assets
- Updated music.track to use NOTE_E2, NOTE_G4 format
- Discovered resource exhaustion: 14 unique samples → 228 registrations
- Implemented comprehensive caching in tracker_init()
- Assets: loaded once from AssetManager, cached synth_id
- Generated notes: created once, stored in persistent pool
- Result: MAX_SPECTROGRAMS 256 → 32 (88% memory reduction)
Debug Logging Infrastructure:
- Created src/util/debug.h with 7 category macros
(AUDIO, RING_BUFFER, TRACKER, SYNTH, 3D, ASSETS, GPU)
- Added DEMO_ENABLE_DEBUG_LOGS CMake option (defines DEBUG_LOG_ALL)
- Converted all diagnostic code to use category macros
- Default build: macros compile to ((void)0) for zero runtime cost
- Debug build: comprehensive logging for troubleshooting
- Updated CONTRIBUTING.md with pre-commit policy
Resource Analysis Tool:
- Enhanced tracker_compiler to report pool sizes and cache potential
- Analysis: 152/228 spectrograms without caching, 14 with caching
- Tool generates optimization recommendations during compilation
Files Changed:
- CMakeLists.txt: Add DEBUG_LOG option
- src/util/debug.h: New debug logging header (7 categories)
- src/audio/miniaudio_backend.cc: Use DEBUG_AUDIO/DEBUG_RING_BUFFER
- src/audio/ring_buffer.cc: Use DEBUG_RING_BUFFER for underruns
- src/audio/tracker.cc: Implement sample caching, use DEBUG_TRACKER
- src/audio/synth.cc: Use DEBUG_SYNTH for validation
- src/audio/synth.h: Update MAX_SPECTROGRAMS (256→32), document caching
- tools/tracker_compiler.cc: Fix is_note_name(), add resource analysis
- assets/music.track: Update to use NOTE_ prefix format
- doc/CONTRIBUTING.md: Add debug logging pre-commit policy
- PROJECT_CONTEXT.md: Document milestone
- TODO.md: Mark tasks completed
Verification:
- Default build: No debug output, audio plays correctly
- Debug build: Comprehensive logging, audio plays correctly
- Caching working: 14 unique samples cached at init
- All tests passing (17/17)
handoff(Claude): Audio system now stable with robust diagnostic infrastructure.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
- Updated ProcGenFunc signature to return bool for error reporting.
- Implemented gen_perlin (Fractional Brownian Motion) in procedural/generator.cc.
- Added support for sky texture in Renderer3D and its shader.
- Integrated Perlin noise sky texture in test_3d_render.cc.
- Caught and handled memory/generation errors in AssetManager and TextureManager.
- Assigned reference numbers to all remaining tasks in documentation.
handoff(Gemini): Side-quest complete. ProcGenFunc now returns bool. Perlin noise added and used for sky in 3D test. Windows build remains stable. All tasks numbered.
|
|
- Consolidated all WebGPU shims and platform-specific logic into src/platform.h.
- Refactored platform_init to return PlatformState by value and platform_poll to automatically refresh time and aspect_ratio.
- Removed STL dependencies (std::map, std::vector, std::string) from AssetManager and Procedural subsystems.
- Fixed Windows cross-compilation by adjusting include paths and linker flags in CMakeLists.txt and updating build_win.sh.
- Removed redundant direct inclusions of GLFW/glfw3.h and WebGPU headers across the project.
- Applied clang-format and updated documentation.
handoff(Gemini): Completed Task #20 and 20.1. Platform abstraction is now unified, and core paths are STL-free. Windows build is stable.
|
|
Replaces the global array with which wraps a local static array. This ensures the asset table is initialized on first use, preventing crashes when other globals (like shader strings) try to access assets during dynamic initialization.
|
|
Updates asset_packer to align static asset arrays to 16 bytes and append a null-terminator. This allows assets to be safely reinterpreted as typed pointers (e.g., float*, const char*) without copying. Updates AssetManager documentation to reflect these guarantees.
|
|
- Adjusted Torus proxy hull in vs_main to 1.5x0.5x1.5 for better SDF fit.
- Updated VisualDebug::add_box to use per-object local extents.
- Standardized floor grid mapping in fs_main using planar p.xz projection.
- Verified non-uniform scale and rotation robustness in test_3d_render.
|
|
- Updated VisualDebug to accept mat4 transforms, enabling wireframes to follow rotating objects.
- Restored SDF bump mapping and floor grid texture in the fragment shader.
- Added vec4::xyz() helper to mini_math.h.
- Fixed Renderer3D to pass the full model matrix for debug visualization.
|
|
- Implemented dynamic resolution support in all shaders and effects.
- Added explicit viewport setting for all render passes to ensure correct scaling.
- Fixed 3D shadow mapping by adding PLANE support and standardizing soft shadow logic.
- Propagated resize events through the Effect hierarchy.
- Applied project-wide code formatting.
|
|
- Implemented full support for non-uniform scaling by calculating and passing the 'model_inverse_transpose' matrix to the shader for correct normal transformation.
- Added 'transpose()' and 'inverse()' methods to the 'mat4' class in 'mini_math.h'.
- Refactored the shader to use the new matrix for lighting rasterized objects.
- Updated the test scene to use a rasterized floor (CUBE) instead of an SDF one, ensuring it receives correct lighting and shadows even with non-uniform scale.
|
|
- Task A: Centralized all generated code (assets, timeline) into a single directory to create a single source of truth.
- Task A: Isolated test asset generation into a temporary build directory, preventing pollution of the main source tree.
- Task B: Vertically compacted all C/C++ source files by removing superfluous newlines.
- Task C: Created a top-level README.md with project overview and file descriptions.
- Task D: Moved non-essential documentation into a directory to reduce root-level clutter.
|
|
- Fixed test_sequence by restoring MainSequence::init_test for mocking.
- Corrected CMakeLists.txt dependencies and source groupings to prevent duplicate symbols.
- standardizing Effect constructor signature for seq_compiler compatibility.
- Implemented Hybrid3DEffect using bumpy Renderer3D and procedural NOISE_TEX.
- Updated MainSequence to support depth buffer for 3D elements.
- Formatted all source files with clang-format.
|
|
- Updated asset_packer to parse PROC(...) syntax.
- Implemented runtime dispatch in AssetManager for procedural generation.
- Added procedural generator functions (noise, grid, periodic).
- Added comprehensive tests for procedural asset lifecycle.
|
|
- Refactored asset manager to use a static array for caching, improving performance and memory efficiency.
- Updated asset_packer to correctly generate ASSET_LAST_ID for array sizing.
- Modified asset_manager.h to use a forward declaration for AssetId.
- Updated asset_manager.cc to use the conditional include for generated asset headers.
- Added a test case in test_assets to verify the array-based cache and ASSET_LAST_ID logic.
|
|
- Extended mini_math.h with mat4 multiplication and affine transforms.
- Implemented TextureManager for runtime procedural texture generation and GPU upload.
- Added 3D system components: Camera, Object, Scene, and Renderer3D.
- Created test_3d_render mini-demo for interactive 3D verification.
- Fixed WebGPU validation errors regarding depthSlice and unimplemented WaitAny.
|
|
|
|
- Enabled AllowShortFunctionsOnASingleLine: All
- Enabled AllowShortBlocksOnASingleLine: Always
- Enabled AllowShortIfStatementsOnASingleLine: Always
- Enabled AllowShortLoopsOnASingleLine: true
- Set MaxEmptyLinesToKeep: 1
- Applied formatting to all source files.
|
|
- Updated CMakeLists.txt to generate assets.h and assets_data.cc in src/generated/.
- Updated scripts/gen_assets.sh to reflect the new output location.
- Modified asset_packer.cc to generate correct include paths in assets_data.cc.
- Updated source files (main.cc, asset_manager.cc, test_assets.cc) to include headers from the 'generated/' subdirectory.
- Ensured all targets have correct include paths to find generated headers.
- Removed stale generated files from src/.
|
|
|
|
system
|
|
|
|
|
|
This refactors the asset management system to be more efficient and cleaner.
- Moved common GetAsset/DropAsset logic to src/util/asset_manager.cc.
- Changed retrieval to use an array of records (AssetRecord) for O(1) lookups instead of a switch statement.
- Updated asset_packer to generate only raw data and the record array.
|
|
This commit applies a new project-wide rule that every source file must begin with a concise 3-line comment header describing its purpose.
- Updated CONTRIBUTING.md with the new rule.
- Applied headers to all .cc and .h files in src/ and tools/.
- Fixed various minor compilation errors and missing includes discovered during the header update process.
|
|
|
