Struct Vector 

#[repr(transparent)]
pub struct Vector<Repr, Space = ()>(pub Repr, _);

A generic vector type. Represents an element of a vector space or a module, a generalization of a vector space where the scalars can be integers (technically, the scalar type can be any ring-like type).

Type parameters

• Repr: Representation of the scalar components of the vector, for example an array or a SIMD vector.
• Space: The space that the vector is an element of. A tag type used to prevent mixing up vectors of different spaces and bases.

Examples

TODO examples

Tuple Fields

0: Repr

Implementations

impl<B> Vector<[f32; 2], Polar<B>>

pub fn r(&self) -> f32

Returns the radial component of self.

pub fn az(&self) -> Angle

Returns the azimuthal component of self.

pub fn to_cart(&self) -> Vec2<B>

Returns self converted to the equivalent Cartesian 2-vector.

Let the components of self be (r, az). Then the result (x, y) equals (r * cos(az), r * sin(az)).

+y
^     ^
| +r /
|   /
|  /_ +az
| /  \
+----------> +x

Examples

use retrofire_core::assert_approx_eq;
use retrofire_core::math::{vec2, polar, degs};

let vec2 = vec2::<f32, ()>;

assert_approx_eq!(polar(2.0, degs(0.0)).to_cart(), vec2(2.0, 0.0));
assert_approx_eq!(polar(3.0, degs(90.0)).to_cart(), vec2(0.0, 3.0));
assert_approx_eq!(polar(4.0, degs(-180.0)).to_cart(), vec2(-4.0, 0.0));

impl<B> Vector<[f32; 3], Spherical<B>>

pub fn r(&self) -> f32

Returns the radial component of self.

pub fn az(&self) -> Angle

Returns the azimuthal component of self.

pub fn alt(&self) -> Angle

Returns the altitude (elevation) component of self.

pub fn to_cart(&self) -> Vec3<B>

Returns self converted to the equivalent Cartesian 3-vector.

Examples

TODO examples

impl<B> Vector<[f32; 2], Real<2, B>>

pub fn to_polar(&self) -> PolarVec<B>

Returns self converted into the equivalent polar coordinate vector.

The r component of the result equals self.len().

The az component equals the angle between the vector and the x-axis in the range (-180°, 180°] such that positive y maps to positive az.

+y
^    ^
|   /
|  /_ +az
| /  \
+----------> +x

Examples

use retrofire_core::assert_approx_eq;
use retrofire_core::math::{vec2, degs};

let vec2 = vec2::<f32, ()>;

// A non-negative x and zero y maps to zero azimuth
assert_eq!(vec2(0.0, 0.0).to_polar().az(), degs(0.0));
assert_eq!(vec2(1.0, 0.0).to_polar().az(), degs(0.0));

// A zero x and positive y maps to right angle azimuth
assert_eq!(vec2(0.0, 1.0).to_polar().az(), degs(90.0));

// A zero x and negative y maps to negative right angle azimuth
assert_eq!(vec2(0.0, -1.0).to_polar().az(), degs(-90.0));

// A negative x and zero y maps to straight angle azimuth
assert_approx_eq!(vec2(-1.0, 0.0).to_polar().az(), degs(180.0));

impl<B> Vector<[f32; 3], Real<3, B>>

pub fn to_spherical(&self) -> SphericalVec<B>

Converts self into the equivalent spherical coordinate vector.

The r component of the result equals self.len().

The az component is the angle between self and the xy-plane in the range (-180°, 180°] such that positive z maps to positive az.

The alt component is the angle between self and the xz-plane in the range [-90°, 90°] such that positive y maps to positive alt.

Examples

use retrofire_core::math::{vec3, spherical, degs};

