pub struct RayTraceScene { /* private fields */ }Expand description
An owned ray-tracing scene with a precomputed bounding volume hierarchy and shadow data.
RayTraceScene bundles the occluder list, the flat BVH over their
bounds, and the (center, radius) shadow bounding spheres consumed by
soft_shadow_factor, computing both exactly once at construction.
Tracing through RayTraceScene::trace and querying through
RayTraceScene::closest_hit perform no heap allocation per ray or
per bounce, making the scene the single canonical entry point for
tracing many rays against a static scene.
Implementations§
Source§impl RayTraceScene
Implements the GPU packing entry point for RayTraceScene.
impl RayTraceScene
Implements the GPU packing entry point for RayTraceScene.
Sourcepub fn encode_gpu(&self) -> Result<Vec<f32>, String>
pub fn encode_gpu(&self) -> Result<Vec<f32>, String>
Packs the scene into the vec4 array both shader backends read.
The layout is frozen by the shader contract:
vec4[0]: node_count, primitive_count, primitive_offset, 0
vec4[1 + 3 * n]: node lower.xyz, start
vec4[2 + 3 * n]: node upper.xyz, count
vec4[3 + 3 * n]: node escape, 0, 0, 0
vec4[primitive_offset + 8 * p]: primitive recordsPrimitives are stored in indices order so a leaf’s start field
reads directly into the packed primitive array while each record
still carries the original primitive index the closest-hit tie
breaker compares. The source occluder ordering is never altered.
An empty scene packs a two-slot header with node_count == 0, which
both shaders detect and treat as “every ray misses”.
Non-finite geometry components, components whose magnitude exceeds
the finite f32 range, and indices above 2^24 (the exact-integer
limit of f32) are rejected rather than truncated, because a
truncated node bound would round inward and lose real geometry.
§Returns
Result<Vec<f32>, String>- The packedvec4array, or the reason the scene cannot be represented on a GPU.
Source§impl RayTraceScene
Implements the constructor and zero-allocation tracing entry points for
RayTraceScene.
impl RayTraceScene
Implements the constructor and zero-allocation tracing entry points for
RayTraceScene.
Sourcepub fn new(occluders: Vec<Occluder>) -> RayTraceScene
pub fn new(occluders: Vec<Occluder>) -> RayTraceScene
Creates a new scene taking ownership of occluders and precomputing
both the bounding volume hierarchy and the (center, radius) shadow
bounding spheres used by soft_shadow_factor.
The hierarchy is built once here; every later query reuses it, so the cost of the BVH never appears in a per-ray measurement. The public surface is unchanged from the pre-BVH constructor, which takes the occluder list by value.
§Arguments
Vec<Occluder>- All occluding surfaces in the scene.
§Returns
RayTraceScene- The new scene with precomputed shadow data.
Sourcepub fn trace(&self, ray: Ray, lights: &LightingUniforms) -> Vector3D
pub fn trace(&self, ray: Ray, lights: &LightingUniforms) -> Vector3D
Iteratively traces a ray through the scene and returns the final
shaded color, using the [RAYTRACE_DEFAULT_MAX_BOUNCES] constant as
the bounce limit.
Performs no heap allocation per ray or per bounce: the shadow
bounding spheres precomputed at construction are reused, and no
Material is cloned. Use RayTraceScene::trace_with_bounces to
override the bounce limit.
§Arguments
Ray- The ray to trace.&LightingUniforms- Lighting parameters used during shading.
§Returns
Vector3D- The final traced color.
Sourcepub fn trace_with_bounces(
&self,
ray: Ray,
lights: &LightingUniforms,
max_bounces: u32,
) -> Vector3D
pub fn trace_with_bounces( &self, ray: Ray, lights: &LightingUniforms, max_bounces: u32, ) -> Vector3D
Iteratively traces a ray through the scene with an explicit bounce limit and returns the final shaded color.
On a miss the ambient color scaled by the accumulated specular
throughput is added. On a hit the surface material is evaluated with
LightingUniforms::shade and, when the hit material has a
non-zero specular component, the trace continues with a reflected
ray up to max_bounces times (incrementing the ray’s depth field
per bounce).
§Arguments
Ray- The ray to trace.&LightingUniforms- Lighting parameters used during shading.u32- The maximum number of bounces allowed for this ray.
§Returns
Vector3D- The final traced color.
Sourcepub fn closest_hit(&self, ray: &Ray) -> Option<Hit>
pub fn closest_hit(&self, ray: &Ray) -> Option<Hit>
Finds the closest intersection between a ray and the scene occluders.
The winning occluder’s Material is cloned exactly once, when the
returned Hit is constructed; losing candidates are never cloned.
Traversal itself resolves every candidate through the scene’s
bounding volume hierarchy, so the cost scales with the parts of the
hierarchy the ray actually crosses rather than with the occluder
count.
§Arguments
&Ray- The ray to test.
§Returns
Option<Hit>- The closest hit, orNoneif the ray misses.
Sourcepub fn occluded(&self, ray: &Ray) -> bool
pub fn occluded(&self, ray: &Ray) -> bool
Reports whether anything in the scene blocks the ray’s parameter range.
This is the any-hit counterpart to RayTraceScene::closest_hit,
built for shadow segments: it stops at the first blocker instead of
resolving the whole hierarchy, so a fully occluded light costs less
than a fully visible one. An empty scene reports false, and a ray
with an inverted or non-finite range reports false rather than
inventing a hit.
§Arguments
&Ray- The ray to test.
§Returns
bool-truewhen at least one occluder intersects the range.