Struct pix_engine::vector::Vector[][src]

#[repr(transparent)]
pub struct Vector<T, const N: usize>(_);
Expand description

A Euclidean Vector in N-dimensional space.

Also known as a geometric vector. A Vector has both a magnitude and a direction. The Vector struct, however, contains N values for each dimensional coordinate.

The magnitude and direction are retrieved with the mag and heading methods.

Some example uses of a Vector include modeling a position, velocity, or acceleration of an object or particle.

Vectors can be combined using vector math, so for example two Vectors can be added together to form a new Vector using let v3 = v1 + v2 or you can add one Vector to another by calling v1 += v2.

Please see the module-level documentation for examples.

Implementations

Converts Vector < T, N > to Vector < U, N >.

Returns Vector < T, N > with the nearest integers to the numbers. Round half-way cases away from 0.0.

Returns Vector < T, N > with the largest integers less than or equal to the numbers.

Returns Vector < T, N > with the smallest integers greater than or equal to the numbers.

Constructs a Vector from [T; N] coordinates.

Examples
let v = Vector::new([2.1]);
assert_eq!(v.as_array(), [2.1]);

let v = Vector::new([2.1, 3.5]);
assert_eq!(v.as_array(), [2.1, 3.5]);

let v = Vector::new([2.1, 3.5, 1.0]);
assert_eq!(v.as_array(), [2.1, 3.5, 1.0]);

Constructs a Vector at the origin.

Example
let v: Vector<f64, 3> = Vector::origin();
assert_eq!(v.as_array(), [0.0, 0.0, 0.0]);

Constructs a Vector from an individual x coordinate.

Constructs a Vector from individual x/y coordinates.

Constructs a Vector from individual x/y/z coordinates.

Constructs a Vector from another Vector, rotated by an angle.

Example
use pix_engine::math::FRAC_PI_2;
let v1 = Vector::new([10.0, 20.0]);
let v2 = Vector::rotated(v1, FRAC_PI_2);
assert!(v2.approx_eq(vector![-20.0, 10.0], 1e-4));

Constructs a 2D unit Vector in the XY plane from a given angle. Angle is given as radians and is unaffected by AngleMode.

Example
use pix_engine::math::FRAC_PI_4;
let v = Vector::from_angle(FRAC_PI_4, 15.0);
assert!(v.approx_eq(vector!(10.6066, 10.6066), 1e-4));

Returns the 2D angular direction of the Vector.

Example
let v = vector!(10.0, 10.0);
let heading: f64 = v.heading();
assert_eq!(heading.to_degrees(), 45.0);

Rotate a 2D Vector by an angle in radians, magnitude remains the same. Unaffected by AngleMode.

Example
use pix_engine::math::FRAC_PI_2;
let mut v = vector!(10.0, 20.0);
v.rotate(FRAC_PI_2);
assert!(v.approx_eq(vector![-20.0, 10.0], 1e-4));

Returns the cross product between two Vectors. Only defined for 3D Vectors.

Example
let v1 = vector!(1.0, 2.0, 3.0);
let v2 = vector!(1.0, 2.0, 3.0);
let cross = v1.cross(v2);
assert_eq!(cross.as_array(), [0.0, 0.0, 0.0]);

Returns the angle between two 3D Vectors in radians.

Example
let v1 = vector!(1.0, 0.0, 0.0);
let v2 = vector!(0.0, 1.0, 0.0);
let angle = v1.angle_between(v2);
assert_eq!(angle, std::f64::consts::FRAC_PI_2);

Constructs a Vector from a Point.

Example
let p = point!(1.0, 2.0);
let v = Vector::from_point(p);
assert_eq!(v.as_array(), [1.0, 2.0]);

Returns the x-coordinate.

Panics

If Vector has zero dimensions.

Example
let v = vector!(1.0, 2.0);
assert_eq!(v.x(), 1.0);

Sets the x-magnitude.

Panics

If Vector has zero dimensions.

Example
let mut v = vector!(1.0, 2.0);
v.set_x(3.0);
assert_eq!(v.as_array(), [3.0, 2.0]);

Returns the y-magnitude.

Panics

If Vector has less than 2 dimensions.

Example
let v = vector!(1.0, 2.0);
assert_eq!(v.y(), 2.0);

