From d74c6dae8614d49c6db958291312c772bf8492c2 Mon Sep 17 00:00:00 2001 From: skal Date: Sun, 8 Feb 2026 07:27:18 +0100 Subject: docs: Document mesh shadow limitation (Task A.1 investigation) --- doc/DEBUG_SHADOWS.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 doc/DEBUG_SHADOWS.md (limited to 'doc/DEBUG_SHADOWS.md') diff --git a/doc/DEBUG_SHADOWS.md b/doc/DEBUG_SHADOWS.md new file mode 100644 index 0000000..bcf6d3e --- /dev/null +++ b/doc/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