1 // Generated from vec.rs.tera template. Edit the template, not the generated file.
2 
3 use crate::{f32::math, wasm32::*, BVec3A, Vec2, Vec3, Vec4};
4 
5 #[cfg(not(target_arch = "spirv"))]
6 use core::fmt;
7 use core::iter::{Product, Sum};
8 use core::{f32, ops::*};
9 
10 use core::arch::wasm32::*;
11 
12 #[repr(C)]
13 union UnionCast {
14     a: [f32; 4],
15     v: Vec3A,
16 }
17 
18 /// Creates a 3-dimensional vector.
19 #[inline(always)]
20 #[must_use]
vec3a(x: f32, y: f32, z: f32) -> Vec3A21 pub const fn vec3a(x: f32, y: f32, z: f32) -> Vec3A {
22     Vec3A::new(x, y, z)
23 }
24 
25 /// A 3-dimensional vector.
26 ///
27 /// SIMD vector types are used for storage on supported platforms for better
28 /// performance than the [`Vec3`] type.
29 ///
30 /// It is possible to convert between [`Vec3`] and [`Vec3A`] types using [`From`]
31 /// or [`Into`] trait implementations.
32 ///
33 /// This type is 16 byte aligned.
34 #[derive(Clone, Copy)]
35 #[repr(transparent)]
36 pub struct Vec3A(pub(crate) v128);
37 
38 impl Vec3A {
39     /// All zeroes.
40     pub const ZERO: Self = Self::splat(0.0);
41 
42     /// All ones.
43     pub const ONE: Self = Self::splat(1.0);
44 
45     /// All negative ones.
46     pub const NEG_ONE: Self = Self::splat(-1.0);
47 
48     /// All `f32::MIN`.
49     pub const MIN: Self = Self::splat(f32::MIN);
50 
51     /// All `f32::MAX`.
52     pub const MAX: Self = Self::splat(f32::MAX);
53 
54     /// All `f32::NAN`.
55     pub const NAN: Self = Self::splat(f32::NAN);
56 
57     /// All `f32::INFINITY`.
58     pub const INFINITY: Self = Self::splat(f32::INFINITY);
59 
60     /// All `f32::NEG_INFINITY`.
61     pub const NEG_INFINITY: Self = Self::splat(f32::NEG_INFINITY);
62 
63     /// A unit vector pointing along the positive X axis.
64     pub const X: Self = Self::new(1.0, 0.0, 0.0);
65 
66     /// A unit vector pointing along the positive Y axis.
67     pub const Y: Self = Self::new(0.0, 1.0, 0.0);
68 
69     /// A unit vector pointing along the positive Z axis.
70     pub const Z: Self = Self::new(0.0, 0.0, 1.0);
71 
72     /// A unit vector pointing along the negative X axis.
73     pub const NEG_X: Self = Self::new(-1.0, 0.0, 0.0);
74 
75     /// A unit vector pointing along the negative Y axis.
76     pub const NEG_Y: Self = Self::new(0.0, -1.0, 0.0);
77 
78     /// A unit vector pointing along the negative Z axis.
79     pub const NEG_Z: Self = Self::new(0.0, 0.0, -1.0);
80 
81     /// The unit axes.
82     pub const AXES: [Self; 3] = [Self::X, Self::Y, Self::Z];
83 
84     /// Creates a new vector.
85     #[inline(always)]
86     #[must_use]
new(x: f32, y: f32, z: f32) -> Self87     pub const fn new(x: f32, y: f32, z: f32) -> Self {
88         Self(f32x4(x, y, z, z))
89     }
90 
91     /// Creates a vector with all elements set to `v`.
92     #[inline]
93     #[must_use]
splat(v: f32) -> Self94     pub const fn splat(v: f32) -> Self {
95         unsafe { UnionCast { a: [v; 4] }.v }
96     }
97 
98     /// Creates a vector from the elements in `if_true` and `if_false`, selecting which to use
99     /// for each element of `self`.
100     ///
101     /// A true element in the mask uses the corresponding element from `if_true`, and false
102     /// uses the element from `if_false`.
103     #[inline]
104     #[must_use]
select(mask: BVec3A, if_true: Self, if_false: Self) -> Self105     pub fn select(mask: BVec3A, if_true: Self, if_false: Self) -> Self {
106         Self(v128_bitselect(if_true.0, if_false.0, mask.0))
107     }
108 
109     /// Creates a new vector from an array.
110     #[inline]
111     #[must_use]
from_array(a: [f32; 3]) -> Self112     pub const fn from_array(a: [f32; 3]) -> Self {
113         Self::new(a[0], a[1], a[2])
114     }
115 
116     /// `[x, y, z]`
117     #[inline]
118     #[must_use]
to_array(&self) -> [f32; 3]119     pub const fn to_array(&self) -> [f32; 3] {
120         unsafe { *(self as *const Vec3A as *const [f32; 3]) }
121     }
122 
123     /// Creates a vector from the first 3 values in `slice`.
124     ///
125     /// # Panics
126     ///
127     /// Panics if `slice` is less than 3 elements long.
128     #[inline]
129     #[must_use]
from_slice(slice: &[f32]) -> Self130     pub const fn from_slice(slice: &[f32]) -> Self {
131         Self::new(slice[0], slice[1], slice[2])
132     }
133 
134     /// Writes the elements of `self` to the first 3 elements in `slice`.
135     ///
136     /// # Panics
137     ///
138     /// Panics if `slice` is less than 3 elements long.
139     #[inline]
write_to_slice(self, slice: &mut [f32])140     pub fn write_to_slice(self, slice: &mut [f32]) {
141         slice[0] = self.x;
142         slice[1] = self.y;
143         slice[2] = self.z;
144     }
145 
146     /// Internal method for creating a 3D vector from a 4D vector, discarding `w`.
147     #[allow(dead_code)]
148     #[inline]
149     #[must_use]
from_vec4(v: Vec4) -> Self150     pub(crate) fn from_vec4(v: Vec4) -> Self {
151         Self(v.0)
152     }
153 
154     /// Creates a 4D vector from `self` and the given `w` value.
155     #[inline]
156     #[must_use]
extend(self, w: f32) -> Vec4157     pub fn extend(self, w: f32) -> Vec4 {
158         Vec4::new(self.x, self.y, self.z, w)
159     }
160 
161     /// Creates a 2D vector from the `x` and `y` elements of `self`, discarding `z`.
162     ///
163     /// Truncation may also be performed by using [`self.xy()`][crate::swizzles::Vec3Swizzles::xy()].
164     #[inline]
165     #[must_use]
truncate(self) -> Vec2166     pub fn truncate(self) -> Vec2 {
167         use crate::swizzles::Vec3Swizzles;
168         self.xy()
169     }
170 
171     /// Computes the dot product of `self` and `rhs`.
172     #[inline]
173     #[must_use]
dot(self, rhs: Self) -> f32174     pub fn dot(self, rhs: Self) -> f32 {
175         dot3(self.0, rhs.0)
176     }
177 
178     /// Returns a vector where every component is the dot product of `self` and `rhs`.
179     #[inline]
180     #[must_use]
dot_into_vec(self, rhs: Self) -> Self181     pub fn dot_into_vec(self, rhs: Self) -> Self {
182         Self(dot3_into_v128(self.0, rhs.0))
183     }
184 
185     /// Computes the cross product of `self` and `rhs`.
186     #[inline]
187     #[must_use]
cross(self, rhs: Self) -> Self188     pub fn cross(self, rhs: Self) -> Self {
189         let lhszxy = i32x4_shuffle::<2, 0, 1, 1>(self.0, self.0);
190         let rhszxy = i32x4_shuffle::<2, 0, 1, 1>(rhs.0, rhs.0);
191         let lhszxy_rhs = f32x4_mul(lhszxy, rhs.0);
192         let rhszxy_lhs = f32x4_mul(rhszxy, self.0);
193         let sub = f32x4_sub(lhszxy_rhs, rhszxy_lhs);
194         Self(i32x4_shuffle::<2, 0, 1, 1>(sub, sub))
195     }
196 
197     /// Returns a vector containing the minimum values for each element of `self` and `rhs`.
198     ///
199     /// In other words this computes `[self.x.min(rhs.x), self.y.min(rhs.y), ..]`.
200     #[inline]
201     #[must_use]
min(self, rhs: Self) -> Self202     pub fn min(self, rhs: Self) -> Self {
203         Self(f32x4_pmin(self.0, rhs.0))
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]
max(self, rhs: Self) -> Self211     pub fn max(self, rhs: Self) -> Self {
212         Self(f32x4_pmax(self.0, rhs.0))
213     }
214 
215     /// Component-wise clamping of values, similar to [`f32::clamp`].
216     ///
217     /// Each element in `min` must be less-or-equal to the corresponding element in `max`.
218     ///
219     /// # Panics
220     ///
221     /// Will panic if `min` is greater than `max` when `glam_assert` is enabled.
222     #[inline]
223     #[must_use]
clamp(self, min: Self, max: Self) -> Self224     pub fn clamp(self, min: Self, max: Self) -> Self {
225         glam_assert!(min.cmple(max).all(), "clamp: expected min <= max");
226         self.max(min).min(max)
227     }
228 
229     /// Returns the horizontal minimum of `self`.
230     ///
231     /// In other words this computes `min(x, y, ..)`.
232     #[inline]
233     #[must_use]
min_element(self) -> f32234     pub fn min_element(self) -> f32 {
235         let v = self.0;
236         let v = f32x4_pmin(v, i32x4_shuffle::<2, 2, 1, 1>(v, v));
237         let v = f32x4_pmin(v, i32x4_shuffle::<1, 0, 0, 0>(v, v));
238         f32x4_extract_lane::<0>(v)
239     }
240 
241     /// Returns the horizontal maximum of `self`.
242     ///
243     /// In other words this computes `max(x, y, ..)`.
244     #[inline]
245     #[must_use]
max_element(self) -> f32246     pub fn max_element(self) -> f32 {
247         let v = self.0;
248         let v = f32x4_pmax(v, i32x4_shuffle::<2, 2, 0, 0>(v, v));
249         let v = f32x4_pmax(v, i32x4_shuffle::<1, 0, 0, 0>(v, v));
250         f32x4_extract_lane::<0>(v)
251     }
252 
253     /// Returns a vector mask containing the result of a `==` comparison for each element of
254     /// `self` and `rhs`.
255     ///
256     /// In other words, this computes `[self.x == rhs.x, self.y == rhs.y, ..]` for all
257     /// elements.
258     #[inline]
259     #[must_use]
cmpeq(self, rhs: Self) -> BVec3A260     pub fn cmpeq(self, rhs: Self) -> BVec3A {
261         BVec3A(f32x4_eq(self.0, rhs.0))
262     }
263 
264     /// Returns a vector mask containing the result of a `!=` comparison for each element of
265     /// `self` and `rhs`.
266     ///
267     /// In other words this computes `[self.x != rhs.x, self.y != rhs.y, ..]` for all
268     /// elements.
269     #[inline]
270     #[must_use]
cmpne(self, rhs: Self) -> BVec3A271     pub fn cmpne(self, rhs: Self) -> BVec3A {
272         BVec3A(f32x4_ne(self.0, rhs.0))
273     }
274 
275     /// Returns a vector mask containing the result of a `>=` comparison for each element of
276     /// `self` and `rhs`.
277     ///
278     /// In other words this computes `[self.x >= rhs.x, self.y >= rhs.y, ..]` for all
279     /// elements.
280     #[inline]
281     #[must_use]
cmpge(self, rhs: Self) -> BVec3A282     pub fn cmpge(self, rhs: Self) -> BVec3A {
283         BVec3A(f32x4_ge(self.0, rhs.0))
284     }
285 
286     /// Returns a vector mask containing the result of a `>` comparison for each element of
287     /// `self` and `rhs`.
288     ///
289     /// In other words this computes `[self.x > rhs.x, self.y > rhs.y, ..]` for all
290     /// elements.
291     #[inline]
292     #[must_use]
cmpgt(self, rhs: Self) -> BVec3A293     pub fn cmpgt(self, rhs: Self) -> BVec3A {
294         BVec3A(f32x4_gt(self.0, rhs.0))
295     }
296 
297     /// Returns a vector mask containing the result of a `<=` comparison for each element of
298     /// `self` and `rhs`.
299     ///
300     /// In other words this computes `[self.x <= rhs.x, self.y <= rhs.y, ..]` for all
301     /// elements.
302     #[inline]
303     #[must_use]
cmple(self, rhs: Self) -> BVec3A304     pub fn cmple(self, rhs: Self) -> BVec3A {
305         BVec3A(f32x4_le(self.0, rhs.0))
306     }
307 
308     /// Returns a vector mask containing the result of a `<` comparison for each element of
309     /// `self` and `rhs`.
310     ///
311     /// In other words this computes `[self.x < rhs.x, self.y < rhs.y, ..]` for all
312     /// elements.
313     #[inline]
314     #[must_use]
cmplt(self, rhs: Self) -> BVec3A315     pub fn cmplt(self, rhs: Self) -> BVec3A {
316         BVec3A(f32x4_lt(self.0, rhs.0))
317     }
318 
319     /// Returns a vector containing the absolute value of each element of `self`.
320     #[inline]
321     #[must_use]
abs(self) -> Self322     pub fn abs(self) -> Self {
323         Self(f32x4_abs(self.0))
324     }
325 
326     /// Returns a vector with elements representing the sign of `self`.
327     ///
328     /// - `1.0` if the number is positive, `+0.0` or `INFINITY`
329     /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY`
330     /// - `NAN` if the number is `NAN`
331     #[inline]
332     #[must_use]
signum(self) -> Self333     pub fn signum(self) -> Self {
334         unsafe {
335             let result = Self(v128_or(v128_and(self.0, Self::NEG_ONE.0), Self::ONE.0));
336             let mask = self.is_nan_mask();
337             Self::select(mask, self, result)
338         }
339     }
340 
341     /// Returns a vector with signs of `rhs` and the magnitudes of `self`.
342     #[inline]
343     #[must_use]
copysign(self, rhs: Self) -> Self344     pub fn copysign(self, rhs: Self) -> Self {
345         unsafe {
346             let mask = Self::splat(-0.0);
347             Self(v128_or(
348                 v128_and(rhs.0, mask.0),
349                 v128_andnot(self.0, mask.0),
350             ))
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]
is_negative_bitmask(self) -> u32360     pub fn is_negative_bitmask(self) -> u32 {
361         (u32x4_bitmask(self.0) & 0x7) as u32
362     }
363 
364     /// Returns `true` if, and only if, all elements are finite.  If any element is either
365     /// `NaN`, positive or negative infinity, this will return `false`.
366     #[inline]
367     #[must_use]
is_finite(self) -> bool368     pub fn is_finite(self) -> bool {
369         self.x.is_finite() && self.y.is_finite() && self.z.is_finite()
370     }
371 
372     /// Returns `true` if any elements are `NaN`.
373     #[inline]
374     #[must_use]
is_nan(self) -> bool375     pub fn is_nan(self) -> bool {
376         self.is_nan_mask().any()
377     }
378 
379     /// Performs `is_nan` on each element of self, returning a vector mask of the results.
380     ///
381     /// In other words, this computes `[x.is_nan(), y.is_nan(), z.is_nan(), w.is_nan()]`.
382     #[inline]
383     #[must_use]
is_nan_mask(self) -> BVec3A384     pub fn is_nan_mask(self) -> BVec3A {
385         BVec3A(f32x4_ne(self.0, self.0))
386     }
387 
388     /// Computes the length of `self`.
389     #[doc(alias = "magnitude")]
390     #[inline]
391     #[must_use]
length(self) -> f32392     pub fn length(self) -> f32 {
393         let dot = dot3_in_x(self.0, self.0);
394         f32x4_extract_lane::<0>(f32x4_sqrt(dot))
395     }
396 
397     /// Computes the squared length of `self`.
398     ///
399     /// This is faster than `length()` as it avoids a square root operation.
400     #[doc(alias = "magnitude2")]
401     #[inline]
402     #[must_use]
length_squared(self) -> f32403     pub fn length_squared(self) -> f32 {
404         self.dot(self)
405     }
406 
407     /// Computes `1.0 / length()`.
408     ///
409     /// For valid results, `self` must _not_ be of length zero.
410     #[inline]
411     #[must_use]
length_recip(self) -> f32412     pub fn length_recip(self) -> f32 {
413         let dot = dot3_in_x(self.0, self.0);
414         f32x4_extract_lane::<0>(f32x4_div(Self::ONE.0, f32x4_sqrt(dot)))
415     }
416 
417     /// Computes the Euclidean distance between two points in space.
418     #[inline]
419     #[must_use]
distance(self, rhs: Self) -> f32420     pub fn distance(self, rhs: Self) -> f32 {
421         (self - rhs).length()
422     }
423 
424     /// Compute the squared euclidean distance between two points in space.
425     #[inline]
426     #[must_use]
distance_squared(self, rhs: Self) -> f32427     pub fn distance_squared(self, rhs: Self) -> f32 {
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]
div_euclid(self, rhs: Self) -> Self434     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]: f32::rem_euclid
445     #[inline]
446     #[must_use]
rem_euclid(self, rhs: Self) -> Self447     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]
normalize(self) -> Self466     pub fn normalize(self) -> Self {
467         let length = f32x4_sqrt(dot3_into_v128(self.0, self.0));
468         #[allow(clippy::let_and_return)]
469         let normalized = Self(f32x4_div(self.0, length));
470         glam_assert!(normalized.is_finite());
471         normalized
472     }
473 
474     /// Returns `self` normalized to length 1.0 if possible, else returns `None`.
475     ///
476     /// In particular, if the input is zero (or very close to zero), or non-finite,
477     /// the result of this operation will be `None`.
478     ///
479     /// See also [`Self::normalize_or_zero()`].
480     #[inline]
481     #[must_use]
try_normalize(self) -> Option<Self>482     pub fn try_normalize(self) -> Option<Self> {
483         let rcp = self.length_recip();
484         if rcp.is_finite() && rcp > 0.0 {
485             Some(self * rcp)
486         } else {
487             None
488         }
489     }
490 
491     /// Returns `self` normalized to length 1.0 if possible, else returns zero.
492     ///
493     /// In particular, if the input is zero (or very close to zero), or non-finite,
494     /// the result of this operation will be zero.
495     ///
496     /// See also [`Self::try_normalize()`].
497     #[inline]
498     #[must_use]
normalize_or_zero(self) -> Self499     pub fn normalize_or_zero(self) -> Self {
500         let rcp = self.length_recip();
501         if rcp.is_finite() && rcp > 0.0 {
502             self * rcp
503         } else {
504             Self::ZERO
505         }
506     }
507 
508     /// Returns whether `self` is length `1.0` or not.
509     ///
510     /// Uses a precision threshold of `1e-6`.
511     #[inline]
512     #[must_use]
is_normalized(self) -> bool513     pub fn is_normalized(self) -> bool {
514         // TODO: do something with epsilon
515         math::abs(self.length_squared() - 1.0) <= 1e-4
516     }
517 
518     /// Returns the vector projection of `self` onto `rhs`.
519     ///
520     /// `rhs` must be of non-zero length.
521     ///
522     /// # Panics
523     ///
524     /// Will panic if `rhs` is zero length when `glam_assert` is enabled.
525     #[inline]
526     #[must_use]
project_onto(self, rhs: Self) -> Self527     pub fn project_onto(self, rhs: Self) -> Self {
528         let other_len_sq_rcp = rhs.dot(rhs).recip();
529         glam_assert!(other_len_sq_rcp.is_finite());
530         rhs * self.dot(rhs) * other_len_sq_rcp
531     }
532 
533     /// Returns the vector rejection of `self` from `rhs`.
534     ///
535     /// The vector rejection is the vector perpendicular to the projection of `self` onto
536     /// `rhs`, in rhs words the result of `self - self.project_onto(rhs)`.
537     ///
538     /// `rhs` must be of non-zero length.
539     ///
540     /// # Panics
541     ///
542     /// Will panic if `rhs` has a length of zero when `glam_assert` is enabled.
543     #[inline]
544     #[must_use]
reject_from(self, rhs: Self) -> Self545     pub fn reject_from(self, rhs: Self) -> Self {
546         self - self.project_onto(rhs)
547     }
548 
549     /// Returns the vector projection of `self` onto `rhs`.
550     ///
551     /// `rhs` must be normalized.
552     ///
553     /// # Panics
554     ///
555     /// Will panic if `rhs` is not normalized when `glam_assert` is enabled.
556     #[inline]
557     #[must_use]
project_onto_normalized(self, rhs: Self) -> Self558     pub fn project_onto_normalized(self, rhs: Self) -> Self {
559         glam_assert!(rhs.is_normalized());
560         rhs * self.dot(rhs)
561     }
562 
563     /// Returns the vector rejection of `self` from `rhs`.
564     ///
565     /// The vector rejection is the vector perpendicular to the projection of `self` onto
566     /// `rhs`, in rhs words the result of `self - self.project_onto(rhs)`.
567     ///
568     /// `rhs` must be normalized.
569     ///
570     /// # Panics
571     ///
572     /// Will panic if `rhs` is not normalized when `glam_assert` is enabled.
573     #[inline]
574     #[must_use]
reject_from_normalized(self, rhs: Self) -> Self575     pub fn reject_from_normalized(self, rhs: Self) -> Self {
576         self - self.project_onto_normalized(rhs)
577     }
578 
579     /// Returns a vector containing the nearest integer to a number for each element of `self`.
580     /// Round half-way cases away from 0.0.
581     #[inline]
582     #[must_use]
round(self) -> Self583     pub fn round(self) -> Self {
584         Self(f32x4_nearest(self.0))
585     }
586 
587     /// Returns a vector containing the largest integer less than or equal to a number for each
588     /// element of `self`.
589     #[inline]
590     #[must_use]
floor(self) -> Self591     pub fn floor(self) -> Self {
592         Self(f32x4_floor(self.0))
593     }
594 
595     /// Returns a vector containing the smallest integer greater than or equal to a number for
596     /// each element of `self`.
597     #[inline]
598     #[must_use]
ceil(self) -> Self599     pub fn ceil(self) -> Self {
600         Self(f32x4_ceil(self.0))
601     }
602 
603     /// Returns a vector containing the integer part each element of `self`. This means numbers are
604     /// always truncated towards zero.
605     #[inline]
606     #[must_use]
trunc(self) -> Self607     pub fn trunc(self) -> Self {
608         Self(f32x4_trunc(self.0))
609     }
610 
611     /// Returns a vector containing the fractional part of the vector, e.g. `self -
612     /// self.floor()`.
613     ///
614     /// Note that this is fast but not precise for large numbers.
615     #[inline]
616     #[must_use]
fract(self) -> Self617     pub fn fract(self) -> Self {
618         self - self.floor()
619     }
620 
621     /// Returns a vector containing `e^self` (the exponential function) for each element of
622     /// `self`.
623     #[inline]
624     #[must_use]
exp(self) -> Self625     pub fn exp(self) -> Self {
626         Self::new(math::exp(self.x), math::exp(self.y), math::exp(self.z))
627     }
628 
629     /// Returns a vector containing each element of `self` raised to the power of `n`.
630     #[inline]
631     #[must_use]
powf(self, n: f32) -> Self632     pub fn powf(self, n: f32) -> Self {
633         Self::new(
634             math::powf(self.x, n),
635             math::powf(self.y, n),
636             math::powf(self.z, n),
637         )
638     }
639 
640     /// Returns a vector containing the reciprocal `1.0/n` of each element of `self`.
641     #[inline]
642     #[must_use]
recip(self) -> Self643     pub fn recip(self) -> Self {
644         Self(f32x4_div(Self::ONE.0, self.0))
645     }
646 
647     /// Performs a linear interpolation between `self` and `rhs` based on the value `s`.
648     ///
649     /// When `s` is `0.0`, the result will be equal to `self`.  When `s` is `1.0`, the result
650     /// will be equal to `rhs`. When `s` is outside of range `[0, 1]`, the result is linearly
651     /// extrapolated.
652     #[doc(alias = "mix")]
653     #[inline]
654     #[must_use]
lerp(self, rhs: Self, s: f32) -> Self655     pub fn lerp(self, rhs: Self, s: f32) -> Self {
656         self + ((rhs - self) * s)
657     }
658 
659     /// Returns true if the absolute difference of all elements between `self` and `rhs` is
660     /// less than or equal to `max_abs_diff`.
661     ///
662     /// This can be used to compare if two vectors contain similar elements. It works best when
663     /// comparing with a known value. The `max_abs_diff` that should be used used depends on
664     /// the values being compared against.
665     ///
666     /// For more see
667     /// [comparing floating point numbers](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/).
668     #[inline]
669     #[must_use]
abs_diff_eq(self, rhs: Self, max_abs_diff: f32) -> bool670     pub fn abs_diff_eq(self, rhs: Self, max_abs_diff: f32) -> bool {
671         self.sub(rhs).abs().cmple(Self::splat(max_abs_diff)).all()
672     }
673 
674     /// Returns a vector with a length no less than `min` and no more than `max`
675     ///
676     /// # Panics
677     ///
678     /// Will panic if `min` is greater than `max` when `glam_assert` is enabled.
679     #[inline]
680     #[must_use]
clamp_length(self, min: f32, max: f32) -> Self681     pub fn clamp_length(self, min: f32, max: f32) -> Self {
682         glam_assert!(min <= max);
683         let length_sq = self.length_squared();
684         if length_sq < min * min {
685             min * (self / math::sqrt(length_sq))
686         } else if length_sq > max * max {
687             max * (self / math::sqrt(length_sq))
688         } else {
689             self
690         }
691     }
692 
693     /// Returns a vector with a length no more than `max`
694     #[inline]
695     #[must_use]
clamp_length_max(self, max: f32) -> Self696     pub fn clamp_length_max(self, max: f32) -> Self {
697         let length_sq = self.length_squared();
698         if length_sq > max * max {
699             max * (self / math::sqrt(length_sq))
700         } else {
701             self
702         }
703     }
704 
705     /// Returns a vector with a length no less than `min`
706     #[inline]
707     #[must_use]
clamp_length_min(self, min: f32) -> Self708     pub fn clamp_length_min(self, min: f32) -> Self {
709         let length_sq = self.length_squared();
710         if length_sq < min * min {
711             min * (self / math::sqrt(length_sq))
712         } else {
713             self
714         }
715     }
716 
717     /// Fused multiply-add. Computes `(self * a) + b` element-wise with only one rounding
718     /// error, yielding a more accurate result than an unfused multiply-add.
719     ///
720     /// Using `mul_add` *may* be more performant than an unfused multiply-add if the target
721     /// architecture has a dedicated fma CPU instruction. However, this is not always true,
722     /// and will be heavily dependant on designing algorithms with specific target hardware in
723     /// mind.
724     #[inline]
725     #[must_use]
mul_add(self, a: Self, b: Self) -> Self726     pub fn mul_add(self, a: Self, b: Self) -> Self {
727         Self::new(
728             math::mul_add(self.x, a.x, b.x),
729             math::mul_add(self.y, a.y, b.y),
730             math::mul_add(self.z, a.z, b.z),
731         )
732     }
733 
734     /// Returns the angle (in radians) between two vectors.
735     ///
736     /// The inputs do not need to be unit vectors however they must be non-zero.
737     #[inline]
738     #[must_use]
angle_between(self, rhs: Self) -> f32739     pub fn angle_between(self, rhs: Self) -> f32 {
740         math::acos_approx(
741             self.dot(rhs)
742                 .div(math::sqrt(self.length_squared().mul(rhs.length_squared()))),
743         )
744     }
745 
746     /// Returns some vector that is orthogonal to the given one.
747     ///
748     /// The input vector must be finite and non-zero.
749     ///
750     /// The output vector is not necessarily unit length. For that use
751     /// [`Self::any_orthonormal_vector()`] instead.
752     #[inline]
753     #[must_use]
any_orthogonal_vector(&self) -> Self754     pub fn any_orthogonal_vector(&self) -> Self {
755         // This can probably be optimized
756         if math::abs(self.x) > math::abs(self.y) {
757             Self::new(-self.z, 0.0, self.x) // self.cross(Self::Y)
758         } else {
759             Self::new(0.0, self.z, -self.y) // self.cross(Self::X)
760         }
761     }
762 
763     /// Returns any unit vector that is orthogonal to the given one.
764     ///
765     /// The input vector must be unit length.
766     ///
767     /// # Panics
768     ///
769     /// Will panic if `self` is not normalized when `glam_assert` is enabled.
770     #[inline]
771     #[must_use]
any_orthonormal_vector(&self) -> Self772     pub fn any_orthonormal_vector(&self) -> Self {
773         glam_assert!(self.is_normalized());
774         // From https://graphics.pixar.com/library/OrthonormalB/paper.pdf
775         let sign = math::signum(self.z);
776         let a = -1.0 / (sign + self.z);
777         let b = self.x * self.y * a;
778         Self::new(b, sign + self.y * self.y * a, -self.y)
779     }
780 
781     /// Given a unit vector return two other vectors that together form an orthonormal
782     /// basis. That is, all three vectors are orthogonal to each other and are normalized.
783     ///
784     /// # Panics
785     ///
786     /// Will panic if `self` is not normalized when `glam_assert` is enabled.
787     #[inline]
788     #[must_use]
any_orthonormal_pair(&self) -> (Self, Self)789     pub fn any_orthonormal_pair(&self) -> (Self, Self) {
790         glam_assert!(self.is_normalized());
791         // From https://graphics.pixar.com/library/OrthonormalB/paper.pdf
792         let sign = math::signum(self.z);
793         let a = -1.0 / (sign + self.z);
794         let b = self.x * self.y * a;
795         (
796             Self::new(1.0 + sign * self.x * self.x * a, sign * b, -sign * self.x),
797             Self::new(b, sign + self.y * self.y * a, -self.y),
798         )
799     }
800 
801     /// Casts all elements of `self` to `f64`.
802     #[inline]
803     #[must_use]
as_dvec3(&self) -> crate::DVec3804     pub fn as_dvec3(&self) -> crate::DVec3 {
805         crate::DVec3::new(self.x as f64, self.y as f64, self.z as f64)
806     }
807 
808     /// Casts all elements of `self` to `i16`.
809     #[inline]
810     #[must_use]
as_i16vec3(&self) -> crate::I16Vec3811     pub fn as_i16vec3(&self) -> crate::I16Vec3 {
812         crate::I16Vec3::new(self.x as i16, self.y as i16, self.z as i16)
813     }
814 
815     /// Casts all elements of `self` to `u16`.
816     #[inline]
817     #[must_use]
as_u16vec3(&self) -> crate::U16Vec3818     pub fn as_u16vec3(&self) -> crate::U16Vec3 {
819         crate::U16Vec3::new(self.x as u16, self.y as u16, self.z as u16)
820     }
821 
822     /// Casts all elements of `self` to `i32`.
823     #[inline]
824     #[must_use]
as_ivec3(&self) -> crate::IVec3825     pub fn as_ivec3(&self) -> crate::IVec3 {
826         crate::IVec3::new(self.x as i32, self.y as i32, self.z as i32)
827     }
828 
829     /// Casts all elements of `self` to `u32`.
830     #[inline]
831     #[must_use]
as_uvec3(&self) -> crate::UVec3832     pub fn as_uvec3(&self) -> crate::UVec3 {
833         crate::UVec3::new(self.x as u32, self.y as u32, self.z as u32)
834     }
835 
836     /// Casts all elements of `self` to `i64`.
837     #[inline]
838     #[must_use]
as_i64vec3(&self) -> crate::I64Vec3839     pub fn as_i64vec3(&self) -> crate::I64Vec3 {
840         crate::I64Vec3::new(self.x as i64, self.y as i64, self.z as i64)
841     }
842 
843     /// Casts all elements of `self` to `u64`.
844     #[inline]
845     #[must_use]
as_u64vec3(&self) -> crate::U64Vec3846     pub fn as_u64vec3(&self) -> crate::U64Vec3 {
847         crate::U64Vec3::new(self.x as u64, self.y as u64, self.z as u64)
848     }
849 }
850 
851 impl Default for Vec3A {
852     #[inline(always)]
default() -> Self853     fn default() -> Self {
854         Self::ZERO
855     }
856 }
857 
858 impl PartialEq for Vec3A {
859     #[inline]
eq(&self, rhs: &Self) -> bool860     fn eq(&self, rhs: &Self) -> bool {
861         self.cmpeq(*rhs).all()
862     }
863 }
864 
865 impl Div<Vec3A> for Vec3A {
866     type Output = Self;
867     #[inline]
div(self, rhs: Self) -> Self868     fn div(self, rhs: Self) -> Self {
869         Self(f32x4_div(self.0, rhs.0))
870     }
871 }
872 
873 impl DivAssign<Vec3A> for Vec3A {
874     #[inline]
div_assign(&mut self, rhs: Self)875     fn div_assign(&mut self, rhs: Self) {
876         self.0 = f32x4_div(self.0, rhs.0);
877     }
878 }
879 
880 impl Div<f32> for Vec3A {
881     type Output = Self;
882     #[inline]
div(self, rhs: f32) -> Self883     fn div(self, rhs: f32) -> Self {
884         Self(f32x4_div(self.0, f32x4_splat(rhs)))
885     }
886 }
887 
888 impl DivAssign<f32> for Vec3A {
889     #[inline]
div_assign(&mut self, rhs: f32)890     fn div_assign(&mut self, rhs: f32) {
891         self.0 = f32x4_div(self.0, f32x4_splat(rhs))
892     }
893 }
894 
895 impl Div<Vec3A> for f32 {
896     type Output = Vec3A;
897     #[inline]
div(self, rhs: Vec3A) -> Vec3A898     fn div(self, rhs: Vec3A) -> Vec3A {
899         Vec3A(f32x4_div(f32x4_splat(self), rhs.0))
900     }
901 }
902 
903 impl Mul<Vec3A> for Vec3A {
904     type Output = Self;
905     #[inline]
mul(self, rhs: Self) -> Self906     fn mul(self, rhs: Self) -> Self {
907         Self(f32x4_mul(self.0, rhs.0))
908     }
909 }
910 
911 impl MulAssign<Vec3A> for Vec3A {
912     #[inline]
mul_assign(&mut self, rhs: Self)913     fn mul_assign(&mut self, rhs: Self) {
914         self.0 = f32x4_mul(self.0, rhs.0);
915     }
916 }
917 
918 impl Mul<f32> for Vec3A {
919     type Output = Self;
920     #[inline]
mul(self, rhs: f32) -> Self921     fn mul(self, rhs: f32) -> Self {
922         Self(f32x4_mul(self.0, f32x4_splat(rhs)))
923     }
924 }
925 
926 impl MulAssign<f32> for Vec3A {
927     #[inline]
mul_assign(&mut self, rhs: f32)928     fn mul_assign(&mut self, rhs: f32) {
929         self.0 = f32x4_mul(self.0, f32x4_splat(rhs))
930     }
931 }
932 
933 impl Mul<Vec3A> for f32 {
934     type Output = Vec3A;
935     #[inline]
mul(self, rhs: Vec3A) -> Vec3A936     fn mul(self, rhs: Vec3A) -> Vec3A {
937         Vec3A(f32x4_mul(f32x4_splat(self), rhs.0))
938     }
939 }
940 
941 impl Add<Vec3A> for Vec3A {
942     type Output = Self;
943     #[inline]
add(self, rhs: Self) -> Self944     fn add(self, rhs: Self) -> Self {
945         Self(f32x4_add(self.0, rhs.0))
946     }
947 }
948 
949 impl AddAssign<Vec3A> for Vec3A {
950     #[inline]
add_assign(&mut self, rhs: Self)951     fn add_assign(&mut self, rhs: Self) {
952         self.0 = f32x4_add(self.0, rhs.0);
953     }
954 }
955 
956 impl Add<f32> for Vec3A {
957     type Output = Self;
958     #[inline]
add(self, rhs: f32) -> Self959     fn add(self, rhs: f32) -> Self {
960         Self(f32x4_add(self.0, f32x4_splat(rhs)))
961     }
962 }
963 
964 impl AddAssign<f32> for Vec3A {
965     #[inline]
add_assign(&mut self, rhs: f32)966     fn add_assign(&mut self, rhs: f32) {
967         self.0 = f32x4_add(self.0, f32x4_splat(rhs));
968     }
969 }
970 
971 impl Add<Vec3A> for f32 {
972     type Output = Vec3A;
973     #[inline]
add(self, rhs: Vec3A) -> Vec3A974     fn add(self, rhs: Vec3A) -> Vec3A {
975         Vec3A(f32x4_add(f32x4_splat(self), rhs.0))
976     }
977 }
978 
979 impl Sub<Vec3A> for Vec3A {
980     type Output = Self;
981     #[inline]
sub(self, rhs: Self) -> Self982     fn sub(self, rhs: Self) -> Self {
983         Self(f32x4_sub(self.0, rhs.0))
984     }
985 }
986 
987 impl SubAssign<Vec3A> for Vec3A {
988     #[inline]
sub_assign(&mut self, rhs: Vec3A)989     fn sub_assign(&mut self, rhs: Vec3A) {
990         self.0 = f32x4_sub(self.0, rhs.0);
991     }
992 }
993 
994 impl Sub<f32> for Vec3A {
995     type Output = Self;
996     #[inline]
sub(self, rhs: f32) -> Self997     fn sub(self, rhs: f32) -> Self {
998         Self(f32x4_sub(self.0, f32x4_splat(rhs)))
999     }
1000 }
1001 
1002 impl SubAssign<f32> for Vec3A {
1003     #[inline]
sub_assign(&mut self, rhs: f32)1004     fn sub_assign(&mut self, rhs: f32) {
1005         self.0 = f32x4_sub(self.0, f32x4_splat(rhs))
1006     }
1007 }
1008 
1009 impl Sub<Vec3A> for f32 {
1010     type Output = Vec3A;
1011     #[inline]
sub(self, rhs: Vec3A) -> Vec3A1012     fn sub(self, rhs: Vec3A) -> Vec3A {
1013         Vec3A(f32x4_sub(f32x4_splat(self), rhs.0))
1014     }
1015 }
1016 
1017 impl Rem<Vec3A> for Vec3A {
1018     type Output = Self;
1019     #[inline]
rem(self, rhs: Self) -> Self1020     fn rem(self, rhs: Self) -> Self {
1021         let n = f32x4_floor(f32x4_div(self.0, rhs.0));
1022         Self(f32x4_sub(self.0, f32x4_mul(n, rhs.0)))
1023     }
1024 }
1025 
1026 impl RemAssign<Vec3A> for Vec3A {
1027     #[inline]
rem_assign(&mut self, rhs: Self)1028     fn rem_assign(&mut self, rhs: Self) {
1029         *self = self.rem(rhs);
1030     }
1031 }
1032 
1033 impl Rem<f32> for Vec3A {
1034     type Output = Self;
1035     #[inline]
rem(self, rhs: f32) -> Self1036     fn rem(self, rhs: f32) -> Self {
1037         self.rem(Self::splat(rhs))
1038     }
1039 }
1040 
1041 impl RemAssign<f32> for Vec3A {
1042     #[inline]
rem_assign(&mut self, rhs: f32)1043     fn rem_assign(&mut self, rhs: f32) {
1044         *self = self.rem(Self::splat(rhs));
1045     }
1046 }
1047 
1048 impl Rem<Vec3A> for f32 {
1049     type Output = Vec3A;
1050     #[inline]
rem(self, rhs: Vec3A) -> Vec3A1051     fn rem(self, rhs: Vec3A) -> Vec3A {
1052         Vec3A::splat(self).rem(rhs)
1053     }
1054 }
1055 
1056 #[cfg(not(target_arch = "spirv"))]
1057 impl AsRef<[f32; 3]> for Vec3A {
1058     #[inline]
as_ref(&self) -> &[f32; 3]1059     fn as_ref(&self) -> &[f32; 3] {
1060         unsafe { &*(self as *const Vec3A as *const [f32; 3]) }
1061     }
1062 }
1063 
1064 #[cfg(not(target_arch = "spirv"))]
1065 impl AsMut<[f32; 3]> for Vec3A {
1066     #[inline]
as_mut(&mut self) -> &mut [f32; 3]1067     fn as_mut(&mut self) -> &mut [f32; 3] {
1068         unsafe { &mut *(self as *mut Vec3A as *mut [f32; 3]) }
1069     }
1070 }
1071 
1072 impl Sum for Vec3A {
1073     #[inline]
sum<I>(iter: I) -> Self where I: Iterator<Item = Self>,1074     fn sum<I>(iter: I) -> Self
1075     where
1076         I: Iterator<Item = Self>,
1077     {
1078         iter.fold(Self::ZERO, Self::add)
1079     }
1080 }
1081 
1082 impl<'a> Sum<&'a Self> for Vec3A {
1083     #[inline]
sum<I>(iter: I) -> Self where I: Iterator<Item = &'a Self>,1084     fn sum<I>(iter: I) -> Self
1085     where
1086         I: Iterator<Item = &'a Self>,
1087     {
1088         iter.fold(Self::ZERO, |a, &b| Self::add(a, b))
1089     }
1090 }
1091 
1092 impl Product for Vec3A {
1093     #[inline]
product<I>(iter: I) -> Self where I: Iterator<Item = Self>,1094     fn product<I>(iter: I) -> Self
1095     where
1096         I: Iterator<Item = Self>,
1097     {
1098         iter.fold(Self::ONE, Self::mul)
1099     }
1100 }
1101 
1102 impl<'a> Product<&'a Self> for Vec3A {
1103     #[inline]
product<I>(iter: I) -> Self where I: Iterator<Item = &'a Self>,1104     fn product<I>(iter: I) -> Self
1105     where
1106         I: Iterator<Item = &'a Self>,
1107     {
1108         iter.fold(Self::ONE, |a, &b| Self::mul(a, b))
1109     }
1110 }
1111 
1112 impl Neg for Vec3A {
1113     type Output = Self;
1114     #[inline]
neg(self) -> Self1115     fn neg(self) -> Self {
1116         Self(f32x4_neg(self.0))
1117     }
1118 }
1119 
1120 impl Index<usize> for Vec3A {
1121     type Output = f32;
1122     #[inline]
index(&self, index: usize) -> &Self::Output1123     fn index(&self, index: usize) -> &Self::Output {
1124         match index {
1125             0 => &self.x,
1126             1 => &self.y,
1127             2 => &self.z,
1128             _ => panic!("index out of bounds"),
1129         }
1130     }
1131 }
1132 
1133 impl IndexMut<usize> for Vec3A {
1134     #[inline]
index_mut(&mut self, index: usize) -> &mut Self::Output1135     fn index_mut(&mut self, index: usize) -> &mut Self::Output {
1136         match index {
1137             0 => &mut self.x,
1138             1 => &mut self.y,
1139             2 => &mut self.z,
1140             _ => panic!("index out of bounds"),
1141         }
1142     }
1143 }
1144 
1145 #[cfg(not(target_arch = "spirv"))]
1146 impl fmt::Display for Vec3A {
fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result1147     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1148         write!(f, "[{}, {}, {}]", self.x, self.y, self.z)
1149     }
1150 }
1151 
1152 #[cfg(not(target_arch = "spirv"))]
1153 impl fmt::Debug for Vec3A {
fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result1154     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
1155         fmt.debug_tuple(stringify!(Vec3A))
1156             .field(&self.x)
1157             .field(&self.y)
1158             .field(&self.z)
1159             .finish()
1160     }
1161 }
1162 
1163 impl From<Vec3A> for v128 {
1164     #[inline]
from(t: Vec3A) -> Self1165     fn from(t: Vec3A) -> Self {
1166         t.0
1167     }
1168 }
1169 
1170 impl From<v128> for Vec3A {
1171     #[inline]
from(t: v128) -> Self1172     fn from(t: v128) -> Self {
1173         Self(t)
1174     }
1175 }
1176 
1177 impl From<[f32; 3]> for Vec3A {
1178     #[inline]
from(a: [f32; 3]) -> Self1179     fn from(a: [f32; 3]) -> Self {
1180         Self::new(a[0], a[1], a[2])
1181     }
1182 }
1183 
1184 impl From<Vec3A> for [f32; 3] {
1185     #[inline]
from(v: Vec3A) -> Self1186     fn from(v: Vec3A) -> Self {
1187         unsafe { *(&v.0 as *const v128 as *const Self) }
1188     }
1189 }
1190 
1191 impl From<(f32, f32, f32)> for Vec3A {
1192     #[inline]
from(t: (f32, f32, f32)) -> Self1193     fn from(t: (f32, f32, f32)) -> Self {
1194         Self::new(t.0, t.1, t.2)
1195     }
1196 }
1197 
1198 impl From<Vec3A> for (f32, f32, f32) {
1199     #[inline]
from(v: Vec3A) -> Self1200     fn from(v: Vec3A) -> Self {
1201         unsafe { *(&v.0 as *const v128 as *const Self) }
1202     }
1203 }
1204 
1205 impl From<Vec3> for Vec3A {
1206     #[inline]
from(v: Vec3) -> Self1207     fn from(v: Vec3) -> Self {
1208         Self::new(v.x, v.y, v.z)
1209     }
1210 }
1211 
1212 impl From<Vec4> for Vec3A {
1213     /// Creates a [`Vec3A`] from the `x`, `y` and `z` elements of `self` discarding `w`.
1214     ///
1215     /// On architectures where SIMD is supported such as SSE2 on `x86_64` this conversion is a noop.
1216     #[inline]
from(v: Vec4) -> Self1217     fn from(v: Vec4) -> Self {
1218         Self(v.0)
1219     }
1220 }
1221 
1222 impl From<Vec3A> for Vec3 {
1223     #[inline]
from(v: Vec3A) -> Self1224     fn from(v: Vec3A) -> Self {
1225         unsafe { *(&v.0 as *const v128 as *const Self) }
1226     }
1227 }
1228 
1229 impl From<(Vec2, f32)> for Vec3A {
1230     #[inline]
from((v, z): (Vec2, f32)) -> Self1231     fn from((v, z): (Vec2, f32)) -> Self {
1232         Self::new(v.x, v.y, z)
1233     }
1234 }
1235 
1236 impl Deref for Vec3A {
1237     type Target = crate::deref::Vec3<f32>;
1238     #[inline]
deref(&self) -> &Self::Target1239     fn deref(&self) -> &Self::Target {
1240         unsafe { &*(self as *const Self).cast() }
1241     }
1242 }
1243 
1244 impl DerefMut for Vec3A {
1245     #[inline]
deref_mut(&mut self) -> &mut Self::Target1246     fn deref_mut(&mut self) -> &mut Self::Target {
1247         unsafe { &mut *(self as *mut Self).cast() }
1248     }
1249 }
1250