// The positive x-axis lies at zero azimuth and altitude
assert_eq!(
    vec3(2.0, 0.0, 0.0).to_spherical(),
    spherical::<()>(2.0, degs(0.0), degs(0.0))
);
// The positive y-axis lies at 90° altitude
assert_eq!(
    vec3(0.0, 2.0, 0.0).to_spherical(),
    spherical::<()>(2.0, degs(0.0), degs(90.0))
);
// The positive z axis lies at 90° azimuth
assert_eq!(
    vec3(0.0, 0.0, 2.0).to_spherical(),
    spherical::<()>(2.0, degs(90.0), degs(0.0))
);

impl<R, Sp> Vector<R, Sp>

pub const fn new(repr: R) -> Self

Returns a new vector with representation repr.

pub fn to<S>(self) -> Vector<R, S>

Returns a vector with value equal to self but in space S.

This method can be used to coerce a vector from one space to another in order to make types match. One use case is to cast a “generic” vector returned by one of the constructor functions to a more specific space.

pub fn to_pt(self) -> Point<R, Sp>

Returns the affine point equivalent to self.

impl<Sp, const N: usize> Vector<[f32; N], Sp>

pub fn len(&self) -> f32

Returns the length (magnitude) of self.

pub fn normalize(&self) -> Self

Returns self normalized to unit length.

Examples

use retrofire_core::assert_approx_eq;
use retrofire_core::math::{vec2, Vec2};

let normalized: Vec2 = vec2(3.0, 4.0).normalize();
assert_approx_eq!(normalized, vec2(0.6, 0.8), eps=1e-2);
assert_approx_eq!(normalized.len_sqr(), 1.0, eps=1e-2);

Panics

Panics in dev mode if self is a zero vector.

pub fn clamp(&self, min: &Self, max: &Self) -> Self

Returns self clamped component-wise to the given range.

In other words, for each component self[i], the result r has r[i] equal to self[i].clamp(min[i], max[i]).

Examples

use retrofire_core::math::vec::{vec3, Vec3, splat};
let v: Vec3 = vec3(0.5, 1.5, -2.0);

// Clamp to the unit cube
let clamped = v.clamp(&splat(-1.0), &splat(1.0));
assert_eq!(clamped, vec3(0.5, 1.0, -1.0));

pub fn is_finite(&self) -> bool

Returns true if every component of self is finite, false otherwise.

See f32::is_finite().

impl<Sc, Sp, const N: usize> Vector<[Sc; N], Sp>

where Self: Linear<Scalar = Sc>, Sc: Linear<Scalar = Sc> + Copy,

pub fn len_sqr(&self) -> Sc

Returns the length of self, squared.

This avoids taking the square root in cases it’s not needed and works with scalars for which a square root is not defined.

pub fn dot(&self, other: &Self) -> Sc

Returns the dot product of self and other.

pub fn scalar_project(&self, other: &Self) -> Sc

where Sc: Div<Sc, Output = Sc>,

Returns the scalar projection of self onto other (the length of the component of self parallel to other).

pub fn vector_project(&self, other: &Self) -> Self

where Sc: Div<Sc, Output = Sc>,

Returns the vector projection of self onto other (the vector component of self parallel to other).

           self
           ^
          /.
        /  .
      /    .
    /      .
  /       _.
 +-------'->-----> other
        result

pub fn reflect(self, other: Self) -> Self

where Sc: Div<Sc, Output = Sc>,

Reflects self across a line.

Examples

use retrofire_core::math::{Vec3, vec3};

let axis: Vec3 = vec3(1.0, 1.0, 0.0);
let v = vec3(3.0, 2.0, -1.0);

assert_eq!(v.reflect(axis), vec3(2.0, 3.0, 1.0));

impl<Sc: Copy, Sp, const N: usize> Vector<[Sc; N], Sp>

pub fn map<T>(self, f: impl FnMut(Sc) -> T) -> Vector<[T; N], Sp>

Returns a vector of the same dimension as self by applying f component-wise.

Examples

use retrofire_core::math::{Vec3i, vec3};

let v: Vec3i = vec3(1, 2, 3);
assert_eq!(v.map(|x| x as f32 + 0.5), vec3(1.5, 2.5, 3.5));