Sets the y-magnitude.

Panics

If Vector has less than 2 dimensions.

Example
let mut v = vector!(1.0, 2.0);
v.set_y(3.0);
assert_eq!(v.as_array(), [1.0, 3.0]);

Returns the z-magnitude.

Panics

If Vector has less than 3 dimensions.

Example
let v = vector!(1.0, 2.0, 2.5);
assert_eq!(v.z(), 2.5);

Sets the z-magnitude.

Panics

If Vector has less than 3 dimensions.

Example
let mut v = vector!(1.0, 2.0, 1.0);
v.set_z(3.0);
assert_eq!(v.as_array(), [1.0, 2.0, 3.0]);

Get Vector coordinates as [T; N].

Example
let v = vector!(2.0, 1.0, 3.0);
assert_eq!(v.as_array(), [2.0, 1.0, 3.0]);

Get Vector coordinates as a byte slice &[T; N].

Example
let v = vector!(2.0, 1.0, 3.0);
assert_eq!(v.as_bytes(), &[2.0, 1.0, 3.0]);

Get Vector coordinates as a mutable byte slice &[T; N].

Example
let mut vector = vector!(2.0, 1.0, 3.0);
for v in vector.as_bytes_mut() {
    *v *= 2.0;
}
assert_eq!(vector.as_bytes(), &[4.0, 2.0, 6.0]);

Returns Vector as a Vec.

Example
let v = vector!(1.0, 1.0, 0.0);
assert_eq!(v.to_vec(), vec![1.0, 1.0, 0.0]);

Constructs a Vector by shifting coordinates by given amount.

Examples
let mut v = vector!(2.0, 3.0, 1.5);
v.offset([2.0, -4.0]);
assert_eq!(v.as_array(), [4.0, -1.0, 1.5]);

Offsets the x-coordinate of the point by a given amount.

Panics

If Point has zero dimensions.

Offsets the y-coordinate of the point by a given amount.

Panics

If Vector has less than 2 dimensions.

Offsets the z-coordinate of the point by a given amount.

Panics

If Vector has less than 3 dimensions.

Constructs a Vector by multiplying it by the given scale factor.

Examples
let mut v = vector!(2.0, 3.0, 1.5);
v.scale(2.0);
assert_eq!(v.as_array(), [4.0, 6.0, 3.0]);

Wraps Vector around the given [T; N], and size (radius).

Examples
let mut v = vector!(200.0, 300.0);
v.wrap([150.0, 400.0], 10.0);
assert_eq!(v.as_array(), [-10.0, 300.0]);

let mut v = vector!(-100.0, 300.0);
v.wrap([150.0, 400.0], 10.0);
assert_eq!(v.as_array(), [160.0, 300.0]);

Constructs a random unit Vector in 1D space.

Example
let v: Vector<f64, 3> = Vector::random();
assert!(v.x() > -1.0 && v.x() < 1.0);
assert!(v.y() > -1.0 && v.y() < 1.0);
assert!(v.z() > -1.0 && v.z() < 1.0);

// May make v's (x, y, z) values something like:
// (0.61554617, 0.0, 0.0) or
// (-0.4695841, 0.0, 0.0) or
// (0.6091097, 0.0, 0.0)

Constructs a Vector from a reflection about a normal to a line in 2D space or a plane in 3D space.

Example
let v1 = Vector::new([1.0, 1.0, 0.0]);
let normal = Vector::new([0.0, 1.0, 0.0]);
let v2 = Vector::reflection(v1, normal);
assert_eq!(v2.as_array(), [-1.0, 1.0, 0.0]);

Constructs a unit Vector of length 1 from another Vector.

Example
let v1 = Vector::new([0.0, 5.0, 0.0]);
let v2 = Vector::normalized(v1);
assert_eq!(v2.as_array(), [0.0, 1.0, 0.0]);

Returns the magnitude (length) of the Vector.

The formula used for 2D is sqrt(x*x + y*y). The formula used for 3D is sqrt(x*x + y*y + z*z).

Example
let v = vector!(1.0, 2.0, 3.0);
let abs_difference = (v.mag() as f64 - 3.7416).abs();
assert!(abs_difference <= 1e-4);

