bevy_math 0.20.0

Provides math functionality for Bevy Engine
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

//! This module holds local implementations of the [`Distribution`] trait for [`StandardUniform`], which
//! allow certain Bevy math types (those whose values can be randomly generated without additional
//! input other than an [`RngExt`]) to be produced using [`rand`]'s APIs. It also holds [`FromRng`],
//! an ergonomic extension to that functionality which permits the omission of type annotations.
//!
//! For instance:
//! ```
//! # use rand::{random,  RngExt, SeedableRng, rngs::StdRng, distr::StandardUniform};
//! # use bevy_math::{Dir3, sampling::FromRng};
//! let mut rng = StdRng::seed_from_u64(7313429298);
//! // Random direction using thread-local rng
//! let random_direction1: Dir3 = random();
//!
//! // Random direction using the rng constructed above
//! let random_direction2: Dir3 = rng.random();
//!
//! // The same as the previous but with different syntax
//! let random_direction3 = Dir3::from_rng(&mut rng);
//!
//! // Five random directions, using StandardUniform explicitly
//! let many_random_directions: Vec<Dir3> = rng.sample_iter(StandardUniform).take(5).collect();
//! ```

use core::f32::consts::{PI, TAU};

use crate::{ops, Dir2, Dir3, Dir3A, Quat, Rot2, Vec2, Vec3};
use rand::{
    distr::{Distribution, StandardUniform},
    RngExt,
};

/// Ergonomics trait for a type with a [`StandardUniform`] distribution, allowing values to be generated
/// uniformly from an [`RngExt`] by a method in its own namespace.
///
/// Example
/// ```
/// # use rand::{RngExt, SeedableRng, rngs::StdRng};
/// # use bevy_math::{Dir3, sampling::FromRng};
/// let mut rng = StdRng::seed_from_u64(451);
/// let random_dir = Dir3::from_rng(&mut rng);
/// ```
pub trait FromRng
where
    Self: Sized,
    StandardUniform: Distribution<Self>,
{
    /// Construct a value of this type uniformly at random using `rng` as the source of randomness.
    fn from_rng<R: RngExt + ?Sized>(rng: &mut R) -> Self {
        rng.random()
    }
}

impl Distribution<Dir2> for StandardUniform {
    #[inline]
    fn sample<R: RngExt + ?Sized>(&self, rng: &mut R) -> Dir2 {
        let theta = rng.random_range(0.0..TAU);
        let (sin, cos) = ops::sin_cos(theta);
        let vector = Vec2::new(cos, sin);
        Dir2::new_unchecked(vector)
    }
}

/// Boundary sampling for unit-spheres
#[inline]
fn sample_unit_sphere_boundary<R: RngExt + ?Sized>(rng: &mut R) -> Vec3 {
    let z = rng.random_range(-1f32..=1f32);
    let (a_sin, a_cos) = ops::sin_cos(rng.random_range(-PI..=PI));
    let c = ops::sqrt(1f32 - z * z);
    let x = a_sin * c;
    let y = a_cos * c;

    Vec3::new(x, y, z)
}

impl FromRng for Dir2 {}

impl Distribution<Dir3> for StandardUniform {
    #[inline]
    fn sample<R: RngExt + ?Sized>(&self, rng: &mut R) -> Dir3 {
        let vector = sample_unit_sphere_boundary(rng);
        Dir3::new_unchecked(vector)
    }
}

impl FromRng for Dir3 {}

impl Distribution<Dir3A> for StandardUniform {
    #[inline]
    fn sample<R: RngExt + ?Sized>(&self, rng: &mut R) -> Dir3A {
        let vector = sample_unit_sphere_boundary(rng);
        Dir3A::new_unchecked(vector.to_vec3a())
    }
}

impl FromRng for Dir3A {}

impl Distribution<Rot2> for StandardUniform {
    #[inline]
    fn sample<R: RngExt + ?Sized>(&self, rng: &mut R) -> Rot2 {
        let angle = rng.random_range(0.0..TAU);
        Rot2::radians(angle)
    }
}

impl FromRng for Rot2 {}

impl FromRng for Quat {}