pub fn zip_map<T: Copy, U>( self, other: Vector<[T; N], Sp>, f: impl FnMut(Sc, T) -> U, ) -> Vector<[U; N], Sp>

Returns a vector of the same dimension as self by applying f component-wise to self and other.

Examples

use retrofire_core::math::vec3;

let a = vec3::<f32, ()>(1.0, 2.0, 3.0);
let b = vec3(4, 3, 2);
assert_eq!(a.zip_map(b, |x, exp| x.powi(exp)), vec3(1.0, 8.0, 9.0));

impl<R, Sc, B> Vector<R, Real<2, B>>

where R: Index<usize, Output = Sc>, Sc: Copy,

pub fn x(&self) -> Sc

Returns the x component of self.

pub fn y(&self) -> Sc

Returns the y component of self.

impl<B> Vector<[f32; 2], Real<2, B>>

pub const X: Self

Unit vector codirectional with the positive x-axis.

pub const Y: Self

Unit vector codirectional with the positive y-axis.

pub fn to_vec3(self) -> Vec3<B>

Converts self into a Vec3, with z set to 0.

pub fn perp(self) -> Self

Returns self rotated 90° counter-clockwise.

Examples

use retrofire_core::math::Vec2;

assert_eq!(<Vec2>::X.perp(), Vec2::Y);
assert_eq!(<Vec2>::Y.perp(), -Vec2::X);

pub fn perp_dot(self, other: Self) -> f32

Returns the “perpendicular dot product” of self and other.

This operation is also called the “2D cross product”. Like its 3D analog, it satisfies the following identity:

a^⟂ · b = |a| |b| sin θ,

where θ is the (signed) angle between a and b. In particular, the result is zero if a and b are parallel (or either is zero), positive if the angle from a to b is positive, and negative if the angle is negative:

      ^ b               ^ a
     /           ^ b   /        ^ a
    ^ a           \   /          \
   /               \ /            \
  O                 O              O-----> b

 a⟂·b = 0        a⟂·b > 0       a⟂·b < 0

Examples

use retrofire_core::math::{vec2, Vec2};
let v: Vec2 = vec2(2.0, 1.0);

assert_eq!(v.perp_dot(3.0 * v),  0.0, "v and 3*v are parallel");
assert_eq!(v.perp_dot(-v),       0.0, "v and -v are parallel");
assert!   (v.perp_dot(Vec2::X) < 0.0, "X is clockwise from v");
assert!   (v.perp_dot(Vec2::Y) > 0.0, "Y is counter-clockwise from v");

impl<R, Sc, B> Vector<R, Real<3, B>>

where R: Index<usize, Output = Sc>, Sc: Copy,

pub fn x(&self) -> Sc

Returns the x component of self.

pub fn y(&self) -> Sc

Returns the y component of self.

pub fn z(&self) -> Sc

Returns the z component of self.

pub fn cross(&self, other: &Self) -> Self

where Sc: Linear<Scalar = Sc>, [Sc; 3]: Into<Self>,

Returns the cross product of self with other.

The result is a vector orthogonal with both input vectors, its length proportional to the area of the parallelogram formed by the vectors. Specifically, the length is given by the identity:

    |𝗮 × 𝗯| = |𝗮| |𝗯| sin 𝜽

where |·| denotes the length of a vector and 𝜽 equals the angle between 𝗮 and 𝗯. Specifically, the result has unit length if 𝗮 and 𝗯 are orthogonal and |𝗮| = |𝗯| = 1. The cross product can be used to produce an orthonormal basis from any two non-parallel non-zero 3-vectors.

       ^
    r  |
    e  |
    s  |    other
    u  |     ^ - - - - - - - +
    l  |   /               /
    t  | /               /
       +--------------- > self

impl<B> Vector<[f32; 3], Real<3, B>>

pub const X: Self

Unit vector codirectional with the positive x-axis.

pub const Y: Self

Unit vector codirectional with the positive y-axis.

pub const Z: Self

Unit vector codirectional with the positive z-axis.

impl<R, Sc> Vector<R, Proj3>

