Skip to main content

rayengine_core/
spatial.rs

1//! Display-independent selection, proximity, and conservative camera visibility.
2//!
3//! [`SpatialIndex2D`] and [`SpatialIndex3D`] own snapshots of caller-supplied
4//! IDs and boxes. Rebuild after world bounds change; no ECS or raylib state is
5//! read implicitly. Queries borrow the snapshot and never allocate when using
6//! visitor methods. A failed rebuild leaves the previous snapshot intact.
7
8mod index;
9mod ray;
10mod visibility;
11
12pub use index::{SpatialHit2, SpatialHit3, SpatialIndex2D, SpatialIndex3D};
13pub use ray::{Ray2, Ray3, RayHit2, RayHit3};
14pub use visibility::{Frustum2D, Frustum3D};
15
16use std::fmt;
17
18/// Invalid, nonfinite, or unsupported spatial input.
19#[derive(Clone, Copy, Debug, PartialEq, Eq)]
20pub enum SpatialError {
21    /// Ray origin/direction is nonfinite or direction has no usable length.
22    InvalidRay,
23    /// A maximum query distance must be nonnegative and not NaN.
24    InvalidDistance,
25    /// One box has nonfinite coordinates or a reversed axis.
26    InvalidBounds(usize),
27    /// Camera, clipping distances, or viewport geometry is invalid.
28    InvalidCamera,
29}
30
31impl fmt::Display for SpatialError {
32    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
33        match self {
34            Self::InvalidRay => write!(f, "ray origin/direction is invalid"),
35            Self::InvalidDistance => write!(f, "query distance must be nonnegative and not NaN"),
36            Self::InvalidBounds(index) => write!(f, "invalid spatial bounds at input {index}"),
37            Self::InvalidCamera => write!(f, "camera or clipping geometry is invalid"),
38        }
39    }
40}
41
42impl std::error::Error for SpatialError {}
43
44pub(crate) fn valid_distance(distance: f32) -> Result<(), SpatialError> {
45    if distance >= 0.0 {
46        Ok(())
47    } else {
48        Err(SpatialError::InvalidDistance)
49    }
50}
51
52#[cfg(test)]
53mod tests;