RayTracer/MetalImplementationPlan.md

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.