Struct Vector3

pub struct Vector3 { /* private fields */ }

A 3D vector that holds an x-coordinate, y-coordinate, and z-coordinate

Implementations

impl Vector3

Constructors

pub fn new(x: f32, y: f32, z: f32) -> Self

Creates a new 3D vector

• x: The x coordinate of the vector
• y: The y coordinate of the vector
• z: The z coordinate of the vector

Returns: Returns a new 3D vector

Examples

let vector = Vector3::new(1.2, 3.45, 6.789);
assert_eq!(1.2, vector.x());
assert_eq!(3.45, vector.y());
assert_eq!(6.789, vector.z());

pub fn from_vector2(vector: Vector2) -> Self

Creates a new 3D vector from a 2D vector

• vector: The 2D vector to convert from

Returns: Returns a converted 3D vector

Examples

let vector2 = Vector2::new(1.2, 3.45);
let vector3 = Vector3::from_vector2(vector2);
assert_eq!(1.2, vector3.x());
assert_eq!(3.45, vector3.y());
assert_eq!(0.0, vector3.z());

pub fn zero() -> Self

Creates an empty 3D vector

Returns: Returns an empty 3D vector

Examples

let vector = Vector3::zero();
assert_eq!(0.0, vector.x());
assert_eq!(0.0, vector.y());
assert_eq!(0.0, vector.z());

pub fn left() -> Self

Creates a 3D unit vector that’s pointing to the lefT: (-1, 0, 0)

Returns: Returns a 3D unit vector that’s pointing to the left

Examples

let vector = Vector3::left();
assert_eq!(-1.0, vector.x());
assert_eq!(0.0, vector.y());
assert_eq!(0.0, vector.z());

pub fn right() -> Self

Creates a 3D unit vector that’s pointing to the right: (1, 0, 0)

Returns: Returns a 3D unit vector that’s pointing to the left

Examples

let vector = Vector3::right();
assert_eq!(1.0, vector.x());
assert_eq!(0.0, vector.y());
assert_eq!(0.0, vector.z());

pub fn up() -> Self

Creates a 3D unit vector that’s pointing up: (0, 1, 0)

Returns: Returns a 3D unit vector that’s pointing up

Examples

let vector = Vector3::up();
assert_eq!(0.0, vector.x());
assert_eq!(1.0, vector.y());
assert_eq!(0.0, vector.z());

pub fn down() -> Self

Creates a 3D unit vector that’s pointing down: (0, -1, 0)

Returns: Returns a 3D unit vector that’s pointing down

Examples

let vector = Vector3::down();
assert_eq!(0.0, vector.x());
assert_eq!(-1.0, vector.y());
assert_eq!(0.0, vector.z());

pub fn forward() -> Self

Creates a 3D unit vector that’s pointing forward: (0, 0, 1)

Returns: Returns a 3D unit vector that’s pointing forward

Examples

let vector = Vector3::forward();
assert_eq!(0.0, vector.x());
assert_eq!(0.0, vector.y());
assert_eq!(1.0, vector.z());

pub fn back() -> Self

Creates a 3D unit vector that’s pointing backwards: (0, 0, -1)

Returns: Returns a 3D unit vector that’s pointing backwards

Examples

let vector = Vector3::back();
assert_eq!(0.0, vector.x());
assert_eq!(0.0, vector.y());
assert_eq!(-1.0, vector.z());

pub fn one() -> Self

Creates a 3D vector that contains 1 in all it’s components: (1, 1, 1)

Returns: Returns a 3D vector that contains 1 in all it’s components

Examples

let vector = Vector3::one();
assert_eq!(1.0, vector.x());
assert_eq!(1.0, vector.y());
assert_eq!(1.0, vector.z());

pub fn from_angles(theta: f32, phi: f32) -> Self

Creates a 3D vector from two given angles

• theta: The first angle to create the vector from
• phi: The second angle to create the vector from

Returns: Returns a 3D vector from the two angles

Examples

let vector = Vector3::from_angles(Math::PI_OVER_4, Math::PI_OVER_4);
let expected = Vector3::new(0.5, 0.5, 0.707106781187);
assert_range!(expected.x(), vector.x());
assert_range!(expected.y(), vector.y());
assert_range!(expected.z(), vector.z());
let vector = Vector3::from_angles(-2.21656815003, 2.21656815003);
let expected = Vector3::new(0.3621814, 0.4806309, 0.7986355);
assert_range!(expected.x(), vector.x());
assert_range!(expected.y(), vector.y());
assert_range!(expected.z(), vector.z());

