From aa78a3e6a4e7c88f027af01a24165faf78273a64 Mon Sep 17 00:00:00 2001 From: skal Date: Mon, 2 Feb 2026 12:29:41 +0100 Subject: docs: Refactor and prioritize project task lists - Restructured PROJECT_CONTEXT.md to introduce a clear roadmap with 'Next Up', 'In Progress', and 'Future Goals'. - Condensed the 'Session Decisions' section into a concise 'Architectural Overview' focusing on the current state. - Updated TODO.md to reflect the highest priority tasks: finalizing the build system and optimizing spectrogram assets. --- PROJECT_CONTEXT.md | 111 +++++++++++++++++++++++++---------------------------- 1 file changed, 52 insertions(+), 59 deletions(-) (limited to 'PROJECT_CONTEXT.md') diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 2d3e21d..ca8a858 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -23,65 +23,58 @@ Style: - Demoscene - No engine abstractions -Incoming tasks in no particular order: -- [x] 1. add a fullscreen mode (as command line option) -- [x] 2. parse the keyboard key. Exit the demo when 'esc' is pressed. Toggle full-screen when 'f' is pressed. -- [x] 3. add binary crunchers for all platforms -- [ ] 4. add cross-compilation for PC+linux (x86_64) and PC+Windows (.exe binary) - - [x] a. PC+Windows (.exe binary) via MinGW - - [ ] b. PC+linux (x86_64) - - [ ] c. have a shell script (check_all.sh) under scripts/ to verify all builds (PC, MacOS, Win64) for all config. To be run before a major commit. Script can be slow to pass, doesn't matter. -- 5. implement a spectrogram editor for representing .spec with elementary shapes (bezier curves, lines, random noise, rectangles...) as a mean of compression / spec generation -- [x] 6. add a scripting tool to edit the demo (compiled into the binary at the end) -- [x] 7. compile wgpu-native in optimized mode (not unoptimized) -- [x] 8. add a #define STRIP_ALL to remove all unnecessary code for the final build (for instance, command-line args parsing, or unnecessary options, constant parameters to function calls, etc.) - Sub-tasks to define an overall code-stripping rule (to be captured in the CONTRIBUTING.md rules): - - [ ] a. function implementations are removed - - [ ] b. useless struct fields are removed (is_fullscreen_, debug_mode_, etc. e.g.) - - [ ] c. static arrays are malloc'd instead of initialized to zero - - [ ] d. code is simplified for size if possible (propose an alternate code implementation inside a STRIP_ALL #ifdef if needed) -- [x] 9. work on the compact in-line and off-line asset system (@ASSET_SYSTEM.md) -- 10. optimize spectool to remove trailing zeroes from a spec file before saving it. Remove the leading zeroes too. -- [x] 11. implement a general [time / timer / beat] system in the demo, for effects timing -- [x] 12. Implement 'Sequence' and 'Effect' system: - - `Effect` interface: `init`, `start`, `compute`, `render`, `end`, `priority`. - - `Sequence` manager: Handles a list of temporally sorted `SequenceItem`s. - - `MainSequence`: Manages global resources (`device`, `queue`) and orchestrates the frame render. - - Refactored `gpu.cc` to use `MainSequence`. - - Moved concrete effects to `src/gpu/demo_effects.cc`. -- 13. Implement Procedural Texture system (Task #3 -> #1): - - `src/procedural/` module (Done). - - Integration with WebGPU: Generate textures at runtime and upload to GPU (Done). - - `src/gpu/texture_manager` implemented and tested. -- 14. Implement 3D system (Task #1 -> #2): - - `src/3d/` module (math, camera, scene, renderer) (Done). - - `Renderer3D` implemented with basic cube rendering (Done). - - `test_3d_render` mini-demo created (Debugging crash in `wgpuInstanceWaitAny`). -- 15. Shader Logic (Task #2 -> #3): - - Ray-object intersection & SDF rendering in WGSL (Done). - - SDF Box, Sphere, Torus implemented. - - Hybrid normal calculation (Analytical + Numerical) (Done). - - Bump mapping with procedural noise (Done). - - Periodic texture generation (Done). -- [x] 16. Integrate 3D Renderer into Main Demo: - - Update `main.cc` / `gpu.cc` to use `Renderer3D`. - - Apply Gaussian Blur and Chromatic Aberration post-processing. - -* **[x] 17. Implement Asset Manager Caching & Procedural Generation** - * 17a. **(Task a)** Implemented array-based caching in `asset_manager.cc` for `GetAsset` (Done). - * 17b. **(Task b)** Modify `asset_packer` to parse a new `PROC(function_name)` compression method. This will generate a record mapping an Asset ID to the procedural function's name. - * 17c. **(Task b)** Implement a runtime dispatcher in `GetAsset`. When a `PROC` asset is requested, the dispatcher will look up the function by its name and execute it. The result will then be cached. - * 17d. **(Task c)** Update the asset management test suite to include a test case with `PROC(function_name)` in `test_assets_list.txt` to verify the generation and caching. - * 17e. **(Task d)** Integrate into `demo64k` by adding a procedural noise texture to `demo_assets.txt` and using this new mechanism in the `Hybrid3DEffect` for bump mapping. - -## Session Decisions and Current State - -### 3D Renderer Implementation -- **Renderer3D**: Encapsulates pipeline creation and render pass recording. -- **Shader**: Currently uses a simple vertex/fragment shader for cubes. -- **Storage**: Objects are stored in a `StorageBuffer` (instance data). -- **Test Tool**: `test_3d_render` created to isolate 3D development. -- **Issue**: `test_3d_render` crashes with "not implemented" in `wgpuInstanceWaitAny` on macOS. +--- +## Project Roadmap + +### Next Up +- **Task #4: Finalize Build System** + - [ ] 4a. Implement Linux cross-compilation from macOS. + - [ ] 4b. Create `scripts/check_all.sh` to build and test all platform targets (macOS, Windows, Linux) to ensure stability before commits. +- **Task #10: Optimize Spectrogram Assets** + - [ ] Modify `spectool` to trim leading and trailing silent frames from `.spec` files to reduce asset size. + +### In Progress +- **Task #8: Implement Final Build Stripping** + - [ ] Define and document a consistent set of rules for code stripping under the `STRIP_ALL` macro. + - [ ] Example sub-tasks: remove unused functions, strip debug fields from structs, simplify code paths where possible. + +### Future Goals +- **Task #5: Implement Spectrogram Editor** + - [ ] Develop a web-based tool (`tools/editor`) for creating and editing `.spec` files visually. + - [ ] The tool should support generating `.spec` files from elementary shapes (lines, curves) for extreme compression. +- **Phase 2: Advanced Size Optimization** + - [ ] Replace GLFW with a minimal native Windows API layer. + - [ ] Investigate and implement advanced asset compression techniques (e.g., logarithmic frequency, quantization). + - [ ] Explore replacing the standard C/C++ runtime with a more lightweight alternative. + +--- +*For a list of completed tasks, see the git history.* + +## Architectural Overview + +### Sequence & Effect System +- **Core Idea**: The demo is orchestrated by a powerful sequence and effect system. +- **`Effect`**: An abstract base class for any visual element (e.g., 3D scene, post-processing). Effects are managed within a timeline. +- **`Sequence`**: A timeline that manages the start and end times of multiple `Effect`s. +- **`MainSequence`**: The top-level manager that holds core WebGPU resources and renders the active `Sequence`s for each frame. +- **`seq_compiler`**: A custom tool that transpiles a simple text file (`assets/demo.seq`) into a C++ timeline (`timeline.cc`), allowing for rapid iteration on the demo's choreography without recompiling the engine. + +### Asset & Build System +- **`asset_packer`**: A tool that packs binary assets (like `.spec` files) into C++ arrays. +- **Runtime Manager**: A highly efficient, array-based lookup system (`GetAsset`) provides O(1) access to all packed assets. +- **Procedural Assets**: The system supports `PROC(function, params...)` syntax in asset lists, enabling runtime generation of assets like noise textures. The `asset_packer` stores the function name, and a runtime dispatcher executes the corresponding C++ function. +- **Automation**: The entire build, asset generation, and packaging process is automated via CMake and helper scripts (`gen_assets.sh`, `build_win.sh`). + +### Audio Engine +- **Real-time Synthesis**: The engine uses an additive synthesizer that generates audio in real-time from spectrograms (`.spec` files) via an Inverse Discrete Cosine Transform (IDCT). +- **Dynamic Updates**: Employs a thread-safe double-buffer mechanism to allow spectrogram data to be modified live for dynamic and evolving soundscapes. +- **Procedural Generation**: Includes a library for generating note spectrograms at runtime, complete with spectral filters for effects like noise and phasing. + +### Platform & Windowing +- **Stateless Refactor**: The entire platform layer (`platform.h`, `platform.cc`) is stateless. All window and input state is encapsulated in a `PlatformState` struct, which is passed to all platform functions. +- **High-DPI Aware**: The platform layer correctly queries framebuffer dimensions in pixels, resolving rendering issues on high-DPI (Retina) displays. +- **Cross-Platform Surface**: Uses `glfw3webgpu` to create a WebGPU-compatible surface on Windows, macOS, and Linux. + ### Procedural Textures - **TextureManager**: Handles CPU generation -> GPU upload. -- cgit v1.2.3