Completed Metal implementation

MetalImplementationPlan.md

@@ -0,0 +1,38 @@
+# Metal Implementation Plan
+
+This document outlines the steps required to complete the Metal-based GPU ray tracer, transitioning from the current scaffolding to a fully functional renderer.
+
+## 1. Material System Integration
+The most critical gap is the lack of material data on the GPU.
+*   **Data Synchronization**: Ensure `struct MaterialParameter` in `res/shaders/Common.slang` matches the C++ memory layout for `Material`.
+*   **Buffer Implementation**: Complete `MetalScene::createRayTracingHierarchy` to:
+    *   Allocate and populate `materialsBuffer`.
+    *   Map each model in `modelRefsBuffer` to a specific material index.
+*   **Shader Retrieval**: In `ClosestHit.slang`, implement the lookup: `MaterialParameter mat = pParams.materialData[m.materialIndex];`.
+
+## 2. Shader Completion
+The Slang shaders currently contain placeholders and incomplete lighting logic.
+*   **`Miss.slang`**: Implement a miss shader that returns a default environment color (e.g., a dark navy or simple sky gradient) to prevent black backgrounds on missed rays.
+*   **`ClosestHit.slang`**:
+    *   Replace `// TOOD:` with actual material attribute fetching.
+    *   Refine the BRDF application: connect the fetched albedo, specular, and emissive values to the lighting loops (Directional/Point lights).
+    *   Fix indirect illumination recursion: ensure the payload correctly accumulates light across multiple bounces without exponential energy gain/loss.
+*   **`RayGen.slang`**: Verify that the `radianceAccumulator` handles sample averaging correctly to support progressive rendering and anti-aliasing.
+
+## 3. Resource & Buffer Management
+Ensure all data flows from the CPU scene description to the Metal compute pipeline.
+*   **Parameter Blocks**: Fully utilize `ParameterBlock<RaytracingParams>` for all global scene data (lights, camera, acceleration structure) to minimize binding overhead.
+*   **Texture Support**: 
+    *   Implement a mechanism in `MetalScene` to upload textures to `id<MTLTexture>`.
+    *   Expand `RaytracingParams` to include access to these textures within the shaders for albedo/normal mapping.
+
+## 4. Performance & Robustness
+*   **Acceleration Structure**: The current compaction logic is good; ensure it is called whenever geometry changes.
+*   **Memory Safety**: Add validation for buffer sizes and alignment, especially when bridging C++ `glm` types to Slang/Metal types.
+*   **Debugging**: Enable Metal API validation during development to catch illegal memory access or incorrect resource usage in the compute kernel.
+
+## 5. Milestones
+1.  **Milestone 1: Basic Geometry**: Render unlit, solid-colored geometry using `ClosestHit` and a basic `Miss` shader.
+2.  **Milestone 2: Basic Lighting**: Implement diffuse shading with a single directional light.
+3.  **Milestone 3: Full Material System**: Integrate textures and multiple material types.
+4.  **Milestone 4: Global Illumination**: Complete recursive bounce logic for indirect lighting.