summaryrefslogtreecommitdiff
path: root/doc/HOWTO.md
AgeCommit message (Collapse)Author
16 hoursrefactor: Reorganize tests into subsystem subdirectoriesskal
Restructured test suite for better organization and targeted testing: **Structure:** - src/tests/audio/ - 15 audio system tests - src/tests/gpu/ - 12 GPU/shader tests - src/tests/3d/ - 6 3D rendering tests - src/tests/assets/ - 2 asset system tests - src/tests/util/ - 3 utility tests - src/tests/common/ - 3 shared test helpers - src/tests/scripts/ - 2 bash test scripts (moved conceptually, not physically) **CMake changes:** - Updated add_demo_test macro to accept LABEL parameter - Applied CTest labels to all 36 tests for subsystem filtering - Updated all test file paths in CMakeLists.txt - Fixed common helper paths (webgpu_test_fixture, etc.) - Added custom targets for subsystem testing: - run_audio_tests, run_gpu_tests, run_3d_tests - run_assets_tests, run_util_tests, run_all_tests **Include path updates:** - Fixed relative includes in GPU tests to reference ../common/ **Documentation:** - Updated doc/HOWTO.md with subsystem test commands - Updated doc/CONTRIBUTING.md with new test organization - Updated scripts/check_all.sh to reflect new structure **Verification:** - All 36 tests passing (100%) - ctest -L <subsystem> filters work correctly - make run_<subsystem>_tests targets functional - scripts/check_all.sh passes Backward compatible: make test and ctest continue to work unchanged. handoff(Gemini): Test reorganization complete. 36/36 tests passing.
17 hoursdocs: Streamline headless mode documentationskal
Summary: - HEADLESS_MODE.md: 58→32 lines (-45%) - HOWTO.md: Condensed to one-liner + reference - Removed implementation details (in code comments) - Simplified comparison table - Clearer use case description handoff(Claude): Documentation cleanup
17 hoursfeat: Add headless mode for testing without GPUskal
Implements DEMO_HEADLESS build option for fast iteration cycles: - Functional GPU/platform stubs (not pure no-ops like STRIP_EXTERNAL_LIBS) - Audio and timeline systems work normally - No rendering overhead - Useful for CI, audio development, timeline validation Files added: - doc/HEADLESS_MODE.md - Documentation - src/gpu/headless_gpu.cc - Validated GPU stubs - src/platform/headless_platform.cc - Time simulation (60Hz) - scripts/test_headless.sh - End-to-end test script Usage: cmake -B build_headless -DDEMO_HEADLESS=ON cmake --build build_headless -j4 ./build_headless/demo64k --headless --duration 30 Progress printed every 5s. Compatible with --dump_wav mode. handoff(Claude): Task #76 follow-up - headless mode complete
17 hoursdocs: Update references to workspace layoutskal
Update all doc references from old paths to workspace structure: - assets/demo.seq → workspaces/main/timeline.seq - assets/music.track → workspaces/main/music.track - assets/final/demo_assets.txt → workspaces/main/assets.txt - assets/test_demo.* → workspaces/test/* Files updated: - HOWTO.md: Add workspace selection, update paths - SEQUENCE.md: Update examples and integration - ASSET_SYSTEM.md: Workspace-aware workflow - CONTRIBUTING.md: Workspace timeline paths - ARCHITECTURE.md: Generic workspace reference Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
18 hoursdocs: Condense HOWTO.md, move details to technical docsskal
- HOWTO.md: 184→97 lines (quick reference only) - BUILD.md: Add build modes, header organization, dependency tracking - ASSET_SYSTEM.md: Add developer workflow section - TRACKER.md: Add AudioEngine API documentation Net: -147 lines in HOWTO.md
18 hoursdocs: Update docs for Task #76 size measurementskal
- Add size measurement section to HOWTO.md - Move Task #76 to COMPLETED.md - Update TODO.md and PROJECT_CONTEXT.md - Document measurement results (Demo=4.4MB, External=2.0MB)
19 hoursdocs: Update documentation and clean up obsolete filesskal
- Add Task #76: External library size measurement - Update hot-reload documentation across README, HOWTO, PROJECT_CONTEXT - Update test count: 36/36 passing (100%) - Remove completed analysis files from root Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
21 hoursdocs: Condense essential context files (856→599 lines)skal
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 <noreply@anthropic.com>
24 hoursdocs: Archive Feb 9 completed tasks and clarify build configsskal
- Move completed tasks (Uniform alignment, WGSL validation, test_demo fix) to COMPLETED.md - Clean up TODO.md and PROJECT_CONTEXT.md "Recently Completed" sections - Update HOWTO.md to clarify DEMO_ALL_OPTIONS enables STRIP_ALL - Note: test_demo PeakMeterEffect requires non-STRIP build Net: -26 lines (better context hygiene) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
26 hoursdocs: Simplify all design docs (50% reduction, 1687 lines removed)skal
Consolidated and streamlined all documentation: **Merged:** - PROCEDURAL.md → deleted (content in ASSET_SYSTEM.md) - FETCH_DEPS.md → BUILD.md (dependencies section) **Simplified (line reductions):** - HOWTO.md: 468→219 (53%) - CONTRIBUTING.md: 453→173 (62%) - SPECTRAL_BRUSH_EDITOR.md: 497→195 (61%) - SEQUENCE.md: 355→197 (45%) - CONTEXT_MAINTENANCE.md: 332→200 (40%) - test_demo_README.md: 273→122 (55%) - ASSET_SYSTEM.md: 271→108 (60%) - MASKING_SYSTEM.md: 240→125 (48%) - 3D.md: 196→118 (40%) - TRACKER.md: 124→76 (39%) - SCENE_FORMAT.md: 59→49 (17%) - BUILD.md: 83→69 (17%) **Total:** 3344→1657 lines (50.4% reduction) **Changes:** - Removed verbose examples, redundant explanations, unimplemented features - Moved detailed task plans to TODO.md (single source of truth) - Consolidated coding style rules - Kept essential APIs, syntax references, technical details **PROJECT_CONTEXT.md:** - Added "Design Docs Quick Reference" with 2-3 line summaries - Removed duplicate task entries - All design docs now loaded on-demand via Read tool Result: Context memory files reduced from 31.6k to ~15k tokens.
39 hoursfeat(gpu): Add auxiliary texture masking systemskal
Implements MainSequence auxiliary texture registry to support inter-effect texture sharing within a single frame. Primary use case: screen-space partitioning where multiple effects render to complementary regions. Architecture: - MainSequence::register_auxiliary_texture(name, width, height) Creates named texture that persists for entire frame - MainSequence::get_auxiliary_view(name) Retrieves texture view for reading/writing Use case example: - Effect1: Generate mask (1 = Effect1 region, 0 = Effect2 region) - Effect1: Render scene A where mask = 1 - Effect2: Reuse mask, render scene B where mask = 0 - Result: Both scenes composited to same framebuffer Implementation details: - Added std::map<std::string, AuxiliaryTexture> to MainSequence - Texture lifecycle managed by MainSequence (create/resize/shutdown) - Memory impact: ~4-8 MB per mask (acceptable for 2-3 masks) - Size impact: ~100 lines (~500 bytes code) Changes: - src/gpu/effect.h: Added auxiliary texture registry API - src/gpu/effect.cc: Implemented registry with FATAL_CHECK validation - doc/MASKING_SYSTEM.md: Complete architecture documentation - doc/HOWTO.md: Added auxiliary texture usage example Also fixed: - test_demo_effects.cc: Corrected EXPECTED_POST_PROCESS_COUNT (9→8) Pre-existing bug: DistortEffect was counted but not tested Testing: - All 33 tests pass (100%) - No functional changes to existing effects - Zero regressions See doc/MASKING_SYSTEM.md for detailed design rationale and examples.
3 daysfeat(build): Add FINAL_STRIP mode for maximum size optimizationskal
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>
4 daysdocs: Document specplay tool and add future enhancement roadmapskal
- Created tools/specplay_README.md with comprehensive documentation - Added Task #64 to TODO.md for future specplay enhancements - Updated HOWTO.md with specplay usage examples and use cases - Outlined 5 priority levels of potential features (20+ ideas) Key enhancements planned: - Priority 1: Spectral visualization, waveform display, frequency analysis - Priority 2: Diff mode, batch analysis, CSV reports - Priority 3: WAV export, normalization - Priority 4: Advanced spectral analysis (harmonics, onsets) - Priority 5: Interactive mode (seek, loop, volume control) The tool is production-ready and actively used for debugging.
4 daysdocs: Update documentation for completed build optimization (Task C)skal
Updated documentation to reflect completed build system improvements: TODO.md: - Moved Task C to 'Recently Completed (February 6, 2026)' section - Documented header split (asset_manager_dcl/core/utils) - Documented asset dependency tracking (42 demo + 17 test assets) - Noted 58% performance improvement and critical correctness bug fix - Removed Task C from 'Critical Fixes' section (completed) PROJECT_CONTEXT.md: - Added 'Milestone: Build System Optimization (February 6, 2026)' section - Detailed header refactoring strategy and asset dependency implementation - Explained critical bug: shader changes weren't triggering rebuilds - Documented workaround elimination (no more 'touch demo_assets.txt') HOWTO.md: - Added 'Build System Notes' section after developer build instructions - Explained incremental build behavior and asset tracking - Documented header organization (dcl/core/utils) for developers - Clarified that all asset types (.wgsl, .spec, .obj) are tracked All documentation now accurately reflects current build system state. Ready to begin next task: Spectrogram Editor (HTML).
5 daysfeat(audio): Complete Phase 4 - Cleanup and Documentation (Task #56)skal
Completed final cleanup phase of Audio Lifecycle Refactor. Removed backwards compatibility shims and updated documentation to reflect new AudioEngine-based initialization patterns. Changes: 1. Removed Backwards Compatibility: - Removed synth_init() call from audio_init() in audio.cc - Added comment explaining AudioEngine is the preferred initialization method - All tests already explicitly call synth_init() or use AudioEngine 2. Documentation Updates: - Updated HOWTO.md with AudioEngine usage examples and best practices - Updated CONTRIBUTING.md with audio subsystem initialization protocols - Documented when to use AudioEngine vs direct synth API calls - Clarified that AudioEngine is a lifecycle manager, not a complete facade 3. Size Verification: - Size-optimized build: 5.0MB (vs 6.2MB debug) - AudioEngine overhead: <500 bytes (within acceptable limits) - No size regression from refactor Results: - All 20 tests pass (100% pass rate) - Demo runs successfully - No backwards compatibility issues - Clear documentation for future development - Binary size impact negligible Design Philosophy: - AudioEngine manages initialization order (synth before tracker) - Direct synth API calls remain valid for performance-critical paths - Low-level tests can still use synth_init() directly if needed - Preferred pattern: Use AudioEngine for lifecycle, direct APIs for operations handoff(Claude): Completed Task #56 Phase 4 - All phases complete! Audio Lifecycle Refactor is fully implemented, tested, and documented. The fragile initialization order dependency has been eliminated. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
6 daysfeat(tooling): Add directory filtering to coverage report script (Task #46)skal
Updated gen_coverage_report.sh to accept an optional argument for targeting specific directories using lcov --extract.
6 daysfeat(tooling): Implement code coverage reporting (Task #44)skal
Added CMake support for coverage builds and a script to generate HTML reports using lcov on macOS. Also cleaned up .gitignore.
8 daysdocs: Add submodule update instructions to HOWTO.mdskal
8 daysrefactor(build): Centralize generated files and clean up project layoutskal
- 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.
generated by cgit v1.2.3 (git 2.51.0) at 2026-02-10 11:16:46 +0000