Raycore.jl

BVH{NodeVec, TriVec, OrigTriVec}

GPU-optimized BVH acceleration structure.

Key optimizations:

• Uses LinearBVH node structure (flat array, depth-first layout)
• Pre-transforms triangles with edge vectors for Möller-Trumbore
• Designed for efficient GPU kernel traversal

Fields:

• nodes: LinearBVH nodes (flat array, depth-first layout)
• triangles: Pre-transformed compact triangles
• primitives: Original triangles (for normals, UVs, materials)
• maxnodeprimitives: Maximum primitives per leaf node

BVH(primitives::AbstractVector, max_node_primitives::Integer=1)

Construct a BVH acceleration structure from a list of primitives (meshes or geometries).

Arguments:

• primitives: Vector of triangle meshes or GeometryBasics geometries
• max_node_primitives: Maximum number of primitives per leaf node (default: 1)

Returns a GPU-optimized BVH with pre-transformed triangles for efficient ray tracing.

RayIntersectionSession{F}

Represents a ray tracing session containing rays, a BVH structure, a hit function, and the computed intersection results.

Fields

• rays::Vector{<:AbstractRay}: Array of rays to trace
• bvh::BVH: BVH acceleration structure to intersect against
• hit_function::F: Function to use for intersection testing (e.g., closest_hit or any_hit)
• hits::Vector{Tuple{Bool, Triangle, Float32, Point3f}}: Results of hit_function applied to each ray

Example

using Raycore, GeometryBasics

# Create BVH from geometry
sphere = Tesselation(Sphere(Point3f(0, 0, 1), 1.0f0), 20)
bvh = Raycore.BVH([sphere])

# Create rays
rays = [
    Raycore.Ray(Point3f(0, 0, -5), Vec3f(0, 0, 1)),
    Raycore.Ray(Point3f(1, 0, -5), Vec3f(0, 0, 1)),
]

# Create session
session = RayIntersectionSession(rays, bvh, Raycore.closest_hit)

# Access results
for (i, hit) in enumerate(session.hits)
    hit_found, primitive, distance, bary_coords = hit
    if hit_found
        println("Ray $i hit at distance $distance")
    end
end

any_hit(bvh::BVH, ray::AbstractRay)

Test if a ray intersects any primitive in the GPU BVH (for occlusion testing). Stops at the first intersection found.

Returns:

• hit_found: Boolean indicating if any intersection was found
• hit_primitive: The primitive that was hit (if any)
• distance: Distance along the ray to the hit point (hit_point = ray.o + ray.d * distance)
• barycentric_coords: Barycentric coordinates of the hit point

closest_hit(bvh::BVH, ray::AbstractRay)

Find the closest intersection between a ray and the GPU BVH. Uses manual traversal with compact triangle intersection for best performance.

Returns:

• hit_found: Boolean indicating if an intersection was found
• hit_primitive: The primitive that was hit (if any)
• distance: Distance along the ray to the hit point (hit_point = ray.o + ray.d * distance)
• barycentric_coords: Barycentric coordinates of the hit point

hit_count(session::RayIntersectionSession)

Count the number of rays that hit geometry in the session.

hit_distances(session::RayIntersectionSession)

Extract all hit distances from a RayIntersectionSession.

Returns a vector of Float32 containing distances for all rays that intersected geometry.

hit_points(session::RayIntersectionSession)

Extract all valid hit points from a RayIntersectionSession.

Returns a vector of Point3f containing the world-space hit points for all rays that intersected geometry.

miss_count(session::RayIntersectionSession)

Count the number of rays that missed all geometry in the session.

Reflect wo about n.

CompactTriangle

Pre-transformed triangle data for efficient GPU ray-triangle intersection. Uses edge vectors for Möller-Trumbore intersection algorithm.

Fields:

• v0: First vertex position (4th component for alignment)
• edge1: v1 - v0 edge vector
• edge2: v2 - v0 edge vector
• normal: Face normal (4th component for alignment)
• indices: [materialidx, primitiveidx] for shading

The shading coordinate system gives a frame for expressing directions in spherical coordinates (θ, ϕ). The angle θ is measured from the given direction to the z-axis and ϕ is the angle formed with the x-axis after projection of the direction onto xy-plane.

Since normal is (0, 0, 1) → cos_θ = n · w = (0, 0, 1) ⋅ w = w.z.

Flip normal n so that it lies in the same hemisphere as v.

generate_ray_grid(bvh::BVH, ray_direction::Vec3f, grid_size::Int)

Generate a grid of ray origins based on the BVH bounding box and a given ray direction.

intersect_compact_triangle(tri::CompactTriangle, ray_o, ray_d, t_max)

Watertight Möller-Trumbore ray-triangle intersection for GPU. Uses pre-computed edge vectors for efficiency.

Returns: (hit, t, u, v) where u,v are barycentric coordinates

dirisnegative: 1 – false, 2 – true

Return index of the longest axis. Useful for deciding which axis to subdivide, when building ray-tracing acceleration structures.

1 - x, 2 - y, 3 - z.

Get offset of a point from the minimum point of the bounds.

to_compact_triangle(tri::Triangle) -> CompactTriangle

Convert a Triangle to CompactTriangle format with pre-computed edge vectors.