Returns the squared magnitude (length) of the Vector. This is faster if the real length is not required in the case of comparing vectors.

The formula used for 2D is x*x + y*y. The formula used for 3D is x*x + y*y + z*z.

Example
let v = vector!(1.0, 2.0, 3.0);
assert_eq!(v.mag_sq(), 14.0);

Returns the dot product betwen two Vectors.

Example
let v1 = vector!(1.0, 2.0, 3.0);
let v2 = vector!(2.0, 3.0, 4.0);
let dot_product = v1.dot(v2);
assert_eq!(dot_product, 20.0);

Reflect Vector about a normal to a line in 2D space or a plane in 3D space.

Example
let mut v = vector!(4.0, 6.0); // Vector heading right and down
let n = vector!(0.0, 1.0); // Surface normal facing up
v.reflect(n); // Reflect about the surface normal (e.g. the x-axis)
assert_eq!(v.x(), -4.0);
assert_eq!(v.y(), 6.0);

Set the magnitude (length) of the Vector.

Examples
let mut v = vector!(10.0, 20.0, 2.0);
v.set_mag(10.0);
assert!(v.approx_eq(vector![4.4543, 8.9087, 0.8908], 1e-4));

Returns the Euclidean distance between two Vectors.

Example
let v1 = vector!(1.0, 0.0, 0.0);
let v2 = vector!(0.0, 1.0, 0.0);
let dist = v1.dist(v2);
let abs_difference: f64 = (dist - std::f64::consts::SQRT_2).abs();
assert!(abs_difference <= 1e-4);

Normalize the Vector to length 1 making it a unit vector.

Example
let mut v = vector!(10.0, 20.0, 2.0);
v.normalize();
assert!(v.approx_eq(vector!(0.4454, 0.8908, 0.0890), 1e-4));

Clamp the magnitude (length) of Vector to the value given by max.

Example
let mut v = vector!(10.0, 20.0, 2.0);
v.limit(5.0);
assert!(v.approx_eq(vector!(2.2271, 4.4543,  0.4454), 1e-4));

Constructs a Vector by linear interpolating between two Vectors by a given amount between 0.0 and 1.0.

Example
let v1 = vector!(1.0, 1.0, 0.0);
let v2 = vector!(3.0, 3.0, 0.0);
let v3 = v1.lerp(v2, 0.5);
assert_eq!(v3.as_array(), [2.0, 2.0, 0.0]);

Returns whether two Vectors are approximately equal.

Example
let v1 = vector!(10.0, 20.0, 2.0);
let v2 = vector!(10.0001, 20.0, 2.0);
assert!(v1.approx_eq(v2, 1e-3));

Trait Implementations

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

The resulting type after applying the + operator.

Performs the + operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the += operation. Read more

Performs the conversion.

Performs the conversion.

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Return default Vector as origin.

The resulting type after dereferencing.

Dereferences the value.

Mutably dereferences the value.

Deserialize this value from the given Serde deserializer. Read more

Display Vector as a string of coordinates.

The resulting type after applying the / operator.

Performs the / operation. Read more

Performs the /= operation. Read more

Converts &[T; M] to Vector < T, N >.

Performs the conversion.

Converts Vector < T, N > to &[T; M].

Performs the conversion.

Converts [T; M] to Vector < T, N >.

Performs the conversion.

Converts Vector < T, N > to [T; M].

Performs the conversion.

Creates a value from an iterator. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

The returned type after indexing.

Performs the indexing (container[index]) operation. Read more

Performs the mutable indexing (container[index]) operation. Read more

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

The resulting type after applying the * operator.

Performs the * operation. Read more

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

T * Point.

The resulting type after applying the * operator.

Performs the *= operation. Read more

The resulting type after applying the - operator.

Performs the unary - operation. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Method which takes an iterator and generates Self from the elements by multiplying the items. Read more

Method which takes an iterator and generates Self from the elements by multiplying the items. Read more

Serialize this value into the given Serde serializer. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

The resulting type after applying the - operator.

Performs the - operation. Read more

Performs the -= operation. Read more

Performs the -= operation. Read more

Performs the -= operation. Read more

Method which takes an iterator and generates Self from the elements by “summing up” the items. Read more

Method which takes an iterator and generates Self from the elements by “summing up” the items. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.