pub fn from_angles_deg(theta: f32, phi: f32) -> Self

Creates a 3D vector from two given angles

• theta: The first angle to create the vector from
• phi: The second angle to create the vector from

Returns: Returns a 3D vector from the two angles

Examples

let vector = Vector3::from_angles_deg(45.0, 45.0);
let expected = Vector3::new(0.5, 0.5, 0.707106781187);
assert_range!(expected.x(), vector.x());
assert_range!(expected.y(), vector.y());
assert_range!(expected.z(), vector.z());
let vector = Vector3::from_angles_deg(-127.0, 127.0);
let expected = Vector3::new(0.3621814, 0.4806309, 0.7986355);
assert_range!(expected.x(), vector.x());
assert_range!(expected.y(), vector.y());
assert_range!(expected.z(), vector.z());

impl Vector3

Properties

pub fn x(&self) -> f32

Gets the x coordinate of the vector

Returns: Returns the x coordinate of the vector

pub fn set_x(&mut self, value: f32)

Sets the x coordinate of the vector

• value: The value to set the x coordinate of the vector

pub fn y(&self) -> f32

Gets the y coordinate of the vector

Returns: Returns the y coordinate of the vector

pub fn set_y(&mut self, value: f32)

Sets the y coordinate of the vector

• value: The value to set the y coordinate of the vector

Examples

let mut a = Vector3::up();
a.set_y(6.0);
assert_eq!(6.0, a.y());

pub fn z(&self) -> f32

Gets the z coordinate of the vector

Returns: Returns the z coordinate of the vector

pub fn set_z(&mut self, value: f32)

Sets the z coordinate of the vector

• value: The value to set the z coordinate of the vector

pub fn magnitude(&self) -> f32

Gets the magnitude of the vector. This returns the length of the vector

Returns: Returns the magnitude of the vector

Examples

let a = Vector3::new(-1.0, 2.0, -2.0);
assert_eq!(3.0, a.magnitude());

pub fn square_magnitude(&self) -> f32

Gets the magnitude squared, avoiding the use of a square root

Returns: Returns the magnitude of the vector squared

Examples

let a = Vector3::new(-1.0, 2.0, 2.0);
assert_eq!(9.0, a.square_magnitude());

impl Vector3

Public Methods

pub fn angle_between(self, rhs: Vector3) -> f32

Gets the angle between the two vectors in radians

• rhs: The other vector to get the angle from

Returns: Returns the angle between the two vectors in radians

Examples

let a = Vector3::new(0.25, -0.5, 1.25);
let b = Vector3::new(2.0, 0.5, -1.0);
assert_range!(1.89518322157, a.angle_between(b));

pub fn angle_between_deg(self, rhs: Vector3) -> f32

Gets the angle between the two vectors in degrees

• rhs: The other vector to get the angle from

Returns: Returns the angle between the two vectors in degrees

Examples

let a = Vector3::new(0.25, -0.5, 1.25);
let b = Vector3::new(2.0, 0.5, -1.0);
assert_range!(108.586, a.angle_between_deg(b), 0.01);

pub fn cross(self, rhs: Vector3) -> Self

Performs a cross product and creates a 3D vector that is orthogonal to both vectors provided

• rhs: The other vector to cross product

Returns: Returns the vector that is orthogonal to both vectors

Examples

let a = Vector3::new(1.0, 2.0, 3.0);
let b = Vector3::new(4.0, 5.0, 6.0);
let expected = Vector3::new(-3.0, 6.0, -3.0);
assert_eq!(expected, a.cross(b));
assert_eq!(Vector3::zero(), a.cross(a));

pub fn distance(self, rhs: Vector3) -> f32

Gets the distance between the two vectors

• rhs: The other vector to get the distance between

Returns: Returns the distance between the two vectors

Examples

let a = Vector3::new(0.25, -0.5, 1.25);
let b = Vector3::new(2.0, 0.5, -1.0);
assert_eq!(3.0207615, a.distance(b));

pub fn dot(self, rhs: Vector3) -> f32

Gets the dot product of between the two vectors. It can be used to determine the angle between two vectors.

• rhs: The other vector to dot product with

Returns: Returns the dot product

Remarks

Using two unit vectors, the maximum range of numbers go from -1 to 1. It scales with the magnitude of both vectors (multiplying them together a.magnitude() * b.magnitude())

Examples

let a = Vector3::one();
let b = Vector3::new(0.25, 1.1, -4.1);
let dot = a.dot(b);
assert_eq!(-2.75, dot);

Note that if the angle is 90 degrees (PI / 2) then it’s going to return 0

