From d3a609fad91744c45f6bc59b625a26f8870e271d Mon Sep 17 00:00:00 2001 From: skal Date: Sun, 8 Feb 2026 21:28:40 +0100 Subject: docs: Archive historical documentation (26 files → doc/archive/) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moved completed/historical docs to doc/archive/ for cleaner context: Archived (26 files): - Analysis docs: variable tempo, audio architecture, build optimization - Handoff docs: 6 agent handoff documents - Debug reports: shadows, peak meter, timing fixes - Task summaries and planning docs Kept (16 files): - Essential: AI_RULES, HOWTO, CONTRIBUTING, CONTEXT_MAINTENANCE - Active subsystems: 3D, ASSET_SYSTEM, TRACKER, SEQUENCE - Current work: MASKING_SYSTEM, SPECTRAL_BRUSH_EDITOR Updated COMPLETED.md with archive index for easy reference. --- doc/archive/DEBUG_SHADOWS.md | 50 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 doc/archive/DEBUG_SHADOWS.md (limited to 'doc/archive/DEBUG_SHADOWS.md') diff --git a/doc/archive/DEBUG_SHADOWS.md b/doc/archive/DEBUG_SHADOWS.md new file mode 100644 index 0000000..bcf6d3e --- /dev/null +++ b/doc/archive/DEBUG_SHADOWS.md @@ -0,0 +1,50 @@ +# Shadow Rendering Analysis + +## Issue +In `test_mesh` (and the engine generally), shadows cast by `ObjectType::MESH` objects onto the floor (or other objects) appear as simple bounding boxes, not matching the mesh geometry. + +## Root Cause +The engine uses **Hybrid Rendering**: +1. **Visibility**: Meshes are rasterized using the GPU graphics pipeline (`mesh_render.wgsl`). +2. **Shadows**: Shadows are calculated using **SDF Raymarching** in the fragment shader (`calc_shadow` in `shadows.wgsl`). + +To calculate shadows, the shader needs to query the distance to every object in the scene (`map_scene`). +For SDF primitives (Sphere, Box, Torus), we have exact mathematical distance functions. +For arbitrary Meshes, calculating the exact Signed Distance Field (SDF) in the shader is computationally expensive and complex (requires BVH in shader or 3D texture). + +Current implementation in `assets/final/shaders/render/scene_query.wgsl`: +```wgsl +fn get_dist(p: vec3, obj_params: vec4) -> f32 { + // ... + if (obj_type == 5.0) { return sdBox(p, obj_params.yzw); } // MESH AABB + return 100.0; +} +``` +`obj_params.yzw` contains the local extents (half-size) of the mesh's AABB. +Thus, **all meshes are approximated as Boxes in the shadow/SDF pass.** + +## Implications +- **Shadow Casting**: Meshes cast box-shaped shadows. +- **Shadow Receiving**: Meshes receive shadows correctly (from other objects' SDFs). +- **Self-Shadowing**: Disabled via `skip_idx` to prevent the mesh from being shadowed by its own proxy box. + +## Potential Solutions + +### 1. Shadow Mapping (Recommended for future) +Render the scene depth from the light's perspective into a texture. +- **Pros**: Exact shadows for rasterized geometry; handles self-shadowing naturally. +- **Cons**: Requires additional render pass, potential bias artifacts, doesn't integrate perfectly with soft SDF shadows (though can be combined). +- **Status**: Tracked as **Task #40**. + +### 2. Mesh SDF Baking +Pre-calculate a 3D texture containing the SDF of the mesh and sample it in the shader. +- **Pros**: Accurate soft shadows, integrates with existing SDF system. +- **Cons**: High memory usage (3D textures), requires tooling to bake SDFs (e.g. `mesh_to_sdf` tool). + +### 3. Analytic Proxies +Manually assign a better proxy shape (e.g. combination of spheres/boxes) for specific meshes. +- **Pros**: Cheap, better than box. +- **Cons**: Manual labor, limited fidelity. + +## Conclusion +The current "bounding box shadow" behavior is a known limitation of using an AABB as the SDF proxy for meshes. It is not a bug in the code, but a simplified implementation choice for the 64k intro constraints. Accurate shadows require implementing Shadow Mapping (Task #40). -- cgit v1.2.3