where R: Index<usize, Output = Sc>, Sc: Copy,

pub fn x(&self) -> Sc

Returns the x component of self.

pub fn y(&self) -> Sc

Returns the y component of self.

pub fn z(&self) -> Sc

Returns the z component of self.

pub fn w(&self) -> Sc

Returns the w component of self.

impl Vector<[f32; 2], Real<2, Tex>>

pub const fn u(&self) -> f32

Returns the u (horizontal) component of self.

pub const fn v(&self) -> f32

Returns the v (vertical) component of self.

Trait Implementations

impl<R, Sp> Add<<Vector<R, Sp> as Affine>::Diff> for Vector<R, Sp>

where Self: Affine,

fn add(self, rhs: <Self as Affine>::Diff) -> Self

TODO

type Output = Vector<R, Sp>

The resulting type after applying the + operator.

impl<R, Sp> AddAssign<<Vector<R, Sp> as Affine>::Diff> for Vector<R, Sp>

where Self: Affine,

The vector += vector operator.

fn add_assign(&mut self, rhs: <Self as Affine>::Diff)

Performs the += operation.

impl<Sc, Sp, const DIM: usize> Affine for Vector<[Sc; DIM], Sp>

where Sc: Linear<Scalar = Sc> + Copy,

const DIM: usize = DIM

The dimension (number of components) of Self.

type Space = Sp

The space that Self is the element type of.

type Diff = Vector<[Sc; DIM], Sp>

The (signed) difference of two values of Self. Diff must have the same dimension as Self.

fn add(&self, other: &Self) -> Self

Adds diff to self component-wise.

fn sub(&self, other: &Self) -> Self

Subtracts other from self, returning the (signed) difference.

fn combine<S: Copy, const N: usize>( weights: &[S; N], points: &[Self; N], ) -> Self

where Self: Clone, Self::Diff: Linear<Scalar = S>,

Returns an affine combination of points.

impl<Src, Dest> Apply<Vector<[f32; 2], Real<2, Src>>> for Mat2x2<RealToReal<2, Src, Dest>>

fn apply(&self, v: &Vec2<Src>) -> Vec2<Dest>

Maps a real 2-vector from basis Src to basis Dst.

Computes the matrix–vector multiplication MV where v is interpreted as a column vector:

 Mv  =  ⎛ M00 M01 ⎞ ⎛ v0 ⎞  =  ⎛ v0' ⎞
        ⎝ M10 M11 ⎠ ⎝ v1 ⎠     ⎝ v1' ⎠

type Output = Vector<[f32; 2], Real<2, Dest>>

The transform codomain type.

impl<Src, Dest> Apply<Vector<[f32; 2], Real<2, Src>>> for Mat3x3<RealToReal<2, Src, Dest>>

fn apply(&self, v: &Vec2<Src>) -> Vec2<Dest>

Maps a real 2-vector from basis Src to basis Dst.

Computes the matrix–vector multiplication 𝝡𝘃 where 𝘃 is interpreted as a column vector with an implicit 𝘃₂ component with value 0:

        ⎛ M00 ·  ·  ⎞ ⎛ v0 ⎞     ⎛ v0' ⎞
 Mv  =  ⎜  ·  ·  ·  ⎟ ⎜ v1 ⎟  =  ⎜ v1' ⎟
        ⎝  ·  · M22 ⎠ ⎝  0 ⎠     ⎝  0  ⎠

type Output = Vector<[f32; 2], Real<2, Dest>>

The transform codomain type.

impl<Src, Dest> Apply<Vector<[f32; 3], Real<3, Src>>> for Mat3x3<RealToReal<3, Src, Dest>>

fn apply(&self, v: &Vec3<Src>) -> Vec3<Dest>

Maps a real 3-vector from basis Src to basis Dst.

