# 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.