summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorskal <pascal.massimino@gmail.com>2026-02-09 19:00:51 +0100
committerskal <pascal.massimino@gmail.com>2026-02-09 19:00:51 +0100
commit46d4cb4d2cbdaa8461201680a134103b547e2063 (patch)
tree0d3cc96818994e5a6093df73f4e38e71ba19812b
parent512e0187e17ab6116c336885c1a9a6dc0a03f9d1 (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.md80
-rw-r--r--README.md44
-rw-r--r--TODO.md34
-rw-r--r--doc/WORKSPACE_SYSTEM.md12
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
diff --git a/README.md b/README.md
index 0117a77..f7d78de 100644
--- a/README.md
+++ b/README.md
@@ -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.
diff --git a/TODO.md b/TODO.md
index aad105e..d7d24bc 100644
--- a/TODO.md
+++ b/TODO.md
@@ -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