parry3d 0.31.1

3 dimensional collision detection library in Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

use crate::shape::SubShapeId;

/// Whether two shapes intersect, and the sub-shapes that do.
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub struct ShapeIntersection {
    /// Whether the two shapes intersect.
    pub intersecting: bool,
    /// The sub-shape of the first shape that intersects.
    ///
    /// Always `0` for a shape with no sub-shapes, and meaningless unless `intersecting` is `true`.
    pub subshape1: SubShapeId,
    /// The sub-shape of the second shape that intersects.
    ///
    /// Always `0` for a shape with no sub-shapes, and meaningless unless `intersecting` is `true`.
    pub subshape2: SubShapeId,
}

impl ShapeIntersection {
    /// A result between shapes with no sub-shapes to distinguish.
    pub fn new(intersecting: bool) -> Self {
        Self {
            intersecting,
            subshape1: 0,
            subshape2: 0,
        }
    }

    /// Sets the sub-shapes that intersect.
    pub fn with_subshapes(mut self, subshape1: SubShapeId, subshape2: SubShapeId) -> Self {
        self.subshape1 = subshape1;
        self.subshape2 = subshape2;
        self
    }

    /// Swaps the roles of the two shapes.
    pub fn swapped(mut self) -> Self {
        core::mem::swap(&mut self.subshape1, &mut self.subshape2);
        self
    }
}

impl From<bool> for ShapeIntersection {
    fn from(intersecting: bool) -> Self {
        Self::new(intersecting)
    }
}

use crate::math::Pose;
use crate::query::{DefaultQueryDispatcher, QueryDispatcher, Unsupported};
use crate::shape::Shape;

/// Tests whether two shapes are intersecting (overlapping).
///
/// This is the fastest collision query, returning only a boolean result without
/// computing contact points, normals, or penetration depth. Use this when you only
/// need to know **if** shapes collide, not **where** or **how much**.
///
/// # Behavior
///
/// Returns `true` if:
/// - Shapes are **touching** (surfaces just make contact)
/// - Shapes are **penetrating** (overlapping with any amount)
///
/// Returns `false` if:
/// - Shapes are **separated** (any distance apart, even very close)
///
/// # Performance
///
/// This is the fastest collision detection query:
/// - **Ball-Ball**: Extremely fast (just distance check)
/// - **AABB-AABB**: Very fast (6 comparisons in 3D)
/// - **Convex-Convex**: Fast (early-exit GJK algorithm)
/// - **Concave shapes**: Uses BVH for acceleration
///
/// Significantly faster than `contact()` or `distance()` because it can
/// terminate early once any intersection is found.
///
/// # Arguments
///
/// * `pos1` - Position and orientation of the first shape
/// * `g1` - The first shape
/// * `pos2` - Position and orientation of the second shape
/// * `g2` - The second shape
///
/// # Returns
///
/// * `Ok(true)` - Shapes are intersecting
/// * `Ok(false)` - Shapes are not intersecting
/// * `Err(Unsupported)` - This shape pair combination is not supported
///
/// # Example
///
/// ```rust
/// # #[cfg(all(feature = "dim3", feature = "f32"))] {
/// use parry3d::query::intersection_test;
/// use parry3d::shape::Ball;
/// use parry3d::math::Pose;
///
/// let ball1 = Ball::new(1.0);
/// let ball2 = Ball::new(1.0);
///
/// // Overlapping balls
/// let pos1 = Pose::translation(0.0, 0.0, 0.0);
/// let pos2 = Pose::translation(1.5, 0.0, 0.0);
///
/// let intersecting = intersection_test(&pos1, &ball1, &pos2, &ball2).unwrap().intersecting;
/// assert!(intersecting); // Distance 1.5 < combined radii 2.0
///
/// // Separated balls
/// let pos3 = Pose::translation(5.0, 0.0, 0.0);
/// let not_intersecting = intersection_test(&pos1, &ball1, &pos3, &ball2).unwrap().intersecting;
/// assert!(!not_intersecting); // Distance 5.0 > combined radii 2.0
/// # }
/// ```
///
/// # Use Cases
///
/// - **Trigger volumes**: Detect when player enters an area
/// - **Broad-phase**: Quickly filter out distant object pairs
/// - **Game logic**: Simple overlap detection (pickup items, damage zones)
/// - **Optimization**: Pre-check before expensive narrow-phase queries
///
/// # When to Use Other Queries
///
/// - Need contact points/normal? → Use [`contact`](crate::query::contact())
/// - Need penetration depth? → Use [`contact`](crate::query::contact())
/// - Need separation distance? → Use [`distance`](crate::query::distance())
/// - Need closest points? → Use [`closest_points`](crate::query::closest_points())
///
/// # See Also
///
/// - [`contact`](crate::query::contact()) - Get contact information if intersecting
/// - [`distance`](crate::query::distance()) - Get separation distance
/// - [`closest_points`](crate::query::closest_points()) - Get closest point locations
pub fn intersection_test(
    pos1: &Pose,
    g1: &dyn Shape,
    pos2: &Pose,
    g2: &dyn Shape,
) -> Result<ShapeIntersection, Unsupported> {
    let pos12 = pos1.inv_mul(pos2);
    DefaultQueryDispatcher.intersection_test(&pos12, g1, g2)
}