let a = Vector3::right();
let b = 2.0 * Vector3::up();
let dot = a.dot(b);
assert_eq!(0.0, dot);

Where as, if the angle is 0 degrees or 180 degrees (PI) then it’s going to return 1 and -1 respectively; given that the two vectors are unit vectors

let a = Vector3::right();
let b = Vector3::left();
let dot_one = a.dot(a);
let dot_negative_one = a.dot(b);
assert_eq!(1.0, dot_one);
assert_eq!(-1.0, dot_negative_one);

pub fn lerp(self, rhs: Vector3, t: f32) -> Self

Linearly interpolates between the this and the other vector

• rhs: The other vector to end from
• t: The ratio value to interpolate between both vectors. Clamped between 0.0 and 1.0

Returns: Returns the interpolated vector

Examples

let a = Vector3::new(0.0, 4.0, -10.0);
let b = Vector3::new(1.0, 10.0, -4.0);
let expected = Vector3::new(0.7, 8.2, -5.8);
assert_eq!(expected, a.lerp(b, 0.7));

pub fn lerp_unclamped(self, rhs: Vector3, t: f32) -> Self

Linearly interpolates between the this and the other vector (not clamped)

• rhs: The other vector to end from
• t: The ratio value to interpolate between both vectors

Returns: Returns the interpolated vector

Examples

let a = Vector3::new(0.0, 4.0, -10.0);
let b = Vector3::new(1.0, 10.0, -4.0);
let expected = Vector3::new(0.7, 8.2, -5.8);
assert_eq!(expected, a.lerp_unclamped(b, 0.7));

pub fn move_towards(self, target: Vector3, delta: f32) -> Self

Moves this vector towards the target vector, it will never move past the target

• target: The target vector to move towards
• delta: The delta distance to try and move with, defines the maximum distance moved

Returns: Returns the vector that is closer towards the target

Examples

let a = Vector3::new(0.25, -0.5, 1.25);
let b = Vector3::new(2.0, 0.5, -1.0);
let expected = Vector3::new(0.3658648, -0.4337915, 1.101031);
assert_eq!(expected, a.move_towards(b, 0.2));
assert_eq!(b, a.move_towards(b, 20.0));

pub fn normalize(self) -> Self

Normalizes the vector

Returns: Returns the unit vector version of this vector

Examples

let vector = Vector3::one().normalize();
assert_range!(0.5773503, vector.x());
assert_range!(0.5773503, vector.y());
assert_range!(0.5773503, vector.z());
let vector = Vector3::new(-0.1, 1.0, -2.4).normalize();
assert_range!(-0.03843312, vector.x());
assert_range!(0.3843312, vector.y());
assert_range!(-0.9223949, vector.z());

pub fn project(self, rhs: Vector3) -> Self

Projects this vector onto the given vector

• rhs: The vector to project onto

Returns: Returns the projected vector

Examples

let a = Vector3::new(1.0, 2.0, 3.0);
let b = Vector3::new(4.0, 5.0, 6.0);
let expected = Vector3::new(1.662337662337662, 2.077922077922078, 2.493506493506494);
assert_eq!(expected, a.project(b));

pub fn reject(self, rhs: Vector3) -> Self

Rejects this vector from the given vector

• rhs: The vector to reject from

Returns: Returns the rejected vector

Examples

let a = Vector3::new(1.0, 2.0, 3.0);
let b = Vector3::new(4.0, 5.0, 6.0);
let expected = Vector3::new(-0.66233766, -0.077922106, 0.50649357);
assert_eq!(expected, a.reject(b));

pub fn reflect(self, normal: Vector3) -> Self

Reflects this vector using a normal vector

• normal: The normal vector to reflect off of

Returns: Returns the reflected vector

Examples

let direction = Vector3::new(1.0, 0.0, 1.0);
let normal = Vector3::new(0.0, 0.0, -1.0);
let expected = Vector3::new(1.0, 0.0, -1.0);
assert_eq!(expected, direction.reflect(normal));
let direction = Vector3::new(0.25, -0.5, 1.25);
let normal = Vector3::new(1.0, 0.5, -1.0);
let expected = Vector3::new(2.75, 0.75, -1.25);
assert_eq!(expected, direction.reflect(normal));

pub fn rotate_towards( self, target: Vector3, radians_delta: f32, magnitude_delta: f32, ) -> Self

Rotates the vector around towards the target vector

• target: The target vector to rotate towards
• radians_delta: The maximum angle delta the vector will rotate in radians
• magnitude_delta: The maximum magnitude the vector will rotate with

Returns: Returns the rotated vector

