Replace material/primitive index with generic meta::T field (#9)

* glass and cleanup

* allow complex material lookup

* fix tests + tutorials

* remove display

* try to reduce docs size

* try to make plots smaller

* fix bvh rendering

Author: SimonDanisch

docs/Project.toml

@@ -16,7 +16,7 @@ WGLMakie = "276b4fcb-3e11-5398-bf8b-a0c2d153d008"
 
 [sources]
 BonitoBook = {url = "https://github.com/SimonDanisch/BonitoBook.jl"}
-Raycore = {path = "../"}
+Raycore = {path = ".."}
 
 [compat]
 Documenter = "1.5"

docs/src/bvh_hit_tests_content.md

@@ -91,7 +91,7 @@ end
 
 complex_bvh = Raycore.BVH(complex_spheres)
 # Test rays to find cases where any_hit differs from closest_hit
-test_rays = map(rand(Point2f, 200)) do p  
+test_rays = map(rand(Point2f, 20)) do p
     p = (p .* 14f0) .- 8f0
     Raycore.Ray(o=Point3f(p..., -5), d=Vec3f(0, 0, 1))
 end
@@ -175,4 +175,3 @@ This document demonstrated:
 6. `any_hit` is typically faster than `closest_hit` due to early termination
 
 All tests passed! ✓
-

docs/src/gpu_raytracing_tutorial.md

@@ -38,16 +38,7 @@ Let's use the exact same scene as the CPU tutorial - the Makie cat with room geo
 # Load and prepare the cat model
 include("raytracing-core.jl")
 bvh, ctx = example_scene()
-# We have a Makie extension for plotting the scene graph
-f, ax, pl = plot(bvh; axis=(; show_axis=false))
-f
-```
-```julia (editor=true, logging=false, output=true)
-cam = cameracontrols(ax.scene)
-cam.eyeposition[] = [0, 1.0, -4]
-cam.lookat[] = [0, 0, 2]
-cam.upvector[] = [0.0, 1, 0.0]
-cam.fov[] = 45.0
+md"**Scene loaded: $(length(bvh.primitives)) triangles, $(length(ctx.materials)) materials**"
 ```
 ## Part 2: GPU Kernel Version 1 - Basic Naive Approach
 

docs/src/raytracing-core.jl

@@ -47,33 +47,12 @@ function Raycore.to_gpu(Arr, ctx::RenderContext)
     return RenderContext(to_gpu(Arr, ctx.lights), to_gpu(Arr, ctx.materials), ctx.ambient)
 end
 
-function render_context(; glass_cat=false)
-    # Create lights and materials
-    lights = [
+function default_lights()
+    return [
         PointLight(Point3f(3, 4, -2), 50.0f0, RGB(1.0f0, 0.9f0, 0.8f0)),
         PointLight(Point3f(-3, 2, 0), 20.0f0, RGB(0.7f0, 0.8f0, 1.0f0)),
         PointLight(Point3f(0, 5, 5), 15.0f0, RGB(1.0f0, 1.0f0, 1.0f0))
     ]
-
-    # Material: base_color, metallic, roughness, ior, transmission
-    cat_material = if glass_cat
-        # Glass cat: clear glass with slight green tint, ior=1.5
-        Material(RGB(0.95f0, 1.0f0, 0.95f0), 0.0f0, 0.0f0, 1.5f0, 1.0f0)
-    else
-        # Original diffuse cat
-        Material(RGB(0.8f0, 0.6f0, 0.4f0), 0.0f0, 0.8f0, 1.0f0, 0.0f0)
-    end
-
-    materials = [
-        cat_material,                                                    # cat (index 1)
-        Material(RGB(0.3f0, 0.5f0, 0.3f0), 0.0f0, 0.9f0, 1.0f0, 0.0f0),  # floor - diffuse
-        Material(RGB(0.8f0, 0.6f0, 0.5f0), 0.8f0, 0.05f0, 1.0f0, 0.0f0), # back wall - metallic
-        Material(RGB(0.7f0, 0.7f0, 0.8f0), 0.0f0, 0.8f0, 1.0f0, 0.0f0),  # left wall - diffuse
-        Material(RGB(0.9f0, 0.9f0, 0.9f0), 0.8f0, 0.02f0, 1.0f0, 0.0f0), # sphere1 - metallic
-        Material(RGB(0.3f0, 0.6f0, 0.9f0), 0.5f0, 0.3f0, 1.0f0, 0.0f0),  # sphere2 - semi-metallic
-    ]
-
-    return RenderContext(lights, materials, 0.1f0)
 end
 
 function compute_light(
@@ -151,7 +130,7 @@ end
 function reflective_kernel(bvh, ctx, tri, dist, bary, ray, sky_color, shadow_samples=8)
     hit_point = ray.o + ray.d * dist
     normal = compute_normal(tri, bary)
-    mat = ctx.materials[tri.material_idx]
+    mat = ctx.materials[tri.metadata]
 
     # Direct lighting with soft shadows
     direct_color = compute_multi_light(bvh, ctx, hit_point, normal, mat, shadow_samples=shadow_samples)
@@ -174,7 +153,7 @@ function reflective_kernel(bvh, ctx, tri, dist, bary, ray, sky_color, shadow_sam
         reflection_color = if refl_hit
             refl_point = reflect_ray.o + reflect_ray.d * refl_dist
             refl_normal = compute_normal(refl_tri, refl_bary)
-            refl_mat = ctx.materials[refl_tri.material_idx]
+            refl_mat = ctx.materials[refl_tri.metadata]
             compute_multi_light(bvh, ctx, refl_point, refl_normal, refl_mat, shadow_samples=shadow_samples)
         else
             to_vec3f(sky_color)
@@ -211,9 +190,29 @@ function example_scene(; glass_cat=false)
     sphere1 = Tesselation(Sphere(Point3f(-2, -1.5 + 0.8, 2), 0.8f0), 64)
     sphere2 = Tesselation(Sphere(Point3f(2, -1.5 + 0.6, 1), 0.6f0), 64)
 
-    # Build our BVH acceleration structure
-    scene_geometry = [cat_mesh, floor, back_wall, left_wall, sphere1, sphere2]
-    return scene_geometry, render_context(glass_cat=glass_cat)
+    # Material: base_color, metallic, roughness, ior, transmission
+    cat_material = if glass_cat
+        Material(RGB(0.95f0, 1.0f0, 0.95f0), 0.0f0, 0.0f0, 1.5f0, 1.0f0)
+    else
+        Material(RGB(0.8f0, 0.6f0, 0.4f0), 0.0f0, 0.8f0, 1.0f0, 0.0f0)
+    end
+
+    # (geometry, material) pairs
+    scene = [
+        (cat_mesh,   cat_material),
+        (floor,      Material(RGB(0.3f0, 0.5f0, 0.3f0), 0.0f0, 0.9f0, 1.0f0, 0.0f0)),
+        (back_wall,  Material(RGB(0.8f0, 0.6f0, 0.5f0), 0.8f0, 0.05f0, 1.0f0, 0.0f0)),
+        (left_wall,  Material(RGB(0.7f0, 0.7f0, 0.8f0), 0.0f0, 0.8f0, 1.0f0, 0.0f0)),
+        (sphere1,    Material(RGB(0.9f0, 0.9f0, 0.9f0), 0.8f0, 0.02f0, 1.0f0, 0.0f0)),
+        (sphere2,    Material(RGB(0.3f0, 0.6f0, 0.9f0), 0.5f0, 0.3f0, 1.0f0, 0.0f0)),
+    ]
+
+    geometries = [g for (g, _) in scene]
+    materials = [m for (_, m) in scene]
+    bvh = Raycore.BVH(geometries, (mesh_idx, tri_idx) -> UInt32(mesh_idx))
+    lights = default_lights()
+    ctx = RenderContext(lights, materials, 0.1f0)
+    return bvh, ctx
 end
 
 function example_scene_glass_cat()

docs/src/raytracing_tutorial_content.md

@@ -50,18 +50,7 @@ sphere2 = Tesselation(Sphere(Point3f(2, -1.5 + 0.6, 1), 0.6f0), 64)
 # Build our BVH acceleration structure
 scene_geometry = [cat_mesh, floor, back_wall, left_wall, sphere1, sphere2]
 bvh = Raycore.BVH(scene_geometry)
-f, ax, pl = plot(bvh; axis=(; show_axis=false))
-```
-Set the camera to something better:
-
-```julia (editor=true, logging=false, output=true)
-cam = cameracontrols(ax.scene)
-cam.eyeposition[] = [0, 1.0, -4]
-cam.lookat[] = [0, 0, 2]
-cam.upvector[] = [0.0, 1, 0.0]
-cam.fov[] = 45.0
-update_cam!(ax.scene, cam)
-nothing
+md"**BVH built with $(length(bvh.primitives)) triangles**"
 ```
 ## Part 2: Helper Functions - Building Blocks
 
@@ -212,7 +201,11 @@ trace((args...)-> shadow_kernel(args...; shadow_samples=8), bvh, samples=8)
 
 ## Part 7: Materials and Multiple Lights
 
-Time to add color and multiple lights:
+Time to add color and multiple lights! To associate materials with geometry, we need to rebuild the BVH with **metadata** that links each triangle to its material.
+
+### Triangle Metadata
+
+When building a BVH, you can pass a `metadata_fn(mesh_idx, tri_idx)` that assigns custom data to each triangle. This metadata is stored in `triangle.metadata` and returned with every ray hit. For materials, we use the mesh index as metadata:
 
 ```julia (editor=true, logging=false, output=true)
 struct PointLight
@@ -233,25 +226,36 @@ struct RenderContext
     ambient::Float32
 end
 
-# Create lights and materials
+# Define materials for each mesh (order matches scene_geometry)
+materials = [
+    Material(RGB(0.8f0, 0.6f0, 0.4f0), 0.0f0, 0.8f0),  # 1: cat
+    Material(RGB(0.3f0, 0.5f0, 0.3f0), 0.0f0, 0.9f0),  # 2: floor
+    Material(RGB(0.8f0, 0.6f0, 0.5f0), 0.8f0, 0.05f0), # 3: back wall
+    Material(RGB(0.7f0, 0.7f0, 0.8f0), 0.0f0, 0.8f0),  # 4: left wall
+    Material(RGB(0.9f0, 0.9f0, 0.9f0), 0.8f0, 0.02f0), # 5: sphere1 - metallic
+    Material(RGB(0.3f0, 0.6f0, 0.9f0), 0.5f0, 0.3f0),  # 6: sphere2 - semi-metallic
+]
+
+# Rebuild BVH with material indices as metadata
+# The metadata_fn receives (mesh_idx, tri_idx) and returns data stored per-triangle
+bvh = Raycore.BVH(scene_geometry, (mesh_idx, tri_idx) -> UInt32(mesh_idx))
+
+# Create lights
 lights = [
     PointLight(Point3f(3, 4, -2), 50.0f0, RGB(1.0f0, 0.9f0, 0.8f0)),
     PointLight(Point3f(-3, 2, 0), 20.0f0, RGB(0.7f0, 0.8f0, 1.0f0)),
     PointLight(Point3f(0, 5, 5), 15.0f0, RGB(1.0f0, 1.0f0, 1.0f0))
 ]
 
-materials = [
-    Material(RGB(0.8f0, 0.6f0, 0.4f0), 0.0f0, 0.8f0),  # cat
-    Material(RGB(0.3f0, 0.5f0, 0.3f0), 0.0f0, 0.9f0),  # floor
-    Material(RGB(0.8f0, 0.6f0, 0.5f0), 0.8f0, 0.05f0),  # back wall
-    Material(RGB(0.7f0, 0.7f0, 0.8f0), 0.0f0, 0.8f0),  # left wall
-    Material(RGB(0.9f0, 0.9f0, 0.9f0), 0.8f0, 0.02f0),  # sphere1 - metallic
-    Material(RGB(0.3f0, 0.6f0, 0.9f0), 0.5f0, 0.3f0),  # sphere2 - semi-metallic
-]
-
 ctx = RenderContext(lights, materials, 0.1f0)
 nothing
 ```
+Now when a ray hits a triangle, we can look up its material using `triangle.metadata`:
+
+```julia
+mat = ctx.materials[triangle.metadata]  # Get material for hit triangle
+```
+
 ```julia (editor=true, logging=false, output=true)
 # Compute lighting from all lights - reusing our compute_light function!
 function compute_multi_light(bvh, ctx, point, normal, mat; shadow_samples=1)
@@ -269,7 +273,8 @@ end
 function material_kernel(bvh, ctx, tri, dist, bary, ray)
     hit_point = ray.o + ray.d * dist
     normal = compute_normal(tri, bary)
-    mat = ctx.materials[tri.material_idx]
+    # Look up material using triangle's metadata (mesh index we stored during BVH construction)
+    mat = ctx.materials[tri.metadata]
 
     color = compute_multi_light(bvh, ctx, hit_point, normal, mat, shadow_samples=2)
     return to_rgb(color)
@@ -287,7 +292,7 @@ Add simple reflections for metallic surfaces:
 function reflective_kernel(bvh, ctx, tri, dist, bary, ray, sky_color)
     hit_point = ray.o + ray.d * dist
     normal = compute_normal(tri, bary)
-    mat = ctx.materials[tri.material_idx]
+    mat = ctx.materials[tri.metadata]
 
     # Direct lighting with soft shadows
     direct_color = compute_multi_light(bvh, ctx, hit_point, normal, mat, shadow_samples=8)
@@ -310,7 +315,7 @@ function reflective_kernel(bvh, ctx, tri, dist, bary, ray, sky_color)
         reflection_color = if refl_hit
             refl_point = reflect_ray.o + reflect_ray.d * refl_dist
             refl_normal = compute_normal(refl_tri, refl_bary)
-            refl_mat = ctx.materials[refl_tri.material_idx]
+            refl_mat = ctx.materials[refl_tri.metadata]
             compute_multi_light(bvh, ctx, refl_point, refl_normal, refl_mat, shadow_samples=1)
         else
             to_vec3f(sky_color)
@@ -387,16 +392,30 @@ We built a complete ray tracer with:
 
 **Key Raycore Functions:**
 
-  * `Raycore.BVH(meshes)` - Build acceleration structure
+  * `Raycore.BVH(meshes)` - Build acceleration structure (default metadata = primitive index)
+  * `Raycore.BVH(meshes, metadata_fn)` - Build with custom per-triangle metadata
   * `Raycore.Ray(o=origin, d=direction)` - Create ray
-  * `Raycore.closest_hit(bvh, ray)` - Find nearest intersection
-  * `Raycore.any_hit(bvh, ray)` - Test for any intersection
+  * `Raycore.closest_hit(bvh, ray)` - Find nearest intersection, returns `(hit, triangle, distance, bary_coords)`
+  * `Raycore.any_hit(bvh, ray)` - Test for any intersection (fast shadow test)
   * `Raycore.reflect(wo, normal)` - Compute reflection direction
+  * `triangle.metadata` - Access custom data stored per-triangle
+
+**Key Patterns:**
+
+1. **Material Scene Pattern** - Associate materials with geometry using metadata:
+
+```julia
+# Build BVH with mesh index as metadata
+bvh = Raycore.BVH(meshes, (mesh_idx, tri_idx) -> UInt32(mesh_idx))
+
+# In your shader, look up material from hit triangle
+mat = materials[triangle.metadata]
+```
 
-**Key Pattern:** The `compute_light` function is reusable across the entire tutorial:
+2. **Reusable Lighting** - The `compute_light` function handles both hard and soft shadows:
 
   * `shadow_samples=1` → hard shadows
-  * `shadow_samples=4` → soft shadows
+  * `shadow_samples>1` → soft shadows
 
-This shows how a well-designed function can handle multiple use cases cleanly!
+This shows how well-designed functions can handle multiple use cases cleanly!
 

docs/src/test_wavefront.jl

@@ -14,8 +14,7 @@ using BenchmarkTools
 include("raytracing-core.jl")
 include("wavefront-renderer.jl")
 
-geom, ctx = example_scene()
-bvh = BVH(geom)
+bvh, ctx = example_scene()
 # ibvh = Raycore.InstancedBVH(geom)
 begin
     img = fill(RGBf(0, 0, 0), 400, 720)
@@ -28,13 +27,16 @@ renderer_instanced.framebuffer
 begin
     img = fill(RGBf(0, 0, 0), 400, 720)
     renderer_instanced = WavefrontRenderer(
-        img, ibvh, ctx;
+        img, bvh, ctx;
         camera_pos=Point3f(0, -0.9, -2.5),
         fov=45.0f0,
         sky_color=RGB{Float32}(0.5f0, 0.7f0, 1.0f0),
         samples_per_pixel=4
     )
     @btime render!(renderer_instanced)
+    # on windows + ryzen 395 max
+    # 381.034 ms (1200456 allocations: 90.13 MiB)
+
     nothing
 end
 using ImageShow
@@ -45,6 +47,7 @@ save("wavefront.png", map(col -> mapc(c -> clamp(c, 0f0, 1f0), col), renderer.fr
 using AMDGPU
 amd_renderer = to_gpu(ROCArray, renderer);
 Array(@btime render!(amd_renderer))
+# 36ms on windows + amd 8060s
 
 using pocl_jll, OpenCL
 amd_renderer = to_gpu(CLArray, renderer);

docs/src/viewfactors_content.md

@@ -6,22 +6,22 @@ This example demonstrates Raycore's analysis capabilities for radiosity and illu
 
 ```julia (editor=true, logging=false, output=true)
 using Raycore, GeometryBasics, LinearAlgebra
-using WGLMakie, FileIO
+using WGLMakie
 
-function LowSphere(radius, contact=Point3f(0); ntriangles=10)
+function LowSphere(radius, contact=Point3f(0); ntriangles=6)
     return Tesselation(Sphere(contact .+ Point3f(0, 0, radius), radius), ntriangles)
 end
 
-# Create scene with multiple objects
-ntriangles = 10
+# Create scene with multiple objects (using low triangle counts to keep docs small)
+ntriangles = 6
 s1 = LowSphere(0.5f0, Point3f(-0.5, 0.0, 0); ntriangles)
 s2 = LowSphere(0.3f0, Point3f(1, 0.5, 0); ntriangles)
 s3 = LowSphere(0.3f0, Point3f(-0.5, 1, 0); ntriangles)
 s4 = LowSphere(0.4f0, Point3f(0, 1.0, 0); ntriangles)
-cat = load(Makie.assetpath("cat.obj"))
+s5 = LowSphere(0.35f0, Point3f(0.5, 0.0, 0); ntriangles)
 
 # Build BVH acceleration structure
-bvh = BVH([s1, s2, s3, s4, cat])
+bvh = BVH([s1, s2, s3, s4, s5])
 world_mesh = GeometryBasics.Mesh(bvh)
 
 # Visualize the scene
@@ -35,7 +35,7 @@ View factors quantify how much each surface "sees" every other surface - essenti
 
 ```julia (editor=true, logging=false, output=true)
 # Calculate view factors between all faces
-viewf_matrix = view_factors(bvh, rays_per_triangle=1000)
+viewf_matrix = view_factors(bvh, rays_per_triangle=20)
 
 # Sum up total view factor per face
 viewfacts = map(i -> Float32(sum(view(viewf_matrix, :, i))), 1:length(bvh.primitives))
@@ -59,7 +59,7 @@ Calculate how much each face is exposed to rays from a specific viewing directio
 viewdir = normalize(ax.scene.camera.view_direction[])
 
 # Compute illumination
-illum = get_illumination(bvh, viewdir)
+illum = get_illumination(bvh, viewdir; grid_size=10)
 
 # Visualize
 pf = FaceView(illum, [GLTriangleFace(i) for i in 1:N])
@@ -75,7 +75,7 @@ Find the average position of visible surface points from a given direction.
 
 ```julia (editor=true, logging=false, output=true)
 # Calculate centroid
-hitpoints, centroid = get_centroid(bvh, viewdir)
+hitpoints, centroid = get_centroid(bvh, viewdir; grid_size=10)
 
 # Visualize
 f, ax, pl = mesh(world_mesh, color=(:blue, 0.5), transparency=true, axis=(show_axis=false,))
@@ -86,4 +86,3 @@ meshscatter!(ax, [centroid], color=:red, markersize=0.05)
 f
 ```
 The red sphere marks the centroid - useful for camera placement and focus calculations.
-