backwards compat and some small fixes

Author: SimonDanisch

docs/src/gpu_raytracing_tutorial.md

@@ -1,4 +1,4 @@
-# GPU Ray Tracing with Raycore
+# Ray Tracing on the GPU
 
 In this tutorial, we'll take the ray tracer from the previous tutorial and port it to the GPU using **KernelAbstractions.jl** and a GPU backend of choice (CUDA.jl, AMDGPU.jl, OpenCL.jl, OneApi.jl, or Metal.jl). We'll explore three different kernel implementations, each with different optimization strategies, and benchmark their performance against each other.
 
@@ -13,8 +13,7 @@ using WGLMakie
 using KernelAbstractions
 using BenchmarkTools
 ```
-
-To run things on the GPU with KernelAbstractions, you need to chose the correct package for your GPU and set the array type we use from there on.
+To run things on the GPU with KernelAbstractions, you need to choose the correct package for your GPU and set the array type we use from there on.
 
 ```julia (editor=true, logging=false, output=true)
 #using CUDA; GArray = CuArray; # For NVIDIA GPUS
@@ -28,8 +27,7 @@ GArray = Array # For the tutorial to run on CI we just use the CPU
 **Ready for GPU!** We have:
 
   * `Raycore` for fast ray-triangle intersections
-  * `KernelAbstractions` for portable GPU kernels
-  * `AMDGPU` for AMD GPU support
+  * `KernelAbstractions` for portable GPU kernels (works with CUDA, AMD, Metal, oneAPI, and OpenCL)
   * `BenchmarkTools` for performance comparison
 
 ## Part 1: Scene Setup (Same as CPU Tutorial)
@@ -46,12 +44,12 @@ f
 ```
 ```julia (editor=true, logging=false, output=true)
 cam = cameracontrols(ax.scene)
-cam.eyeposition[] = [0, 1.0, -5]
+cam.eyeposition[] = [0, 1.0, -4]
 cam.lookat[] = [0, 0, 2]
 cam.upvector[] = [0.0, 1, 0.0]
 cam.fov[] = 45.0
 ```
-## Part 5: GPU Kernel Version 1 - Basic Naive Approach
+## Part 2: GPU Kernel Version 1 - Basic Naive Approach
 
 The simplest GPU kernel - one thread per pixel:
 
@@ -70,7 +68,7 @@ import KernelAbstractions as KA
     x = ((idx - 1) % width) + 1
     y = ((idx - 1) ÷ width) + 1
     if x <= width && y <= height
-        # Generate camera ray and do a calculate a simple light model
+        # Generate camera ray and calculate a simple light model
         color = Vec3f(0)
         for i in 1:NSamples
             color = color .+ sample_light(bvh, ctx, width, height, camera_pos, focal_length, aspect, x, y, sky_color)
@@ -129,12 +127,12 @@ img_gpu = GArray(img);
 bvh_gpu = to_gpu(GArray, bvh);
 ctx_gpu = to_gpu(GArray, ctx);
 bench_kernel_v1 = @benchmark trace_gpu(raytrace_kernel_v1!, img_gpu, bvh_gpu, ctx_gpu)
-# bring back to GPU to display image
+# Bring back to CPU to display image
 Array(img_gpu)
 ```
 **First GPU render!** This is the simplest approach - one thread per pixel with no optimization.
 
-## Part 6: Optimized Kernel - Loop Unrolling
+## Part 3: Optimized Kernel - Loop Unrolling
 
 Loop overhead is significant on GPUs! Manually unrolling the sampling loop eliminates this overhead:
 
@@ -169,7 +167,7 @@ Array(img_gpu)
   * Better instruction-level parallelism
   * **1.39x faster than baseline!**
 
-## Part 7: Tiled Kernel with Optimized Tile Size
+## Part 4: Tiled Kernel with Optimized Tile Size
 
 The tile size dramatically affects performance. Let's use the optimal size discovered through benchmarking:
 