Computes the matrix–vector multiplication Mv where v is interpreted as a column vector:

        ⎛ M00 ·  ·  ⎞ ⎛ v0 ⎞     ⎛ v0' ⎞
 Mv  =  ⎜  ·  ·  ·  ⎟ ⎜ v1 ⎟  =  ⎜ v1' ⎟
        ⎝  ·  · M22 ⎠ ⎝ v2 ⎠     ⎝ v2' ⎠

type Output = Vector<[f32; 3], Real<3, Dest>>

The transform codomain type.

impl<Src, Dst> Apply<Vector<[f32; 3], Real<3, Src>>> for Mat4x4<RealToReal<3, Src, Dst>>

fn apply(&self, v: &Vec3<Src>) -> Vec3<Dst>

Maps a real 3-vector from basis Src to basis Dst.

Computes the matrix–vector multiplication Mv where v is interpreted as a column vector with an implicit v₃ component with value 0:

        ⎛ M00 ·  ·  ·  ⎞ ⎛ v0 ⎞     ⎛ v0' ⎞
 Mv  =  ⎜  ·  ·  ·  ·  ⎟ ⎜ v1 ⎟  =  ⎜ v1' ⎟
        ⎜  ·  ·  ·  ·  ⎟ ⎜ v2 ⎟     ⎜ v2' ⎟
        ⎝  ·  ·  · M33 ⎠ ⎝  0 ⎠     ⎝  0  ⎠

type Output = Vector<[f32; 3], Real<3, Dst>>

The transform codomain type.

impl<Sc: ApproxEq, Sp, const N: usize> ApproxEq<Vector<[Sc; N], Sp>, Sc> for Vector<[Sc; N], Sp>

fn approx_eq_eps(&self, other: &Self, eps: &Sc) -> bool

Returns whether self and other are approximately equal, using the relative epsilon rel_eps.

fn relative_epsilon() -> Sc

Returns the default relative epsilon of type E.

fn approx_eq(&self, other: &Other) -> bool

Returns whether self and other are approximately equal. Uses the epsilon returned by Self::relative_epsilon.

impl<R: Clone, S> Clone for Vector<R, S>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<R: Debug, Sp: Debug + Default> Debug for Vector<R, Sp>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<R: Default, B, const DIM: usize> Default for Vector<R, Real<DIM, B>>

fn default() -> Self

Returns the “default value” for a type.

impl<R, Sp> Div<f32> for Vector<R, Sp>

where Self: Linear<Scalar = f32>,

fn div(self, rhs: f32) -> Self

TODO

type Output = Vector<R, Sp>

The resulting type after applying the / operator.

impl<R, Sp> DivAssign<f32> for Vector<R, Sp>

where Self: Linear<Scalar = f32>,

fn div_assign(&mut self, rhs: f32)

Performs the /= operation.

impl<R, Sp> From<R> for Vector<R, Sp>

fn from(repr: R) -> Self

Converts to this type from the input type.

impl<Sp, Sc: Clone, const DIM: usize> From<Sc> for Vector<[Sc; DIM], Sp>

fn from(scalar: Sc) -> Self

Returns a vector with all components equal to scalar.

This operation is also called “splat” or “broadcast”.

impl<B> From<Vector<[f32; 2], Polar<B>>> for Vec2<B>

Available on crate feature fp only.

fn from(p: PolarVec<B>) -> Self

Converts a polar vector into the equivalent Cartesian vector.

See PolarVec::to_cart for more information.

impl<B> From<Vector<[f32; 2], Real<2, B>>> for PolarVec<B>

Available on crate feature fp only.

fn from(v: Vec2<B>) -> Self

Converts a Cartesian 2-vector into the equivalent polar vector.

See Vec2::to_polar for more information.

impl<B> From<Vector<[f32; 3], Real<3, B>>> for SphericalVec<B>

Available on crate feature fp only.

fn from(v: Vec3<B>) -> Self

Converts a Cartesian 3-vector into the equivalent spherical vector.

See Vec3::to_spherical for more information.

impl<B> From<Vector<[f32; 3], Spherical<B>>> for Vec3<B>

Available on crate feature fp only.

fn from(v: SphericalVec<B>) -> Self