Remarks

This method uses quaternions to rotate the vector, and does not appear if using the no_quaternions feature

Examples

let a = Vector3::new(1.0, 3.0, 4.0);
let b = Vector3::new(4.0, 6.0, 7.0);
let expected = Vector3::new(1.504205, 3.097963, 3.894842);
let actual = Vector3::rotate_towards(a, b, 0.1, 0.1);
assert_eq!(expected, actual);

pub fn scale(self, rhs: Vector3) -> Self

Scales the vector using another vector, multiplying everything component-wise

• rhs: The other vector to scale with

Returns: Returns the scaled vector

Examples

let a = Vector3::new(0.25, -0.5, 1.25);
let b = Vector3::new(2.0, 0.5, -1.0);
let expected = Vector3::new(0.5, -0.25, -1.25);
assert_eq!(expected, a.scale(b));

pub fn signed_angle_between(self, rhs: Vector3, axis: Vector3) -> f32

Gets the signed angle between the two vectors using an axis in radians

• rhs: The other vector to get the angle from
• axis: The axis vector to determine what direction the angle is going

Returns: Returns the signed angle between the two vectors using an axis in radians

Examples

let a = Vector3::new(0.25, -0.5, 1.25);
let b = Vector3::new(2.0, 0.5, -1.0);
let axis = Vector3::new(1.0, -1.0, 0.0);
assert_range!(-1.89518322157, a.signed_angle_between(b, axis));

pub fn signed_angle_between_deg(self, rhs: Vector3, axis: Vector3) -> f32

Gets the signed angle between the two vectors using an axis in degrees

• rhs: The other vector to get the angle from
• axis: The axis vector to determine what direction the angle is going

Returns: Returns the signed angle between the two vectors using an axis in degrees

Examples

let a = Vector3::new(0.25, -0.5, 1.25);
let b = Vector3::new(2.0, 0.5, -1.0);
let axis = Vector3::new(1.0, -1.0, 0.0);
assert_range!(-108.586, a.signed_angle_between_deg(b, axis), 0.01);

pub fn slerp(self, rhs: Vector3, t: f32) -> Self

Spherically interpolates between two vectors

• rhs: The target vector to interpolate towards
• t: The ratio (t) to interpolate with

Returns: Returns the spherically interpolated vector

Examples

let a = Vector3::new(1.0, 3.0, 4.0);
let b = Vector3::new(4.0, 6.0, 7.0);
let actual = Vector3::slerp_unclamped(a, b, 0.7);
let expected = Vector3::new(2.903773, 5.117129, 6.223807);
assert_range!(expected.x(), actual.x(), 0.0001);
assert_range!(expected.y(), actual.y(), 0.0001);
assert_range!(expected.z(), actual.z(), 0.0001);

pub fn slerp_unclamped(self, rhs: Vector3, t: f32) -> Self

Spherically interpolates between two vectors (not clamped)

• rhs: The target vector to interpolate towards
• t: The ratio (t) to interpolate with (not clamped)

Returns: Returns the spherically interpolated vector

Examples

let a = Vector3::new(1.0, 3.0, 4.0);
let b = Vector3::new(4.0, 6.0, 7.0);
let actual = Vector3::slerp_unclamped(a, b, 0.7);
let expected = Vector3::new(2.903773, 5.117129, 6.223807);
assert_range!(expected.x(), actual.x(), 0.0001);
assert_range!(expected.y(), actual.y(), 0.0001);
assert_range!(expected.z(), actual.z(), 0.0001);

pub fn smooth_damp( self, target: Vector3, velocity: Vector3, smooth_time: f32, max_speed: f32, delta: f32, ) -> (Self, Self)

Smooths a vector towards a desired goal over time

• target: The position to try to reach
• velocity: The current velocity
• smooth_time: The time (in seconds) it will take to reach the target
• max_speed: The maximum speed of the vector
• delta: The time between frames

Returns: Returns a tuple of a vector that is closer towards the target and the new velocity

Examples

let current = Vector3::new(1.0, 2.0, 3.0);
let target = Vector3::new(14.0, 15.0, 16.0);
let velocity = Vector3::new(4.0, 5.0, 6.0);
let time = 8.0;
let max_speed = 2.3;
let delta = 0.2;
let (position, velocity) = Vector3::smooth_damp(
	current,
	target,
	velocity,
	time,
	max_speed,
	delta
);
let expected_position = Vector3::new(1.7734365, 2.9636898, 4.156722);
let expected_velocity = Vector3::new(3.7411351, 4.644839, 5.5768046);
assert_eq!(expected_position, position);
assert_eq!(expected_velocity, velocity);

