glam/f64/
dvec3.rs

Help
1// Generated from vec.rs.tera template. Edit the template, not the generated file.
2
3use crate::{f64::math, BVec3, DVec2, DVec4, IVec3, UVec3, Vec3};
4
5#[cfg(not(target_arch = "spirv"))]
6use core::fmt;
7use core::iter::{Product, Sum};
8use core::{f32, ops::*};
9
10/// Creates a 3-dimensional vector.
11#[inline(always)]
12#[must_use]
13pub const fn dvec3(x: f64, y: f64, z: f64) -> DVec3 {
14    DVec3::new(x, y, z)
15}
16
17/// A 3-dimensional vector.
18#[derive(Clone, Copy, PartialEq)]
19#[cfg_attr(not(target_arch = "spirv"), repr(C))]
20#[cfg_attr(target_arch = "spirv", repr(simd))]
21pub struct DVec3 {
22    pub x: f64,
23    pub y: f64,
24    pub z: f64,
25}
26
27impl DVec3 {
28    /// All zeroes.
29    pub const ZERO: Self = Self::splat(0.0);
30
31    /// All ones.
32    pub const ONE: Self = Self::splat(1.0);
33
34    /// All negative ones.
35    pub const NEG_ONE: Self = Self::splat(-1.0);
36
37    /// All `f64::MIN`.
38    pub const MIN: Self = Self::splat(f64::MIN);
39
40    /// All `f64::MAX`.
41    pub const MAX: Self = Self::splat(f64::MAX);
42
43    /// All `f64::NAN`.
44    pub const NAN: Self = Self::splat(f64::NAN);
45
46    /// All `f64::INFINITY`.
47    pub const INFINITY: Self = Self::splat(f64::INFINITY);
48
49    /// All `f64::NEG_INFINITY`.
50    pub const NEG_INFINITY: Self = Self::splat(f64::NEG_INFINITY);
51
52    /// A unit vector pointing along the positive X axis.
53    pub const X: Self = Self::new(1.0, 0.0, 0.0);
54
55    /// A unit vector pointing along the positive Y axis.
56    pub const Y: Self = Self::new(0.0, 1.0, 0.0);
57
58    /// A unit vector pointing along the positive Z axis.
59    pub const Z: Self = Self::new(0.0, 0.0, 1.0);
60
61    /// A unit vector pointing along the negative X axis.
62    pub const NEG_X: Self = Self::new(-1.0, 0.0, 0.0);
63
64    /// A unit vector pointing along the negative Y axis.
65    pub const NEG_Y: Self = Self::new(0.0, -1.0, 0.0);
66
67    /// A unit vector pointing along the negative Z axis.
68    pub const NEG_Z: Self = Self::new(0.0, 0.0, -1.0);
69
70    /// The unit axes.
71    pub const AXES: [Self; 3] = [Self::X, Self::Y, Self::Z];
72
73    /// Creates a new vector.
74    #[inline(always)]
75    #[must_use]
76    pub const fn new(x: f64, y: f64, z: f64) -> Self {
77        Self { x, y, z }
78    }
79
80    /// Creates a vector with all elements set to `v`.
81    #[inline]
82    #[must_use]
83    pub const fn splat(v: f64) -> Self {
84        Self { x: v, y: v, z: v }
85    }
86
87    /// Creates a vector from the elements in `if_true` and `if_false`, selecting which to use
88    /// for each element of `self`.
89    ///
90    /// A true element in the mask uses the corresponding element from `if_true`, and false
91    /// uses the element from `if_false`.
92    #[inline]
93    #[must_use]
94    pub fn select(mask: BVec3, if_true: Self, if_false: Self) -> Self {
95        Self {
96            x: if mask.test(0) { if_true.x } else { if_false.x },
97            y: if mask.test(1) { if_true.y } else { if_false.y },
98            z: if mask.test(2) { if_true.z } else { if_false.z },
99        }
100    }
101
102    /// Creates a new vector from an array.
103    #[inline]
104    #[must_use]
105    pub const fn from_array(a: [f64; 3]) -> Self {
106        Self::new(a[0], a[1], a[2])
107    }
108
109    /// `[x, y, z]`
110    #[inline]
111    #[must_use]
112    pub const fn to_array(&self) -> [f64; 3] {
113        [self.x, self.y, self.z]
114    }
115
116    /// Creates a vector from the first 3 values in `slice`.
117    ///
118    /// # Panics
119    ///
120    /// Panics if `slice` is less than 3 elements long.
121    #[inline]
122    #[must_use]
123    pub const fn from_slice(slice: &[f64]) -> Self {
124        Self::new(slice[0], slice[1], slice[2])
125    }
126
127    /// Writes the elements of `self` to the first 3 elements in `slice`.
128    ///
129    /// # Panics
130    ///
131    /// Panics if `slice` is less than 3 elements long.
132    #[inline]
133    pub fn write_to_slice(self, slice: &mut [f64]) {
134        slice[0] = self.x;
135        slice[1] = self.y;
136        slice[2] = self.z;
137    }
138
139    /// Internal method for creating a 3D vector from a 4D vector, discarding `w`.
140    #[allow(dead_code)]
141    #[inline]
142    #[must_use]
143    pub(crate) fn from_vec4(v: DVec4) -> Self {
144        Self {
145            x: v.x,
146            y: v.y,
147            z: v.z,
148        }
149    }
150
151    /// Creates a 4D vector from `self` and the given `w` value.
152    #[inline]
153    #[must_use]
154    pub fn extend(self, w: f64) -> DVec4 {
155        DVec4::new(self.x, self.y, self.z, w)
156    }
157
158    /// Creates a 2D vector from the `x` and `y` elements of `self`, discarding `z`.
159    ///
160    /// Truncation may also be performed by using [`self.xy()`][crate::swizzles::Vec3Swizzles::xy()].
161    #[inline]
162    #[must_use]
163    pub fn truncate(self) -> DVec2 {
164        use crate::swizzles::Vec3Swizzles;
165        self.xy()
166    }
167
168    /// Computes the dot product of `self` and `rhs`.
169    #[inline]
170    #[must_use]
171    pub fn dot(self, rhs: Self) -> f64 {
172        (self.x * rhs.x) + (self.y * rhs.y) + (self.z * rhs.z)
173    }
174
175    /// Returns a vector where every component is the dot product of `self` and `rhs`.
176    #[inline]
177    #[must_use]
178    pub fn dot_into_vec(self, rhs: Self) -> Self {
179        Self::splat(self.dot(rhs))
180    }
181
182    /// Computes the cross product of `self` and `rhs`.
183    #[inline]
184    #[must_use]
185    pub fn cross(self, rhs: Self) -> Self {
186        Self {
187            x: self.y * rhs.z - rhs.y * self.z,
188            y: self.z * rhs.x - rhs.z * self.x,
189            z: self.x * rhs.y - rhs.x * self.y,
190        }
191    }
192
193    /// Returns a vector containing the minimum values for each element of `self` and `rhs`.
194    ///
195    /// In other words this computes `[self.x.min(rhs.x), self.y.min(rhs.y), ..]`.
196    #[inline]
197    #[must_use]
198    pub fn min(self, rhs: Self) -> Self {
199        Self {
200            x: self.x.min(rhs.x),
201            y: self.y.min(rhs.y),
202            z: self.z.min(rhs.z),
203        }
204    }
205
206    /// Returns a vector containing the maximum values for each element of `self` and `rhs`.
207    ///
208    /// In other words this computes `[self.x.max(rhs.x), self.y.max(rhs.y), ..]`.
209    #[inline]
210    #[must_use]
211    pub fn max(self, rhs: Self) -> Self {
212        Self {
213            x: self.x.max(rhs.x),
214            y: self.y.max(rhs.y),
215            z: self.z.max(rhs.z),
216        }
217    }
218
219    /// Component-wise clamping of values, similar to [`f64::clamp`].
220    ///
221    /// Each element in `min` must be less-or-equal to the corresponding element in `max`.
222    ///
223    /// # Panics
224    ///
225    /// Will panic if `min` is greater than `max` when `glam_assert` is enabled.
226    #[inline]
227    #[must_use]
228    pub fn clamp(self, min: Self, max: Self) -> Self {
229        glam_assert!(min.cmple(max).all(), "clamp: expected min <= max");
230        self.max(min).min(max)
231    }
232
233    /// Returns the horizontal minimum of `self`.
234    ///
235    /// In other words this computes `min(x, y, ..)`.
236    #[inline]
237    #[must_use]
238    pub fn min_element(self) -> f64 {
239        self.x.min(self.y.min(self.z))
240    }
241
242    /// Returns the horizontal maximum of `self`.
243    ///
244    /// In other words this computes `max(x, y, ..)`.
245    #[inline]
246    #[must_use]
247    pub fn max_element(self) -> f64 {
248        self.x.max(self.y.max(self.z))
249    }
250
251    /// Returns a vector mask containing the result of a `==` comparison for each element of
252    /// `self` and `rhs`.
253    ///
254    /// In other words, this computes `[self.x == rhs.x, self.y == rhs.y, ..]` for all
255    /// elements.
256    #[inline]
257    #[must_use]
258    pub fn cmpeq(self, rhs: Self) -> BVec3 {
259        BVec3::new(self.x.eq(&rhs.x), self.y.eq(&rhs.y), self.z.eq(&rhs.z))
260    }
261
262    /// Returns a vector mask containing the result of a `!=` comparison for each element of
263    /// `self` and `rhs`.
264    ///
265    /// In other words this computes `[self.x != rhs.x, self.y != rhs.y, ..]` for all
266    /// elements.
267    #[inline]
268    #[must_use]
269    pub fn cmpne(self, rhs: Self) -> BVec3 {
270        BVec3::new(self.x.ne(&rhs.x), self.y.ne(&rhs.y), self.z.ne(&rhs.z))
271    }
272
273    /// Returns a vector mask containing the result of a `>=` comparison for each element of
274    /// `self` and `rhs`.
275    ///
276    /// In other words this computes `[self.x >= rhs.x, self.y >= rhs.y, ..]` for all
277    /// elements.
278    #[inline]
279    #[must_use]
280    pub fn cmpge(self, rhs: Self) -> BVec3 {
281        BVec3::new(self.x.ge(&rhs.x), self.y.ge(&rhs.y), self.z.ge(&rhs.z))
282    }
283
284    /// Returns a vector mask containing the result of a `>` comparison for each element of
285    /// `self` and `rhs`.
286    ///
287    /// In other words this computes `[self.x > rhs.x, self.y > rhs.y, ..]` for all
288    /// elements.
289    #[inline]
290    #[must_use]
291    pub fn cmpgt(self, rhs: Self) -> BVec3 {
292        BVec3::new(self.x.gt(&rhs.x), self.y.gt(&rhs.y), self.z.gt(&rhs.z))
293    }
294
295    /// Returns a vector mask containing the result of a `<=` comparison for each element of
296    /// `self` and `rhs`.
297    ///
298    /// In other words this computes `[self.x <= rhs.x, self.y <= rhs.y, ..]` for all
299    /// elements.
300    #[inline]
301    #[must_use]
302    pub fn cmple(self, rhs: Self) -> BVec3 {
303        BVec3::new(self.x.le(&rhs.x), self.y.le(&rhs.y), self.z.le(&rhs.z))
304    }
305
306    /// Returns a vector mask containing the result of a `<` comparison for each element of
307    /// `self` and `rhs`.
308    ///
309    /// In other words this computes `[self.x < rhs.x, self.y < rhs.y, ..]` for all
310    /// elements.
311    #[inline]
312    #[must_use]
313    pub fn cmplt(self, rhs: Self) -> BVec3 {
314        BVec3::new(self.x.lt(&rhs.x), self.y.lt(&rhs.y), self.z.lt(&rhs.z))
315    }
316
317    /// Returns a vector containing the absolute value of each element of `self`.
318    #[inline]
319    #[must_use]
320    pub fn abs(self) -> Self {
321        Self {
322            x: math::abs(self.x),
323            y: math::abs(self.y),
324            z: math::abs(self.z),
325        }
326    }
327
328    /// Returns a vector with elements representing the sign of `self`.
329    ///
330    /// - `1.0` if the number is positive, `+0.0` or `INFINITY`
331    /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY`
332    /// - `NAN` if the number is `NAN`
333    #[inline]
334    #[must_use]
335    pub fn signum(self) -> Self {
336        Self {
337            x: math::signum(self.x),
338            y: math::signum(self.y),
339            z: math::signum(self.z),
340        }
341    }
342
343    /// Returns a vector with signs of `rhs` and the magnitudes of `self`.
344    #[inline]
345    #[must_use]
346    pub fn copysign(self, rhs: Self) -> Self {
347        Self {
348            x: math::copysign(self.x, rhs.x),
349            y: math::copysign(self.y, rhs.y),
350            z: math::copysign(self.z, rhs.z),
351        }
352    }
353
354    /// Returns a bitmask with the lowest 3 bits set to the sign bits from the elements of `self`.
355    ///
356    /// A negative element results in a `1` bit and a positive element in a `0` bit.  Element `x` goes
357    /// into the first lowest bit, element `y` into the second, etc.
358    #[inline]
359    #[must_use]
360    pub fn is_negative_bitmask(self) -> u32 {
361        (self.x.is_sign_negative() as u32)
362            | (self.y.is_sign_negative() as u32) << 1
363            | (self.z.is_sign_negative() as u32) << 2
364    }
365
366    /// Returns `true` if, and only if, all elements are finite.  If any element is either
367    /// `NaN`, positive or negative infinity, this will return `false`.
368    #[inline]
369    #[must_use]
370    pub fn is_finite(self) -> bool {
371        self.x.is_finite() && self.y.is_finite() && self.z.is_finite()
372    }
373
374    /// Returns `true` if any elements are `NaN`.
375    #[inline]
376    #[must_use]
377    pub fn is_nan(self) -> bool {
378        self.x.is_nan() || self.y.is_nan() || self.z.is_nan()
379    }
380
381    /// Performs `is_nan` on each element of self, returning a vector mask of the results.
382    ///
383    /// In other words, this computes `[x.is_nan(), y.is_nan(), z.is_nan(), w.is_nan()]`.
384    #[inline]
385    #[must_use]
386    pub fn is_nan_mask(self) -> BVec3 {
387        BVec3::new(self.x.is_nan(), self.y.is_nan(), self.z.is_nan())
388    }
389
390    /// Computes the length of `self`.
391    #[doc(alias = "magnitude")]
392    #[inline]
393    #[must_use]
394    pub fn length(self) -> f64 {
395        math::sqrt(self.dot(self))
396    }
397
398    /// Computes the squared length of `self`.
399    ///
400    /// This is faster than `length()` as it avoids a square root operation.
401    #[doc(alias = "magnitude2")]
402    #[inline]
403    #[must_use]
404    pub fn length_squared(self) -> f64 {
405        self.dot(self)
406    }
407
408    /// Computes `1.0 / length()`.
409    ///
410    /// For valid results, `self` must _not_ be of length zero.
411    #[inline]
412    #[must_use]
413    pub fn length_recip(self) -> f64 {
414        self.length().recip()
415    }
416
417    /// Computes the Euclidean distance between two points in space.
418    #[inline]
419    #[must_use]
420    pub fn distance(self, rhs: Self) -> f64 {
421        (self - rhs).length()
422    }
423
424    /// Compute the squared euclidean distance between two points in space.
425    #[inline]
426    #[must_use]
427    pub fn distance_squared(self, rhs: Self) -> f64 {
428        (self - rhs).length_squared()
429    }
430
431    /// Returns the element-wise quotient of [Euclidean division] of `self` by `rhs`.
432    #[inline]
433    #[must_use]
434    pub fn div_euclid(self, rhs: Self) -> Self {
435        Self::new(
436            math::div_euclid(self.x, rhs.x),
437            math::div_euclid(self.y, rhs.y),
438            math::div_euclid(self.z, rhs.z),
439        )
440    }
441
442    /// Returns the element-wise remainder of [Euclidean division] of `self` by `rhs`.
443    ///
444    /// [Euclidean division]: f64::rem_euclid
445    #[inline]
446    #[must_use]
447    pub fn rem_euclid(self, rhs: Self) -> Self {
448        Self::new(
449            math::rem_euclid(self.x, rhs.x),
450            math::rem_euclid(self.y, rhs.y),
451            math::rem_euclid(self.z, rhs.z),
452        )
453    }
454
455    /// Returns `self` normalized to length 1.0.
456    ///
457    /// For valid results, `self` must _not_ be of length zero, nor very close to zero.
458    ///
459    /// See also [`Self::try_normalize()`] and [`Self::normalize_or_zero()`].
460    ///
461    /// Panics
462    ///
463    /// Will panic if `self` is zero length when `glam_assert` is enabled.
464    #[inline]
465    #[must_use]
466    pub fn normalize(self) -> Self {
467        #[allow(clippy::let_and_return)]
468        let normalized = self.mul(self.length_recip());
469        glam_assert!(normalized.is_finite());
470        normalized
471    }
472
473    /// Returns `self` normalized to length 1.0 if possible, else returns `None`.
474    ///
475    /// In particular, if the input is zero (or very close to zero), or non-finite,
476    /// the result of this operation will be `None`.
477    ///
478    /// See also [`Self::normalize_or_zero()`].
479    #[inline]
480    #[must_use]
481    pub fn try_normalize(self) -> Option<Self> {
482        let rcp = self.length_recip();
483        if rcp.is_finite() && rcp > 0.0 {
484            Some(self * rcp)
485        } else {
486            None
487        }
488    }
489
490    /// Returns `self` normalized to length 1.0 if possible, else returns zero.
491    ///
492    /// In particular, if the input is zero (or very close to zero), or non-finite,
493    /// the result of this operation will be zero.
494    ///
495    /// See also [`Self::try_normalize()`].
496    #[inline]
497    #[must_use]
498    pub fn normalize_or_zero(self) -> Self {
499        let rcp = self.length_recip();
500        if rcp.is_finite() && rcp > 0.0 {
501            self * rcp
502        } else {
503            Self::ZERO
504        }
505    }
506
507    /// Returns whether `self` is length `1.0` or not.
508    ///
509    /// Uses a precision threshold of `1e-6`.
510    #[inline]
511    #[must_use]
512    pub fn is_normalized(self) -> bool {
513        // TODO: do something with epsilon
514        math::abs(self.length_squared() - 1.0) <= 1e-4
515    }
516
517    /// Returns the vector projection of `self` onto `rhs`.
518    ///
519    /// `rhs` must be of non-zero length.
520    ///
521    /// # Panics
522    ///
523    /// Will panic if `rhs` is zero length when `glam_assert` is enabled.
524    #[inline]
525    #[must_use]
526    pub fn project_onto(self, rhs: Self) -> Self {
527        let other_len_sq_rcp = rhs.dot(rhs).recip();
528        glam_assert!(other_len_sq_rcp.is_finite());
529        rhs * self.dot(rhs) * other_len_sq_rcp
530    }
531
532    /// Returns the vector rejection of `self` from `rhs`.
533    ///
534    /// The vector rejection is the vector perpendicular to the projection of `self` onto
535    /// `rhs`, in rhs words the result of `self - self.project_onto(rhs)`.
536    ///
537    /// `rhs` must be of non-zero length.
538    ///
539    /// # Panics
540    ///
541    /// Will panic if `rhs` has a length of zero when `glam_assert` is enabled.
542    #[inline]
543    #[must_use]
544    pub fn reject_from(self, rhs: Self) -> Self {
545        self - self.project_onto(rhs)
546    }
547
548    /// Returns the vector projection of `self` onto `rhs`.
549    ///
550    /// `rhs` must be normalized.
551    ///
552    /// # Panics
553    ///
554    /// Will panic if `rhs` is not normalized when `glam_assert` is enabled.
555    #[inline]
556    #[must_use]
557    pub fn project_onto_normalized(self, rhs: Self) -> Self {
558        glam_assert!(rhs.is_normalized());
559        rhs * self.dot(rhs)
560    }
561
562    /// Returns the vector rejection of `self` from `rhs`.
563    ///
564    /// The vector rejection is the vector perpendicular to the projection of `self` onto
565    /// `rhs`, in rhs words the result of `self - self.project_onto(rhs)`.
566    ///
567    /// `rhs` must be normalized.
568    ///
569    /// # Panics
570    ///
571    /// Will panic if `rhs` is not normalized when `glam_assert` is enabled.
572    #[inline]
573    #[must_use]
574    pub fn reject_from_normalized(self, rhs: Self) -> Self {
575        self - self.project_onto_normalized(rhs)
576    }
577
578    /// Returns a vector containing the nearest integer to a number for each element of `self`.
579    /// Round half-way cases away from 0.0.
580    #[inline]
581    #[must_use]
582    pub fn round(self) -> Self {
583        Self {
584            x: math::round(self.x),
585            y: math::round(self.y),
586            z: math::round(self.z),
587        }
588    }
589
590    /// Returns a vector containing the largest integer less than or equal to a number for each
591    /// element of `self`.
592    #[inline]
593    #[must_use]
594    pub fn floor(self) -> Self {
595        Self {
596            x: math::floor(self.x),
597            y: math::floor(self.y),
598            z: math::floor(self.z),
599        }
600    }
601
602    /// Returns a vector containing the smallest integer greater than or equal to a number for
603    /// each element of `self`.
604    #[inline]
605    #[must_use]
606    pub fn ceil(self) -> Self {
607        Self {
608            x: math::ceil(self.x),
609            y: math::ceil(self.y),
610            z: math::ceil(self.z),
611        }
612    }
613
614    /// Returns a vector containing the integer part each element of `self`. This means numbers are
615    /// always truncated towards zero.
616    #[inline]
617    #[must_use]
618    pub fn trunc(self) -> Self {
619        Self {
620            x: math::trunc(self.x),
621            y: math::trunc(self.y),
622            z: math::trunc(self.z),
623        }
624    }
625
626    /// Returns a vector containing the fractional part of the vector, e.g. `self -
627    /// self.floor()`.
628    ///
629    /// Note that this is fast but not precise for large numbers.
630    #[inline]
631    #[must_use]
632    pub fn fract(self) -> Self {
633        self - self.floor()
634    }
635
636    /// Returns a vector containing `e^self` (the exponential function) for each element of
637    /// `self`.
638    #[inline]
639    #[must_use]
640    pub fn exp(self) -> Self {
641        Self::new(math::exp(self.x), math::exp(self.y), math::exp(self.z))
642    }
643
644    /// Returns a vector containing each element of `self` raised to the power of `n`.
645    #[inline]
646    #[must_use]
647    pub fn powf(self, n: f64) -> Self {
648        Self::new(
649            math::powf(self.x, n),
650            math::powf(self.y, n),
651            math::powf(self.z, n),
652        )
653    }
654
655    /// Returns a vector containing the reciprocal `1.0/n` of each element of `self`.
656    #[inline]
657    #[must_use]
658    pub fn recip(self) -> Self {
659        Self {
660            x: 1.0 / self.x,
661            y: 1.0 / self.y,
662            z: 1.0 / self.z,
663        }
664    }
665
666    /// Performs a linear interpolation between `self` and `rhs` based on the value `s`.
667    ///
668    /// When `s` is `0.0`, the result will be equal to `self`.  When `s` is `1.0`, the result
669    /// will be equal to `rhs`. When `s` is outside of range `[0, 1]`, the result is linearly
670    /// extrapolated.
671    #[doc(alias = "mix")]
672    #[inline]
673    #[must_use]
674    pub fn lerp(self, rhs: Self, s: f64) -> Self {
675        self + ((rhs - self) * s)
676    }
677
678    /// Returns true if the absolute difference of all elements between `self` and `rhs` is
679    /// less than or equal to `max_abs_diff`.
680    ///
681    /// This can be used to compare if two vectors contain similar elements. It works best when
682    /// comparing with a known value. The `max_abs_diff` that should be used used depends on
683    /// the values being compared against.
684    ///
685    /// For more see
686    /// [comparing floating point numbers](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/).
687    #[inline]
688    #[must_use]
689    pub fn abs_diff_eq(self, rhs: Self, max_abs_diff: f64) -> bool {
690        self.sub(rhs).abs().cmple(Self::splat(max_abs_diff)).all()
691    }
692
693    /// Returns a vector with a length no less than `min` and no more than `max`
694    ///
695    /// # Panics
696    ///
697    /// Will panic if `min` is greater than `max` when `glam_assert` is enabled.
698    #[inline]
699    #[must_use]
700    pub fn clamp_length(self, min: f64, max: f64) -> Self {
701        glam_assert!(min <= max);
702        let length_sq = self.length_squared();
703        if length_sq < min * min {
704            min * (self / math::sqrt(length_sq))
705        } else if length_sq > max * max {
706            max * (self / math::sqrt(length_sq))
707        } else {
708            self
709        }
710    }
711
712    /// Returns a vector with a length no more than `max`
713    #[inline]
714    #[must_use]
715    pub fn clamp_length_max(self, max: f64) -> Self {
716        let length_sq = self.length_squared();
717        if length_sq > max * max {
718            max * (self / math::sqrt(length_sq))
719        } else {
720            self
721        }
722    }
723
724    /// Returns a vector with a length no less than `min`
725    #[inline]
726    #[must_use]
727    pub fn clamp_length_min(self, min: f64) -> Self {
728        let length_sq = self.length_squared();
729        if length_sq < min * min {
730            min * (self / math::sqrt(length_sq))
731        } else {
732            self
733        }
734    }
735
736    /// Fused multiply-add. Computes `(self * a) + b` element-wise with only one rounding
737    /// error, yielding a more accurate result than an unfused multiply-add.
738    ///
739    /// Using `mul_add` *may* be more performant than an unfused multiply-add if the target
740    /// architecture has a dedicated fma CPU instruction. However, this is not always true,
741    /// and will be heavily dependant on designing algorithms with specific target hardware in
742    /// mind.
743    #[inline]
744    #[must_use]
745    pub fn mul_add(self, a: Self, b: Self) -> Self {
746        Self::new(
747            math::mul_add(self.x, a.x, b.x),
748            math::mul_add(self.y, a.y, b.y),
749            math::mul_add(self.z, a.z, b.z),
750        )
751    }
752
753    /// Returns the angle (in radians) between two vectors.
754    ///
755    /// The inputs do not need to be unit vectors however they must be non-zero.
756    #[inline]
757    #[must_use]
758    pub fn angle_between(self, rhs: Self) -> f64 {
759        math::acos_approx(
760            self.dot(rhs)
761                .div(math::sqrt(self.length_squared().mul(rhs.length_squared()))),
762        )
763    }
764
765    /// Returns some vector that is orthogonal to the given one.
766    ///
767    /// The input vector must be finite and non-zero.
768    ///
769    /// The output vector is not necessarily unit length. For that use
770    /// [`Self::any_orthonormal_vector()`] instead.
771    #[inline]
772    #[must_use]
773    pub fn any_orthogonal_vector(&self) -> Self {
774        // This can probably be optimized
775        if math::abs(self.x) > math::abs(self.y) {
776            Self::new(-self.z, 0.0, self.x) // self.cross(Self::Y)
777        } else {
778            Self::new(0.0, self.z, -self.y) // self.cross(Self::X)
779        }
780    }
781
782    /// Returns any unit vector that is orthogonal to the given one.
783    ///
784    /// The input vector must be unit length.
785    ///
786    /// # Panics
787    ///
788    /// Will panic if `self` is not normalized when `glam_assert` is enabled.
789    #[inline]
790    #[must_use]
791    pub fn any_orthonormal_vector(&self) -> Self {
792        glam_assert!(self.is_normalized());
793        // From https://graphics.pixar.com/library/OrthonormalB/paper.pdf
794        let sign = math::signum(self.z);
795        let a = -1.0 / (sign + self.z);
796        let b = self.x * self.y * a;
797        Self::new(b, sign + self.y * self.y * a, -self.y)
798    }
799
800    /// Given a unit vector return two other vectors that together form an orthonormal
801    /// basis. That is, all three vectors are orthogonal to each other and are normalized.
802    ///
803    /// # Panics
804    ///
805    /// Will panic if `self` is not normalized when `glam_assert` is enabled.
806    #[inline]
807    #[must_use]
808    pub fn any_orthonormal_pair(&self) -> (Self, Self) {
809        glam_assert!(self.is_normalized());
810        // From https://graphics.pixar.com/library/OrthonormalB/paper.pdf
811        let sign = math::signum(self.z);
812        let a = -1.0 / (sign + self.z);
813        let b = self.x * self.y * a;
814        (
815            Self::new(1.0 + sign * self.x * self.x * a, sign * b, -sign * self.x),
816            Self::new(b, sign + self.y * self.y * a, -self.y),
817        )
818    }
819
820    /// Casts all elements of `self` to `f32`.
821    #[inline]
822    #[must_use]
823    pub fn as_vec3(&self) -> crate::Vec3 {
824        crate::Vec3::new(self.x as f32, self.y as f32, self.z as f32)
825    }
826
827    /// Casts all elements of `self` to `f32`.
828    #[inline]
829    #[must_use]
830    pub fn as_vec3a(&self) -> crate::Vec3A {
831        crate::Vec3A::new(self.x as f32, self.y as f32, self.z as f32)
832    }
833
834    /// Casts all elements of `self` to `i16`.
835    #[inline]
836    #[must_use]
837    pub fn as_i16vec3(&self) -> crate::I16Vec3 {
838        crate::I16Vec3::new(self.x as i16, self.y as i16, self.z as i16)
839    }
840
841    /// Casts all elements of `self` to `u16`.
842    #[inline]
843    #[must_use]
844    pub fn as_u16vec3(&self) -> crate::U16Vec3 {
845        crate::U16Vec3::new(self.x as u16, self.y as u16, self.z as u16)
846    }
847
848    /// Casts all elements of `self` to `i32`.
849    #[inline]
850    #[must_use]
851    pub fn as_ivec3(&self) -> crate::IVec3 {
852        crate::IVec3::new(self.x as i32, self.y as i32, self.z as i32)
853    }
854
855    /// Casts all elements of `self` to `u32`.
856    #[inline]
857    #[must_use]
858    pub fn as_uvec3(&self) -> crate::UVec3 {
859        crate::UVec3::new(self.x as u32, self.y as u32, self.z as u32)
860    }
861
862    /// Casts all elements of `self` to `i64`.
863    #[inline]
864    #[must_use]
865    pub fn as_i64vec3(&self) -> crate::I64Vec3 {
866        crate::I64Vec3::new(self.x as i64, self.y as i64, self.z as i64)
867    }
868
869    /// Casts all elements of `self` to `u64`.
870    #[inline]
871    #[must_use]
872    pub fn as_u64vec3(&self) -> crate::U64Vec3 {
873        crate::U64Vec3::new(self.x as u64, self.y as u64, self.z as u64)
874    }
875}
876
877impl Default for DVec3 {
878    #[inline(always)]
879    fn default() -> Self {
880        Self::ZERO
881    }
882}
883
884impl Div<DVec3> for DVec3 {
885    type Output = Self;
886    #[inline]
887    fn div(self, rhs: Self) -> Self {
888        Self {
889            x: self.x.div(rhs.x),
890            y: self.y.div(rhs.y),
891            z: self.z.div(rhs.z),
892        }
893    }
894}
895
896impl DivAssign<DVec3> for DVec3 {
897    #[inline]
898    fn div_assign(&mut self, rhs: Self) {
899        self.x.div_assign(rhs.x);
900        self.y.div_assign(rhs.y);
901        self.z.div_assign(rhs.z);
902    }
903}
904
905impl Div<f64> for DVec3 {
906    type Output = Self;
907    #[inline]
908    fn div(self, rhs: f64) -> Self {
909        Self {
910            x: self.x.div(rhs),
911            y: self.y.div(rhs),
912            z: self.z.div(rhs),
913        }
914    }
915}
916
917impl DivAssign<f64> for DVec3 {
918    #[inline]
919    fn div_assign(&mut self, rhs: f64) {
920        self.x.div_assign(rhs);
921        self.y.div_assign(rhs);
922        self.z.div_assign(rhs);
923    }
924}
925
926impl Div<DVec3> for f64 {
927    type Output = DVec3;
928    #[inline]
929    fn div(self, rhs: DVec3) -> DVec3 {
930        DVec3 {
931            x: self.div(rhs.x),
932            y: self.div(rhs.y),
933            z: self.div(rhs.z),
934        }
935    }
936}
937
938impl Mul<DVec3> for DVec3 {
939    type Output = Self;
940    #[inline]
941    fn mul(self, rhs: Self) -> Self {
942        Self {
943            x: self.x.mul(rhs.x),
944            y: self.y.mul(rhs.y),
945            z: self.z.mul(rhs.z),
946        }
947    }
948}
949
950impl MulAssign<DVec3> for DVec3 {
951    #[inline]
952    fn mul_assign(&mut self, rhs: Self) {
953        self.x.mul_assign(rhs.x);
954        self.y.mul_assign(rhs.y);
955        self.z.mul_assign(rhs.z);
956    }
957}
958
959impl Mul<f64> for DVec3 {
960    type Output = Self;
961    #[inline]
962    fn mul(self, rhs: f64) -> Self {
963        Self {
964            x: self.x.mul(rhs),
965            y: self.y.mul(rhs),
966            z: self.z.mul(rhs),
967        }
968    }
969}
970
971impl MulAssign<f64> for DVec3 {
972    #[inline]
973    fn mul_assign(&mut self, rhs: f64) {
974        self.x.mul_assign(rhs);
975        self.y.mul_assign(rhs);
976        self.z.mul_assign(rhs);
977    }
978}
979
980impl Mul<DVec3> for f64 {
981    type Output = DVec3;
982    #[inline]
983    fn mul(self, rhs: DVec3) -> DVec3 {
984        DVec3 {
985            x: self.mul(rhs.x),
986            y: self.mul(rhs.y),
987            z: self.mul(rhs.z),
988        }
989    }
990}
991
992impl Add<DVec3> for DVec3 {
993    type Output = Self;
994    #[inline]
995    fn add(self, rhs: Self) -> Self {
996        Self {
997            x: self.x.add(rhs.x),
998            y: self.y.add(rhs.y),
999            z: self.z.add(rhs.z),
1000        }
1001    }
1002}
1003
1004impl AddAssign<DVec3> for DVec3 {
1005    #[inline]
1006    fn add_assign(&mut self, rhs: Self) {
1007        self.x.add_assign(rhs.x);
1008        self.y.add_assign(rhs.y);
1009        self.z.add_assign(rhs.z);
1010    }
1011}
1012
1013impl Add<f64> for DVec3 {
1014    type Output = Self;
1015    #[inline]
1016    fn add(self, rhs: f64) -> Self {
1017        Self {
1018            x: self.x.add(rhs),
1019            y: self.y.add(rhs),
1020            z: self.z.add(rhs),
1021        }
1022    }
1023}
1024
1025impl AddAssign<f64> for DVec3 {
1026    #[inline]
1027    fn add_assign(&mut self, rhs: f64) {
1028        self.x.add_assign(rhs);
1029        self.y.add_assign(rhs);
1030        self.z.add_assign(rhs);
1031    }
1032}
1033
1034impl Add<DVec3> for f64 {
1035    type Output = DVec3;
1036    #[inline]
1037    fn add(self, rhs: DVec3) -> DVec3 {
1038        DVec3 {
1039            x: self.add(rhs.x),
1040            y: self.add(rhs.y),
1041            z: self.add(rhs.z),
1042        }
1043    }
1044}
1045
1046impl Sub<DVec3> for DVec3 {
1047    type Output = Self;
1048    #[inline]
1049    fn sub(self, rhs: Self) -> Self {
1050        Self {
1051            x: self.x.sub(rhs.x),
1052            y: self.y.sub(rhs.y),
1053            z: self.z.sub(rhs.z),
1054        }
1055    }
1056}
1057
1058impl SubAssign<DVec3> for DVec3 {
1059    #[inline]
1060    fn sub_assign(&mut self, rhs: DVec3) {
1061        self.x.sub_assign(rhs.x);
1062        self.y.sub_assign(rhs.y);
1063        self.z.sub_assign(rhs.z);
1064    }
1065}
1066
1067impl Sub<f64> for DVec3 {
1068    type Output = Self;
1069    #[inline]
1070    fn sub(self, rhs: f64) -> Self {
1071        Self {
1072            x: self.x.sub(rhs),
1073            y: self.y.sub(rhs),
1074            z: self.z.sub(rhs),
1075        }
1076    }
1077}
1078
1079impl SubAssign<f64> for DVec3 {
1080    #[inline]
1081    fn sub_assign(&mut self, rhs: f64) {
1082        self.x.sub_assign(rhs);
1083        self.y.sub_assign(rhs);
1084        self.z.sub_assign(rhs);
1085    }
1086}
1087
1088impl Sub<DVec3> for f64 {
1089    type Output = DVec3;
1090    #[inline]
1091    fn sub(self, rhs: DVec3) -> DVec3 {
1092        DVec3 {
1093            x: self.sub(rhs.x),
1094            y: self.sub(rhs.y),
1095            z: self.sub(rhs.z),
1096        }
1097    }
1098}
1099
1100impl Rem<DVec3> for DVec3 {
1101    type Output = Self;
1102    #[inline]
1103    fn rem(self, rhs: Self) -> Self {
1104        Self {
1105            x: self.x.rem(rhs.x),
1106            y: self.y.rem(rhs.y),
1107            z: self.z.rem(rhs.z),
1108        }
1109    }
1110}
1111
1112impl RemAssign<DVec3> for DVec3 {
1113    #[inline]
1114    fn rem_assign(&mut self, rhs: Self) {
1115        self.x.rem_assign(rhs.x);
1116        self.y.rem_assign(rhs.y);
1117        self.z.rem_assign(rhs.z);
1118    }
1119}
1120
1121impl Rem<f64> for DVec3 {
1122    type Output = Self;
1123    #[inline]
1124    fn rem(self, rhs: f64) -> Self {
1125        Self {
1126            x: self.x.rem(rhs),
1127            y: self.y.rem(rhs),
1128            z: self.z.rem(rhs),
1129        }
1130    }
1131}
1132
1133impl RemAssign<f64> for DVec3 {
1134    #[inline]
1135    fn rem_assign(&mut self, rhs: f64) {
1136        self.x.rem_assign(rhs);
1137        self.y.rem_assign(rhs);
1138        self.z.rem_assign(rhs);
1139    }
1140}
1141
1142impl Rem<DVec3> for f64 {
1143    type Output = DVec3;
1144    #[inline]
1145    fn rem(self, rhs: DVec3) -> DVec3 {
1146        DVec3 {
1147            x: self.rem(rhs.x),
1148            y: self.rem(rhs.y),
1149            z: self.rem(rhs.z),
1150        }
1151    }
1152}
1153
1154#[cfg(not(target_arch = "spirv"))]
1155impl AsRef<[f64; 3]> for DVec3 {
1156    #[inline]
1157    fn as_ref(&self) -> &[f64; 3] {
1158        unsafe { &*(self as *const DVec3 as *const [f64; 3]) }
1159    }
1160}
1161
1162#[cfg(not(target_arch = "spirv"))]
1163impl AsMut<[f64; 3]> for DVec3 {
1164    #[inline]
1165    fn as_mut(&mut self) -> &mut [f64; 3] {
1166        unsafe { &mut *(self as *mut DVec3 as *mut [f64; 3]) }
1167    }
1168}
1169
1170impl Sum for DVec3 {
1171    #[inline]
1172    fn sum<I>(iter: I) -> Self
1173    where
1174        I: Iterator<Item = Self>,
1175    {
1176        iter.fold(Self::ZERO, Self::add)
1177    }
1178}
1179
1180impl<'a> Sum<&'a Self> for DVec3 {
1181    #[inline]
1182    fn sum<I>(iter: I) -> Self
1183    where
1184        I: Iterator<Item = &'a Self>,
1185    {
1186        iter.fold(Self::ZERO, |a, &b| Self::add(a, b))
1187    }
1188}
1189
1190impl Product for DVec3 {
1191    #[inline]
1192    fn product<I>(iter: I) -> Self
1193    where
1194        I: Iterator<Item = Self>,
1195    {
1196        iter.fold(Self::ONE, Self::mul)
1197    }
1198}
1199
1200impl<'a> Product<&'a Self> for DVec3 {
1201    #[inline]
1202    fn product<I>(iter: I) -> Self
1203    where
1204        I: Iterator<Item = &'a Self>,
1205    {
1206        iter.fold(Self::ONE, |a, &b| Self::mul(a, b))
1207    }
1208}
1209
1210impl Neg for DVec3 {
1211    type Output = Self;
1212    #[inline]
1213    fn neg(self) -> Self {
1214        Self {
1215            x: self.x.neg(),
1216            y: self.y.neg(),
1217            z: self.z.neg(),
1218        }
1219    }
1220}
1221
1222impl Index<usize> for DVec3 {
1223    type Output = f64;
1224    #[inline]
1225    fn index(&self, index: usize) -> &Self::Output {
1226        match index {
1227            0 => &self.x,
1228            1 => &self.y,
1229            2 => &self.z,
1230            _ => panic!("index out of bounds"),
1231        }
1232    }
1233}
1234
1235impl IndexMut<usize> for DVec3 {
1236    #[inline]
1237    fn index_mut(&mut self, index: usize) -> &mut Self::Output {
1238        match index {
1239            0 => &mut self.x,
1240            1 => &mut self.y,
1241            2 => &mut self.z,
1242            _ => panic!("index out of bounds"),
1243        }
1244    }
1245}
1246
1247#[cfg(not(target_arch = "spirv"))]
1248impl fmt::Display for DVec3 {
1249    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1250        write!(f, "[{}, {}, {}]", self.x, self.y, self.z)
1251    }
1252}
1253
1254#[cfg(not(target_arch = "spirv"))]
1255impl fmt::Debug for DVec3 {
1256    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
1257        fmt.debug_tuple(stringify!(DVec3))
1258            .field(&self.x)
1259            .field(&self.y)
1260            .field(&self.z)
1261            .finish()
1262    }
1263}
1264
1265impl From<[f64; 3]> for DVec3 {
1266    #[inline]
1267    fn from(a: [f64; 3]) -> Self {
1268        Self::new(a[0], a[1], a[2])
1269    }
1270}
1271
1272impl From<DVec3> for [f64; 3] {
1273    #[inline]
1274    fn from(v: DVec3) -> Self {
1275        [v.x, v.y, v.z]
1276    }
1277}
1278
1279impl From<(f64, f64, f64)> for DVec3 {
1280    #[inline]
1281    fn from(t: (f64, f64, f64)) -> Self {
1282        Self::new(t.0, t.1, t.2)
1283    }
1284}
1285
1286impl From<DVec3> for (f64, f64, f64) {
1287    #[inline]
1288    fn from(v: DVec3) -> Self {
1289        (v.x, v.y, v.z)
1290    }
1291}
1292
1293impl From<(DVec2, f64)> for DVec3 {
1294    #[inline]
1295    fn from((v, z): (DVec2, f64)) -> Self {
1296        Self::new(v.x, v.y, z)
1297    }
1298}
1299
1300impl From<Vec3> for DVec3 {
1301    #[inline]
1302    fn from(v: Vec3) -> Self {
1303        Self::new(f64::from(v.x), f64::from(v.y), f64::from(v.z))
1304    }
1305}
1306
1307impl From<IVec3> for DVec3 {
1308    #[inline]
1309    fn from(v: IVec3) -> Self {
1310        Self::new(f64::from(v.x), f64::from(v.y), f64::from(v.z))
1311    }
1312}
1313
1314impl From<UVec3> for DVec3 {
1315    #[inline]
1316    fn from(v: UVec3) -> Self {
1317        Self::new(f64::from(v.x), f64::from(v.y), f64::from(v.z))
1318    }
1319}
glam/f64/dvec3.rs

glam/f64/
dvec3.rs
