diff options
| author | skal <pascal.massimino@gmail.com> | 2026-02-09 19:00:51 +0100 |
|---|---|---|
| committer | skal <pascal.massimino@gmail.com> | 2026-02-09 19:00:51 +0100 |
| commit | 46d4cb4d2cbdaa8461201680a134103b547e2063 (patch) | |
| tree | 0d3cc96818994e5a6093df73f4e38e71ba19812b | |
| parent | 512e0187e17ab6116c336885c1a9a6dc0a03f9d1 (diff) | |
docs: Streamline top-level documentation
Condense README, PROJECT_CONTEXT, and TODO:
- README: Remove verbose file listings, focus on quickstart
- PROJECT_CONTEXT: Condense status, remove recent completions
- TODO: Mark Task #77 complete, remove verbose details
- WORKSPACE_SYSTEM: Mark as completed
Details moved to individual doc/ files.
Net: -76 lines
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
| -rw-r--r-- | PROJECT_CONTEXT.md | 80 | ||||
| -rw-r--r-- | README.md | 44 | ||||
| -rw-r--r-- | TODO.md | 34 | ||||
| -rw-r--r-- | doc/WORKSPACE_SYSTEM.md | 12 |
4 files changed, 47 insertions, 123 deletions
diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index ae79bbf..ff6bc48 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -31,75 +31,33 @@ ## Current Status -- 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, .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: **36/36 tests passing (100%)** - All tests operational +- **Workspace system:** Multi-workspace support. Easy switching with `-DDEMO_WORKSPACE=<name>`. Shared common assets. +- **Audio:** Sample-accurate sync. Zero heap allocations per frame. Variable tempo. Comprehensive tests. +- **Shaders:** Parameterized effects (UniformHelper, .seq syntax). Modular WGSL composition. +- **3D:** Hybrid SDF/rasterization with BVH. Binary scene loader. Blender pipeline. +- **Build:** Asset dependency tracking. Size measurement. Hot-reload (debug-only). +- **Testing:** **36/36 passing (100%)** --- ## Next Up -**Active:** -- Task #5: Spectral Brush Editor [IN PROGRESS] - Procedural spectrogram tool (50-100× compression) - -**Visuals:** -- Task #52: Procedural SDF Font -- Task #53: Particles Shader Polish -- Task #55: SDF Random Planes Intersection - -**Structure:** -- Task #77: Workspace System - Self-contained demo workspaces - -**Tooling:** -- Task #54: Tracy Integration -- Task #76: External Library Size Measurement - -**Details:** See `TODO.md` and individual design docs - ---- - -## Design Docs Reference - -**Core Systems:** -- `doc/ASSET_SYSTEM.md` - Build-time asset packer, 16-byte alignment -- `doc/SEQUENCE.md` - .seq timeline format with BPM notation -- `doc/TRACKER.md` - Audio pattern system, unit-less timing -- `doc/3D.md` - Hybrid SDF raymarching with BVH acceleration - -**Formats:** -- `doc/SCENE_FORMAT.md` - Binary scene format (SCN1) -- `doc/MASKING_SYSTEM.md` - Auxiliary texture registry - -**Tools & Workflow:** -- `doc/BUILD.md` - Multi-platform builds (Debug/STRIP_ALL/FINAL_STRIP) -- `doc/SPECTRAL_BRUSH_EDITOR.md` - Procedural spectrogram tool -- `doc/WORKSPACE_SYSTEM.md` - Multi-demo organization -- `doc/HOT_RELOAD.md` - Debug-only file change detection -- `doc/SIZE_MEASUREMENT.md` - External library size measurement -- `doc/test_demo_README.md` - 16s audio/visual sync test - -**Meta:** -- `doc/CONTEXT_MAINTENANCE.md` - Context hygiene protocol +See `TODO.md` for current priorities and active tasks. --- -## Recently Completed +## Documentation -**Feb 9, 2026:** -- Size measurement system (Task #76) - Demo: 4.4MB, External: 2.0MB -- Hot-reload file watcher (debug-only, 0 bytes overhead) -- WGSL uniform buffer validation (Task #75) -- Uniform buffer alignment fixes (Task #74) - -**Feb 8, 2026:** -- Shader parametrization system (Task #73) - ---- +**Essential:** +- `doc/ARCHITECTURE.md` - System architecture and design decisions +- `doc/HOWTO.md` - Common operations and workflows +- `doc/CONTRIBUTING.md` - Development protocols -For detailed architecture, see `doc/ARCHITECTURE.md`. +**Technical Reference:** +- Core: `ASSET_SYSTEM.md`, `SEQUENCE.md`, `TRACKER.md`, `3D.md` +- Formats: `SCENE_FORMAT.md`, `MASKING_SYSTEM.md` +- Tools: `BUILD.md`, `WORKSPACE_SYSTEM.md`, `SIZE_MEASUREMENT.md` -For completed tasks history, see `doc/COMPLETED.md` and git history. +**History:** +- `doc/COMPLETED.md` - Completed tasks archive +- Git log for detailed change history @@ -1,46 +1,20 @@ # 64k Demo Project -This is a C++ project aiming to create a cross-platform (Windows, macOS, Linux) 64-kilobyte demo. +Cross-platform (Windows, macOS, Linux) 64-kilobyte demoscene production. ## Quickstart -Development setup: - ```bash cmake -S . -B build -DDEMO_ALL_OPTIONS=ON -cmake --build build +cmake --build build -j4 +./build/demo64k ``` -## Project Files - -- `ASSET_SYSTEM.md`: Describes the custom asset packing and management system. -- `BUILD.md`: Instructions for building the project. -- `CONTRIBUTING.md`: Guidelines for contributing, including coding style and commit policies. -- `FETCH_DEPS.md`: Information on third-party dependencies. -- `HOT_RELOAD.md`: Debug-only file change detection system. -- `HOWTO.md`: General instructions for running and interacting with the demo. -- `PHASE2_COMPRESSION.md`: Details on future asset compression strategies. -- `PROCEDURAL.md`: Details on the procedural texture generation system. -- `PROJECT_CONTEXT.md`: A comprehensive overview of the project's architecture, features, and current state. -- `SEQUENCE.md`: Complete reference for `.seq` file format and timeline system. -- `SIZE_MEASUREMENT.md`: Strategy for measuring core demo size vs external library overhead. -- `SPEC_EDITOR.md`: Plans for a future web-based spectrogram editor tool. -- `WORKSPACE_SYSTEM.md`: Multi-demo workspace organization architecture. -- `3D.md`: Overview of the 3D rendering pipeline and future enhancements. -- `TODO.md`: A list of immediate, small-scale tasks. - -## Source Code Layout +## Documentation -The source code is organized into the following main directories: +- **PROJECT_CONTEXT.md** - Current status and architecture overview +- **TODO.md** - Active tasks and priorities +- **doc/HOWTO.md** - Common operations (building, testing, assets) +- **doc/CONTRIBUTING.md** - Development guidelines and protocols -- `src/`: The main C++ source code for the demo. - - `3d/`: Core 3D rendering components (camera, scene, renderer). - - `audio/`: Audio synthesis and processing engine. - - `gpu/`: WebGPU rendering pipeline, effects, and shader management. - - `procedural/`: Procedural content generation (textures, etc.). - - `tests/`: Unit and integration tests for various components. - - `util/`: Shared utility classes, like the asset manager. -- `assets/`: Raw assets (audio, sequence files) that are processed and packed. -- `scripts/`: Helper scripts for building, packaging, and running the demo. -- `tools/`: Source code for command-line tools used in the asset pipeline (e.g., `asset_packer`, `spectool`). -- `third_party/`: Third-party libraries like miniaudio and glfw3webgpu. +See `doc/` for detailed technical documentation. @@ -8,27 +8,19 @@ ## Priority 1: Spectral Brush Editor (Task #5) [IN PROGRESS] -Web-based tool for procedurally tracing audio spectrograms. Replaces large `.spec` assets with tiny C++ code (50-100× compression). +Procedural spectrogram tool: 50-100× compression (5 KB .spec → ~100 bytes C++). **Design:** `doc/SPECTRAL_BRUSH_EDITOR.md` -**Phases:** C++ Runtime → Editor Core → File I/O → Extensions - -**Impact:** 5 KB .spec → ~100 bytes C++ code - --- -## Priority 2: Workspace System (Task #77) +## ~~Priority 2: Workspace System (Task #77)~~ [COMPLETED] -Self-contained workspaces for parallel demo development. Each workspace contains timeline, music, assets, and shaders. +Self-contained workspaces for parallel demo development. **Design:** `doc/WORKSPACE_SYSTEM.md` -**Structure:** `/workspaces/{main,test,...}` + `/assets/common/` for shared resources - -**Benefit:** Clean separation, easy switching (`-DDEMO_WORKSPACE=main`), scales to multiple demos - -**Effort:** 12-16 hours +**Usage:** `cmake -B build -DDEMO_WORKSPACE=main` --- @@ -42,24 +34,18 @@ Pipeline for importing complex 3D scenes to replace hardcoded geometry. ## Priority 4: WGSL Modularization (Task #50) [RECURRENT] -Ongoing shader code hygiene. Refactor for granular, reusable snippets. - -**Sub-tasks:** -- Split `common_uniforms.wgsl` into separate files (Low priority) -- Type-safe shader composition to prevent raw string usage (Low priority) +Ongoing shader code hygiene for granular, reusable snippets. --- ## Future: Size Optimization (64k Target) -Final phase tasks for reaching 64KB binary size: - -- **Task #22:** Windows Native Platform (replace GLFW with Win32) -- **Task #28:** Spectrogram Quantization (optimize frequency distribution) -- **Task #34:** Full STL Removal (custom containers) -- **Task #35:** CRT Replacement (CRT-free entry) +- Task #22: Windows Native Platform (Win32) +- Task #28: Spectrogram Quantization +- Task #34: Full STL Removal +- Task #35: CRT Replacement -**Measurement:** Use `./scripts/measure_size.sh` to track progress (Task #76 complete) +**Measure:** `./scripts/measure_size.sh` --- diff --git a/doc/WORKSPACE_SYSTEM.md b/doc/WORKSPACE_SYSTEM.md index 45fb064..e8e2615 100644 --- a/doc/WORKSPACE_SYSTEM.md +++ b/doc/WORKSPACE_SYSTEM.md @@ -1,8 +1,14 @@ -# Workspace System (Task #77) +# Workspace System (Task #77) [COMPLETED] -## Goal +## Status -Reorganize project to support multiple self-contained demo workspaces, enabling parallel development and clean separation of content. +**Implemented:** Feb 9, 2026 + +Workspace system is now active. Use `cmake -B build -DDEMO_WORKSPACE=<name>` to select workspace. + +## Overview + +Self-contained demo workspaces for parallel development and clean content separation. **Motivation:** Current structure scatters demo content across multiple locations: - `assets/demo.seq` - Timeline |