impl Vector3

Conversions

pub fn to_vector2(self) -> Vector2

Trait Implementations

impl Add<Vector2> for Vector3

type Output = Vector3

The resulting type after applying the + operator.

fn add(self, rhs: Vector2) -> Self::Output

Performs the + operation.

impl Add<Vector3> for Vector2

type Output = Vector3

The resulting type after applying the + operator.

fn add(self, rhs: Vector3) -> Self::Output

Performs the + operation.

impl Add for Vector3

type Output = Vector3

The resulting type after applying the + operator.

fn add(self, rhs: Vector3) -> Self::Output

Performs the + operation.

impl AddAssign<Vector2> for Vector3

fn add_assign(&mut self, rhs: Vector2)

Performs the += operation.

impl AddAssign<Vector3> for Vector2

fn add_assign(&mut self, rhs: Vector3)

Performs the += operation.

impl AddAssign for Vector3

fn add_assign(&mut self, rhs: Vector3)

Performs the += operation.

impl Clone for Vector3

fn clone(&self) -> Vector3

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Vector3

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

Formats the value using the given formatter.

impl Div<Vector3> for f32

type Output = Vector3

The resulting type after applying the / operator.

fn div(self, rhs: Vector3) -> Self::Output

Performs the / operation.

impl Div<Vector3> for i32

type Output = Vector3

The resulting type after applying the / operator.

fn div(self, rhs: Vector3) -> Self::Output

Performs the / operation.

impl Div<f32> for Vector3

type Output = Vector3

The resulting type after applying the / operator.

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

Performs the / operation.

impl Div<i32> for Vector3

type Output = Vector3

The resulting type after applying the / operator.

fn div(self, rhs: i32) -> Self::Output

Performs the / operation.

impl DivAssign<f32> for Vector3

fn div_assign(&mut self, rhs: f32)

Performs the /= operation.

impl DivAssign<i32> for Vector3

fn div_assign(&mut self, rhs: i32)

Performs the /= operation.

impl From<Vector2> for Vector3

fn from(value: Vector2) -> Self

Converts to this type from the input type.

impl From<Vector3> for Vector2

fn from(value: Vector3) -> Self

Converts to this type from the input type.

impl Mul<Vector3> for Quaternion

type Output = Vector3

The resulting type after applying the * operator.

fn mul(self, rhs: Vector3) -> Self::Output

Performs the * operation.

impl Mul<Vector3> for f32

type Output = Vector3

The resulting type after applying the * operator.

fn mul(self, rhs: Vector3) -> Self::Output

Performs the * operation.

impl Mul<Vector3> for i32

type Output = Vector3

The resulting type after applying the * operator.

fn mul(self, rhs: Vector3) -> Self::Output

Performs the * operation.

impl Mul<f32> for Vector3

type Output = Vector3

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> Self::Output

Performs the * operation.

impl Mul<i32> for Vector3

type Output = Vector3

The resulting type after applying the * operator.

fn mul(self, rhs: i32) -> Self::Output

Performs the * operation.

impl Mul for Vector3

type Output = f32

The resulting type after applying the * operator.

fn mul(self, rhs: Vector3) -> Self::Output

Performs the * operation.

impl MulAssign<f32> for Vector3

fn mul_assign(&mut self, rhs: f32)

Performs the *= operation.

impl MulAssign<i32> for Vector3

fn mul_assign(&mut self, rhs: i32)

Performs the *= operation.

impl Neg for Vector3

type Output = Vector3

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl PartialEq for Vector3

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 Sub<Vector2> for Vector3

type Output = Vector3

The resulting type after applying the - operator.

fn sub(self, rhs: Vector2) -> Self::Output

Performs the - operation.

impl Sub<Vector3> for Vector2

type Output = Vector3

The resulting type after applying the - operator.

fn sub(self, rhs: Vector3) -> Self::Output

Performs the - operation.

impl Sub for Vector3

type Output = Vector3

The resulting type after applying the - operator.

fn sub(self, rhs: Vector3) -> Self::Output

Performs the - operation.

impl SubAssign<Vector2> for Vector3

fn sub_assign(&mut self, rhs: Vector2)

Performs the -= operation.

impl SubAssign<Vector3> for Vector2

fn sub_assign(&mut self, rhs: Vector3)

Performs the -= operation.

impl SubAssign for Vector3

fn sub_assign(&mut self, rhs: Vector3)

Performs the -= operation.

impl Copy for Vector3

impl Eq for Vector3

impl Send for Vector3

impl Sync for Vector3