A point or a direction in space.
Right-handed: x and y as in the plane, z towards the viewer in the usual camera setup, so that cross(x, y) == z.
Values are immutable; every operation returns a new one.
The operators take two vectors of the same type. Scalar scaling is scale and divide, not * and /, which belong to the component-wise product.
abs
pub fn Vec3::abs(Self) -> Self
The vector with every component replaced by its absolute value.
angle_between
pub fn Vec3::angle_between(Self, Self) -> Float
The angle between the two directions, in radians, in 0..pi.
Unsigned: in space there is no counter-clockwise, so the answer is just how far apart they point. Computed from the normalized dot product, clamped so that rounding cannot push it out of the arc cosine's domain. Zero when either vector has no direction.
mbt check
test {
let x : @moonmath.Vec3 = @moonmath.Vec3::unit_x()
let y = @moonmath.Vec3::unit_y()
assert_true(@moonmath.approx(x.angle_between(y), @moonmath.half_pi))
assert_true(@moonmath.approx(x.angle_between(-x), @moonmath.pi))
}
any_orthonormal_pair
pub fn Vec3::any_orthonormal_pair(Self) -> (Self, Self)
Two unit vectors that, with this one, form a right-handed frame.
The first is any_orthonormal_vector; the second is this vector crossed with it, so u.cross(v) == self.normalize(). What a tangent frame for a normal map or a tube around a curve is built from. A vector with no direction answers the x and y axes.
any_orthonormal_vector
pub fn Vec3::any_orthonormal_vector(Self) -> Self
A unit vector perpendicular to this one.
The choice is fixed rather than arbitrary: the axis this vector leans on least is crossed with it, which is never near a zero-length product, and the same input always gives the same answer. A vector with no direction answers unit_x, there being no perpendicular to prefer.
approx
pub fn Vec3::approx(Self, Self, eps? : Float) -> Bool
Whether the two vectors agree to within eps component by component.
ceil
pub fn Vec3::ceil(Self) -> Self
The vector with every component rounded up to a whole number.
clamp
pub fn Vec3::clamp(Self, Self, Self) -> Self
The vector with every component pinned between low and high.
clamp_length
pub fn Vec3::clamp_length(Self, Float, Float) -> Self
The vector shortened to at most high and lengthened to at least low.
The direction is kept, and a vector with no direction is left as it is: there is no length to bring into range. The two bounds may be given in either order.
cross
pub fn Vec3::cross(Self, Self) -> Self
The cross product: the vector perpendicular to both, right-handed.
Its length is the area of the parallelogram they span, so the two are parallel exactly when it is zero. cross(x, y) is z.
distance
pub fn Vec3::distance(Self, Self) -> Float
The distance between the two points.
distance_squared
pub fn Vec3::distance_squared(Self, Self) -> Float
The square of the distance between the two points.
divide
pub fn Vec3::divide(Self, Float) -> Self
The vector divided by divisor, component by component.
Dividing by zero gives an infinity or a NaN, as the scalar division does.
dot
pub fn Vec3::dot(Self, Self) -> Float
The dot product: length * other.length * cos(angle) between them.
floor
pub fn Vec3::floor(Self) -> Self
The vector with every component rounded down to a whole number.
fract
pub fn Vec3::fract(Self) -> Self
The vector with every component replaced by its fractional part.
is_finite
pub fn Vec3::is_finite(Self) -> Bool
Whether every component is finite.
length
pub fn Vec3::length(Self) -> Float
The length of the vector: its distance from the origin.
length_squared
pub fn Vec3::length_squared(Self) -> Float
The square of the length, without the square root.
lerp
pub fn Vec3::lerp(Self, Self, Float) -> Self
The point a fraction of the way from self to other.
max
pub fn Vec3::max(Self, Self) -> Self
The component-wise larger of the two.
max_element
pub fn Vec3::max_element(Self) -> Float
The largest of the three components.
midpoint
pub fn Vec3::midpoint(Self, Self) -> Self
The point half way between the two.
min
pub fn Vec3::min(Self, Self) -> Self
The component-wise smaller of the two.
min_element
pub fn Vec3::min_element(Self) -> Float
The smallest of the three components.
move_towards
pub fn Vec3::move_towards(Self, Self, Float) -> Self
The vector moved towards target by at most max_delta, without passing it.
A step of a steering or an inverse-kinematics pass: the distance covered is max_delta however far away the target is, and the target itself once it is nearer than that.
new
pub fn Vec3::new(Float, Float, Float) -> Self
The vector from its three components.
normalize
pub fn Vec3::normalize(Self) -> Self
The vector scaled to length one, pointing the way it did.
The zero vector has no direction, and this returns Vec3::zero() rather than a NaN: the named answer is "no direction", not "undefined". Use try_normalize where the case needs telling apart.
normalize_or
pub fn Vec3::normalize_or(Self, Self) -> Self
The vector scaled to length one, or fallback if it has no direction.
one
pub fn Vec3::one() -> Self
The vector with one in every component.
project
pub fn Vec3::project(Self, Self) -> Self
The component of self along onto.
onto need not be a unit vector. A zero onto gives zero.
random_in_ball
pub fn Vec3::random_in_ball(Float, Float, Float) -> Self
A point uniformly distributed through the unit ball.
u1, u2 and u3 are independent uniform samples in [0, 1). The radius is the cube root of u3, not u3 itself: the volume grows as the cube of the radius, so a linear radius would pile the points near the centre.
random_on_sphere
pub fn Vec3::random_on_sphere(Float, Float) -> Self
A point uniformly distributed over the surface of the unit sphere.
u1 and u2 are independent uniform samples in [0, 1). The height is sampled uniformly rather than the polar angle, which is what keeps the distribution even: sampling the angle uniformly would crowd the poles.
reflect
pub fn Vec3::reflect(Self, Self) -> Self
The direction self takes after bouncing off a surface with normal normal.
self is the incoming direction and normal points out of the surface against it. Both are taken to be unit length, as they are in a shader; the result has the same length as self.
refract
pub fn Vec3::refract(Self, Self, Float) -> Self?
The direction self takes after entering a medium with normal normal and index ratio eta, or None past the critical angle.
self and normal are taken to be unit length, normal pointing against the incoming direction, and eta the ratio of the indices of refraction on the two sides. Past the critical angle the ray is reflected whole and there is no refracted direction: None says so, and reflecting is the caller's business.
mbt check
test {
let down : @moonmath.Vec3 = @moonmath.Vec3::new(0.0, -1.0, 0.0)
let up = @moonmath.Vec3::new(0.0, 1.0, 0.0)
// Straight down onto a surface and straight on through.
let through = down.refract(up, 0.5).unwrap()
assert_true(through.approx(down))
}
reject
pub fn Vec3::reject(Self, Self) -> Self
The component of self perpendicular to onto.
rotate_axis
pub fn Vec3::rotate_axis(Self, Self, Float) -> Self
The vector turned about axis by radians, by the right-hand rule.
axis is normalized first, and a zero axis turns nothing.
rotate_x
pub fn Vec3::rotate_x(Self, Float) -> Self
The vector turned about +x by radians, by the right-hand rule.
The turn looks from +x towards the origin: unit_y goes to unit_z for a quarter turn, as a rotation about x does everywhere else in the library.
mbt check
test {
let quarter : @moonmath.Vec3 = @moonmath.Vec3::unit_y().rotate_x(
@moonmath.half_pi,
)
assert_true(quarter.approx(@moonmath.Vec3::unit_z()))
}
rotate_y
pub fn Vec3::rotate_y(Self, Float) -> Self
The vector turned about +y by radians, by the right-hand rule.
rotate_z
pub fn Vec3::rotate_z(Self, Float) -> Self
The vector turned about +z by radians, by the right-hand rule.
round
pub fn Vec3::round(Self) -> Self
The vector with every component rounded to the nearest whole number, a half going up.
scale
pub fn Vec3::scale(Self, Float) -> Self
The vector multiplied by factor.
slerp
pub fn Vec3::slerp(Self, Self, Float) -> Self
The direction a fraction t of the way from this one to other, along the great circle.
Both are read as directions and normalized first, so the result is a unit vector and the length of the inputs does not matter. Directions that are the same give the same answer for every t; opposite ones have no single arc between them, and the start is returned. A vector with no direction falls back to the straight line, there being no arc to take.
mbt check
test {
let x : @moonmath.Vec3 = @moonmath.Vec3::unit_x()
let y = @moonmath.Vec3::unit_y()
let half_way = x.slerp(y, 0.5)
let diagonal = @moonmath.Vec3::new(1.0, 1.0, 0.0).normalize()
assert_true(half_way.approx(diagonal))
}
splat
pub fn Vec3::splat(Float) -> Self
The same value in all three components.
to_array
pub fn Vec3::to_array(Self) -> FixedArray[Float]
The components in order, [x, y, z], for handing to a buffer.
to_vec4
pub fn Vec3::to_vec4(Self, Float) -> Vec4
The same vector with w appended, for a point being lifted into 4D.
try_normalize
pub fn Vec3::try_normalize(Self) -> Self?
The vector scaled to length one, or None if it has no direction.
unit_x
pub fn Vec3::unit_x() -> Self
The unit vector along +x.
unit_y
pub fn Vec3::unit_y() -> Self
The unit vector along +y.
unit_z
pub fn Vec3::unit_z() -> Self
The unit vector along +z.
with_x
pub fn Vec3::with_x(Self, Float) -> Self
The same vector with a new x component.
with_y
pub fn Vec3::with_y(Self, Float) -> Self
The same vector with a new y component.
with_z
pub fn Vec3::with_z(Self, Float) -> Self
The same vector with a new z component.
xy
pub fn Vec3::xy(Self) -> Vec2
The first two components: the vector projected onto the xy plane.
xz
pub fn Vec3::xz(Self) -> Vec2
The first and third components: the projection onto the xz plane.
xzy
pub fn Vec3::xzy(Self) -> Self
The components in the order (x, z, y), swapping the last two.
yxz
pub fn Vec3::yxz(Self) -> Self
The components in the order (y, x, z), swapping the first two.
yz
pub fn Vec3::yz(Self) -> Vec2
The last two components: the projection onto the yz plane.
yzx
pub fn Vec3::yzx(Self) -> Self
The components in the order (y, z, x), a third of a turn of the axes.
zero
pub fn Vec3::zero() -> Self
The zero vector: the origin, and the one vector with no direction.
zxy
pub fn Vec3::zxy(Self) -> Self
The components in the order (z, x, y), the other third of a turn.
zyx
pub fn Vec3::zyx(Self) -> Self
The components backwards: (z, y, x), which turns a lookup into its mirror.