Converts a spherical coordinate vector to a Euclidean 3-vector.

See SphericalVec::to_cart for more information.

impl<R, Sp> Index<usize> for Vector<R, Sp>

where Self: Affine, R: Index<usize>,

fn index(&self, i: usize) -> &Self::Output

Returns the component of self with index i.

Panics

If i >= Self::DIM. Note that Self::DIM can be less than the number of elements in R.

type Output = <R as Index<usize>>::Output

The returned type after indexing.

impl<R, Sp> IndexMut<usize> for Vector<R, Sp>

where Self: Affine, R: IndexMut<usize>,

fn index_mut(&mut self, i: usize) -> &mut Self::Output

Returns a mutable reference to the component of self with index i.

Panics

If i >= Self::DIM. Note that Self::DIM can be less than the number of elements in R.

impl<Sc, Sp, const DIM: usize> Linear for Vector<[Sc; DIM], Sp>

where Sc: Linear<Scalar = Sc> + Copy,

fn zero() -> Self

Returns a vector with all-zero components, also called a zero vector.

type Scalar = Sc

The scalar type associated with Self.

fn mul(&self, scalar: Sc) -> Self

Multiplies all components of self by scalar.

fn neg(&self) -> Self

Returns the additive inverse of self.

impl<R, Sp> Mul<<Vector<R, Sp> as Linear>::Scalar> for Vector<R, Sp>

where Self: Linear,

fn mul(self, rhs: <Self as Linear>::Scalar) -> Self

TODO

type Output = Vector<R, Sp>

The resulting type after applying the * operator.

impl<R, Sp> Mul<Vector<R, Sp>> for f32

where Vector<R, Sp>: Linear<Scalar = f32>,

type Output = Vector<R, Sp>

The resulting type after applying the * operator.

fn mul(self, rhs: Vector<R, Sp>) -> Self::Output

Performs the * operation.

impl<R, Sp> Mul<Vector<R, Sp>> for i32

where Vector<R, Sp>: Linear<Scalar = i32>,

type Output = Vector<R, Sp>

The resulting type after applying the * operator.

fn mul(self, rhs: Vector<R, Sp>) -> Self::Output

Performs the * operation.

impl<R, Sp> Mul<Vector<R, Sp>> for u32

where Vector<R, Sp>: Linear<Scalar = u32>,

type Output = Vector<R, Sp>

The resulting type after applying the * operator.

fn mul(self, rhs: Vector<R, Sp>) -> Self::Output

Performs the * operation.

impl<R, Sp> MulAssign<<Vector<R, Sp> as Linear>::Scalar> for Vector<R, Sp>

where Self: Linear,

fn mul_assign(&mut self, rhs: <Self as Linear>::Scalar)

Performs the *= operation.

impl<R, Sp> Neg for Vector<R, Sp>

where Self: Linear,

The vector negation operator.

type Output = Vector<R, Sp>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<R: PartialEq, S> PartialEq for Vector<R, S>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<R, Sp> Sub<<Vector<R, Sp> as Affine>::Diff> for Vector<R, Sp>

where Self: Affine,

fn sub(self, rhs: <Self as Affine>::Diff) -> Self

TODO

type Output = Vector<R, Sp>

The resulting type after applying the - operator.

impl<R, Sp> SubAssign<<Vector<R, Sp> as Affine>::Diff> for Vector<R, Sp>

where Self: Affine,

The vector -= vector operator.

fn sub_assign(&mut self, rhs: <Self as Affine>::Diff)

Performs the -= operation.

impl<R, Sp> Sum for Vector<R, Sp>

where Self: Linear,

fn sum<I: Iterator<Item = Self>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by “summing up” the items.

impl<Sc, Sp, const N: usize> ZDiv for Vector<[Sc; N], Sp>

where Sc: ZDiv + Copy,

fn z_div(self, z: f32) -> Self

impl<R: Copy, S> Copy for Vector<R, S>

impl<R: Eq, S> Eq for Vector<R, S>