@@ -223,10 +221,9 @@ Array(img_gpu)
 ```
 **Tile size matters!** With `(32, 16)` tiles, this kernel is **1.22x faster** than baseline. With poor tile sizes like `(8, 8)`, it can be **2.5x slower**!
 
-## Part 8: Wavefront Path Tracing
+## Part 5: Wavefront Path Tracing
 
-The wavefront approach reorganizes ray tracing to minimize thread divergence by grouping similar work together. Instead of each thread handling an entire pixel's path, we separate the work into stages.
-Discussing the excat implementation is outside the scope of this tutorial, so we only include the finished renderer here:
+The wavefront approach reorganizes ray tracing to minimize thread divergence by grouping similar work together. Instead of each thread handling an entire pixel's path, we separate the work into stages. Discussing the exact implementation is outside the scope of this tutorial, so we only include the finished renderer here:
 
 ```julia (editor=true, logging=false, output=true)
 include("wavefront-renderer.jl")
@@ -254,7 +251,7 @@ Array(renderer_gpu.framebuffer)
   * Scales well with scene complexity
   * Enables advanced features like path tracing
 
-## Part 9: Comprehensive Performance Benchmarks
+## Part 6: Comprehensive Performance Benchmarks
 
 Now let's compare all kernels including the wavefront renderer:
 
@@ -277,6 +274,7 @@ DOM.img(src=Asset(data"gpu-benchmarks.png"), width="700px")
 ```
 ### Next Steps
 
-* Add **adaptive sampling** (more samples only where needed)
-* Explore **shared memory** optimizations for BVH traversal
-* Implement **streaming multisampling** across frames
+  * Add **adaptive sampling** (more samples only where needed)
+  * Explore **shared memory** optimizations for BVH traversal
+  * Implement **streaming multisampling** across frames
+

docs/src/index.md

@@ -27,11 +27,11 @@ Build a complete ray tracer from scratch with shadows, materials, reflections, a
 
 [Ray Tracing with Raycore](@ref)
 
-### Ray on the GPU Tutorial
+### GPU Ray Tracing Tutorial
 
-Take the previous ray tracer and run it on the GPU
+Port the ray tracer to the GPU with KernelAbstractions.jl. Learn about kernel optimization, loop unrolling, tiling, and wavefront rendering.
 
-![Ray Tracing](.gpu_raytracing_tutorial-bbook/data/gpu-benchmarks.png)
+![GPU Ray Tracing](.gpu_raytracing_tutorial-bbook/data/gpu-benchmarks.png)
 
 [GPU Ray Tracing with Raycore](@ref)
 

docs/src/raytracing_tutorial_content.md

@@ -1,7 +1,6 @@
 # Ray Tracing in one Hour
 
-Analougus to the famous [Ray Tracing in one Weekend](https://raytracing.github.io/), this tutorial uses Raycore to do the hard work of performant ray triangle intersection and therefore get a high performing ray tracer in a much shorter time.
-We'll start with the absolute basics and progressively add features until we have a ray tracer that produces beautiful images with shadows, materials, and reflections.
+Analougus to the famous [Ray Tracing in one Weekend](https://raytracing.github.io/), this tutorial uses Raycore to do the hard work of performant ray triangle intersection and therefore get a high performing ray tracer in a much shorter time. We'll start with the absolute basics and progressively add features until we have a ray tracer that produces beautiful images with shadows, materials, and reflections.
 
 ## Setup
 
@@ -49,9 +48,10 @@ 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)
-plot(bvh; axis=(; show_axis=false))
+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]
@@ -61,7 +61,6 @@ cam.fov[] = 45.0
 update_cam!(ax.scene, cam)
 nothing
 ```
-
 ## Part 2: Helper Functions - Building Blocks
 
 Let's define reusable helper functions we'll use throughout:
@@ -86,12 +85,9 @@ end
 to_vec3f(c::RGB) = Vec3f(c.r, c.g, c.b)
 to_rgb(v::Vec3f) = RGB{Float32}(v...)
 ```
-
 ## Part 3: The Simplest Ray Tracer - Depth Visualization
 
-We're using one main function to shoot rays for each pixel.
-For simplicity, we already added multisampling and simple multi threading, to enjoy smoother images and faster rendering times throughout the tutorial.
-Read the GPU tutorial how to further improve the performance of this simple, not yet optimal kernel.
+We're using one main function to shoot rays for each pixel. For simplicity, we already added multisampling and simple multi threading, to enjoy smoother images and faster rendering times throughout the tutorial. Read the GPU tutorial how to further improve the performance of this simple, not yet optimal kernel.
 
 ```julia (editor=true, logging=false, output=true)
 function trace(f, bvh; width=700, height=300,
@@ -130,7 +126,6 @@ depth_kernel(bvh, ctx, tri, dist, bary, ray) = RGB(1.0f0 - min(dist / 10.0f0, 1.
 ```julia (editor=true, logging=false, output=true)
 @time trace(depth_kernel, bvh, samples=16)
 ```
-
 **First render!** Depth visualization shows distance to surfaces. **Much faster with threading and smoother with multi-sampling!**
 
 ## Part 5: Lighting with Hard Shadows
@@ -202,7 +197,6 @@ end
 
 trace(shadow_kernel, bvh, samples=4)
 ```
-
 **Hard shadows working!** Scene has realistic lighting with sharp shadow edges.
 
 ## Part 6: Soft Shadows
@@ -351,8 +345,7 @@ end
 
 tone_mapping(img, a=0.38, y=1.0)
 ```
-For performance type stability is a must!
-We can use JET to test if a function is completely type stable, which we also test in the Raycore tests for all functions.
+For performance type stability is a must! We can use JET to test if a function is completely type stable, which we also test in the Raycore tests for all functions.
 
 ```julia (editor=true, logging=false, output=true)
 using JET
@@ -404,3 +397,4 @@ We built a complete ray tracer with:
   * `shadow_samples=4` → soft shadows
 
 This shows how a well-designed function can handle multiple use cases cleanly!
+

docs/src/wavefront-renderer.jl

@@ -619,7 +619,7 @@ function WavefrontRenderer(
 
     # Allocate work queues as SoA
     primary_ray_queue = similar_soa(img, PrimaryRayWork, num_rays)
-    primary_hit_queue = similar_soa(img, PrimaryHitWork{eltype(bvh.original_triangles)}, num_rays)
+    primary_hit_queue = similar_soa(img, PrimaryHitWork{eltype(bvh.primitives)}, num_rays)
     shadow_ray_queue = similar_soa(img, ShadowRayWork, num_shadow_rays)
     shadow_result_queue = similar_soa(img, ShadowResult, num_shadow_rays)
     reflection_ray_soa = similar_soa(img, ReflectionRayWork, num_rays)
@@ -758,7 +758,7 @@ function render!(renderer::WavefrontRenderer)
     refl_shade_kernel!(
         renderer.primary_hit_queue,
         renderer.reflection_hit_soa,
-        renderer.bvh.original_triangles,
+        renderer.bvh.primitives,
         renderer.ctx,
         renderer.sky_color,
         renderer.shading_queue,
@@ -805,7 +805,7 @@ function trace_wavefront_full(
 
     # Allocate work queues as SoA
     primary_ray_queue = similar_soa(img, PrimaryRayWork, num_rays)
-    primary_hit_queue = similar_soa(img, PrimaryHitWork{eltype(bvh.original_triangles)}, num_rays)
+    primary_hit_queue = similar_soa(img, PrimaryHitWork{eltype(bvh.primitives)}, num_rays)
     shadow_ray_queue = similar_soa(img, ShadowRayWork, num_shadow_rays)
     shadow_result_queue = similar_soa(img, ShadowResult, num_shadow_rays)
     reflection_ray_soa = similar_soa(img, ReflectionRayWork, num_rays)
@@ -848,7 +848,7 @@ function trace_wavefront_full(
 
     # Stage 8: Shade reflections and blend (using SoA)
     refl_shade_kernel! = shade_reflections_and_blend!(backend)
-    refl_shade_kernel!(primary_hit_queue, reflection_hit_soa, bvh.original_triangles, ctx, sky_color, shading_queue, ndrange=num_rays)
+    refl_shade_kernel!(primary_hit_queue, reflection_hit_soa, bvh.primitives, ctx, sky_color, shading_queue, ndrange=num_rays)
 
     # Stage 9: Accumulate final image
     accum_kernel! = accumulate_final!(backend)

ext/RaycoreMakieExt.jl

@@ -186,7 +186,7 @@ Helper function to draw BVH geometry
 function draw_bvh!(plot, bvh::Raycore.BVH, colors, alpha)
     # Group primitives by their material_idx
     primitive_groups = Dict{UInt32, Vector{Raycore.Triangle}}()
-    for prim in bvh.original_triangles
+    for prim in bvh.primitives
         mat_idx = prim.material_idx
         if !haskey(primitive_groups, mat_idx)
             primitive_groups[mat_idx] = Raycore.Triangle[]
@@ -236,7 +236,7 @@ function Makie.convert_arguments(::Type{Makie.Mesh}, bvh::Raycore.BVH)
     faces = GeometryBasics.TriangleFace{Int}[]
     colors = Float32[]
     normals = Vec3f[]
-    for (i, prim) in enumerate(bvh.original_triangles)
+    for (i, prim) in enumerate(bvh.primitives)
         start_idx = length(vertices)
         for (v, n) in zip(prim.vertices, prim.normals)
             push!(vertices, v)

raycore-blogpost.md

@@ -0,0 +1,134 @@
+# Announcing Raycore.jl: High-Performance Ray Tracing for CPU and GPU
+
+I'm excited to announce **Raycore.jl**, a high-performance ray-triangle intersection engine with BVH acceleration, designed for both CPU and GPU execution in Julia. Whether you're building a physically-based renderer, simulating light transport, or exploring acoustic propagation, Raycore provides the performance and flexibility you need.
+
+## Why Write a New Ray Intersection Engine?
+
+You might wonder: why build yet another ray tracer? The answer lies in Julia's unique strengths and the opportunities they create.
+
+### Advantages of Julia
+
+* **High-level language with performance close to C/C++** - Write readable code that runs fast
+* **Great GPU support** - Single codebase runs on CUDA, AMD, Metal, oneAPI, and OpenCL via KernelAbstractions.jl
+* **Multiple dispatch for different geometries, algorithms, and materials** - Extend the system cleanly without modifying core code
+* **Pluggable architecture for new features** - Add custom materials, sampling strategies, or acceleration structures
+* **One of the best languages to write out math** - The code looks like the equations you'd write on paper
+
+### Honest Assessment: The Tradeoffs
+
+Julia isn't perfect, and I want to be upfront about the challenges:
+
+* **Long compile times for first use** - The first run of a function triggers JIT compilation
+* **GPU code still has some rough edges** - Complex kernels require careful attention to avoid allocations and GPU-unfriendly constructs
+
+In practice, compile times aren't as bad as they might sound. You keep a Julia session running and only pay the compilation cost once. There's also ongoing work on precompilation that could reduce these times to near-zero in the future. For GPU code, better tooling for detecting and fixing issues is on the horizon, along with improved error messages when problematic LLVM code is generated.
+
+### The Big Picture
+
+The flexibility to write a high-performance ray tracer in a high-level language opens up exciting possibilities:
+
+* **Use automatic differentiation** to optimize scene parameters or light placement
+* **Plug in new optimizations seamlessly** without fighting a type system or rewriting core algorithms
+* **Democratize working on high-performance ray tracing** - contributions don't require C++ expertise
+* **Rapid experimentation** - test new ideas without lengthy compile cycles
+
+## What is Raycore.jl?
+
+Raycore is a focused library that does one thing well: fast ray-triangle intersections with BVH acceleration. It provides the building blocks for ray tracing applications without imposing a particular rendering architecture.
+
+**Core Features:**
+- Fast BVH construction and traversal
+- CPU and GPU support via KernelAbstractions.jl
+- Analysis tools: centroid calculation, illumination analysis, view factors for radiosity
+- Makie integration for visualization
+
+**Performance:** On GPU, we've achieved significant speedups through kernel optimizations including loop unrolling, tiling, and wavefront rendering approaches that minimize thread divergence.
+
+## Interactive Tutorials
+
+The documentation includes several hands-on tutorials that build from basics to advanced GPU optimization:
+
+### 1. BVH Hit Tests & Basics
+
+Learn the fundamentals of ray-triangle intersection, BVH construction, and visualization.
+
+![BVH Basics](docs/src/basics.png)
+
+[Try the tutorial →](https://docs.raycore.jl)
+
+### 2. Ray Tracing Tutorial
+
+Build a complete ray tracer from scratch with shadows, materials, reflections, and tone mapping.
+
+![Ray Tracing](docs/src/raytracing.png)
+
+[Try the tutorial →](https://docs.raycore.jl)
+
+### 3. Ray Tracing on the GPU
+
+Port the ray tracer to GPU and learn optimization techniques: loop unrolling, tiling, and wavefront rendering. Includes comprehensive benchmarks comparing different approaches.
+
+![GPU Benchmarks](docs/src/.gpu_raytracing_tutorial-bbook/data/gpu-benchmarks.png)
+
+[Try the tutorial →](https://docs.raycore.jl)
+
+### 4. View Factors & Analysis
+
+Calculate view factors, illumination, and centroids for radiosity and thermal analysis applications.
+
+![View Factors](docs/src/viewfactors.png)
+
+[Try the tutorial →](https://docs.raycore.jl)
+
+## What Can It Be Used For?
+
+Ray tracing isn't just for rendering pretty pictures. Raycore enables a wide range of physics and engineering applications:
+
+* **Physically-based rendering** - Photorealistic image synthesis with accurate light transport
+* **Light transport simulations** - Analyze lighting design, daylighting, and energy efficiency
+* **Acoustic simulations** - Model sound propagation in architectural spaces
+* **Neutron transport simulations** - Nuclear reactor analysis and radiation shielding
+* **Thermal radiosity** - Heat transfer analysis in complex geometries
+* **Any application that needs ray tracing** - The core is general-purpose
+
+A high-performance implementation of CPU and GPU ray tracing in Julia can be a huge enabler for research and development in these fields, especially considering how easy it is to jump into the code and make changes dynamically. Need to add a new material model? Write a few methods. Want to try a different BVH construction algorithm? Implement the interface. The barrier to experimentation is low.
+
+## Getting Started
+
+Install Raycore.jl from the Julia package manager:
+
+```julia
+using Pkg
+Pkg.add("Raycore")
+```
+
+Then check out the [interactive tutorials](https://docs.raycore.jl) to start building your first ray tracer!
+
+## Future Work
+
+While Raycore is production-ready for many applications, there are exciting directions for future development:
+
+* **Advanced acceleration structures** - Explore alternatives to BVH like kd-trees or octrees for specific use cases
+* **Importance sampling** - Better Monte Carlo integration strategies for path tracing
+* **Spectral rendering** - Move beyond RGB to full spectral wavelengths
+* **Bi-directional path tracing** - Handle difficult lighting scenarios more efficiently
+* **GPU memory optimizations** - Reduce memory footprint for larger scenes
+* **Improved precompilation** - Further reduce first-run latency
+* **Domain-specific extensions** - Purpose-built tools for acoustic, thermal, or neutron transport
+
+Contributions are welcome! The codebase is designed to be approachable, and the Julia community is friendly and helpful.
+
+## Acknowledgments
+
+This project builds on the excellent work of the Julia GPU ecosystem, particularly KernelAbstractions.jl for portable GPU programming, and the Julia visualization stack including Makie.jl for the interactive tutorials.
+
+Special thanks to everyone who provided feedback during development and helped shape Raycore into what it is today.
+
+---
+
+**Links:**
+- [Documentation & Tutorials](https://docs.raycore.jl)
+- [GitHub Repository](https://github.com/yourusername/Raycore.jl)
+- [Julia Discourse](https://discourse.julialang.org)
+
+I'm excited to see what you build with Raycore.jl. Happy ray tracing!