Math
NEO's math types: vectors, quaternions and directions, geometric shapes, bounding volumes and ray casts, curves, splines and easing, smooth interpolation and random sampling.
On this page
The prelude brings in NEO's math: vectors and matrices, rotations and directions, geometric shapes with bounding volumes, and curves with easing. They come from three crates, all re-exported by neo: neo::math (vectors, rotations), neo::shape (shapes, bounding volumes, rays) and neo::curve (curves, splines, easing).
Vectors, rotations and directions#
| Type | What it is |
|---|---|
Vec2, Vec3, Vec4 | f32 vectors. Also IVec* (i32), UVec* (u32), BVec* (bool), Vec3A (16-byte aligned, faster in bulk). |
Mat2, Mat3, Mat4 | Matrices. |
Quat | A 3D rotation. Quat::from_rotation_y(angle), Quat::from_axis_angle(axis, angle), Quat::from_euler(EulerRot::YXZ, yaw, pitch, roll). |
Rot2 | A 2D rotation. Rot2::degrees(45.0), Rot2::radians(r). |
Dir2, Dir3 | A vector guaranteed to be unit length. Dir3::new(v) fails on a zero vector instead of producing NaN. Dir3::Y, Dir3::NEG_Z and so on. |
Isometry2d, Isometry3d | A rotation plus a translation, with no scale. Shapes take one to say where they are. |
Rect, IRect, URect | Axis-aligned 2D rectangles. |
let v = vec3(1.0, 2.0, 3.0);
let len = v.length();
let n = v.normalize_or_zero();
let mid = Vec3::ZERO.lerp(v, 0.5);
let up = Dir3::Y;
let turned = Quat::from_rotation_y(std::f32::consts::FRAC_PI_2) * Vec3::X; // ≈ −ZAngles are radians throughout. Use f32::to_radians() for degrees.
Portable float functions#
neo::math::ops has sin, cos, powf, exp, atan2 and the other float functions under their standard names. Prefer them in code that must give the same results on every platform: with the libm cargo feature they use one implementation everywhere, where the standard library's can differ slightly between platforms.
Shapes#
The shape types describe geometry without being tied to rendering. You can turn them into meshes, draw them with gizmos, measure them and test them for overlap.
| 2D | 3D |
|---|---|
Circle, Ellipse, Annulus, Arc2d, CircularSector, CircularSegment | Sphere, Cuboid, Cylinder, Capsule3d, Cone, ConicalFrustum, Torus |
Rectangle, Rhombus, Triangle2d, RegularPolygon, Polygon, ConvexPolygon, Capsule2d | Triangle3d, Tetrahedron, Plane3d, InfinitePlane3d |
Segment2d, Polyline2d, Line2d, Plane2d | Segment3d, Polyline3d, Line3d, Extrusion<T> |
// as a mesh
let mesh = meshes.add(Capsule3d::new(0.5, 1.0));
// as a gizmo
gizmos.primitive_3d(&Sphere::new(1.0), Isometry3d::from_translation(Vec3::Y), Color::WHITE);
// measured
let area = Circle::new(2.0).area();Examples: cargo run --example render_primitives, custom_primitives.
Bounding volumes and ray casts#
Bounding volumes are simple shapes around more complex ones, for cheap overlap tests.
| Type | What it is |
|---|---|
Aabb2d, Aabb3d | Axis-aligned boxes. |
BoundingCircle, BoundingSphere | Circles and spheres. |
RayCast2d, RayCast3d, AabbCast2d, BoundingCircleCast and others | Rays and moving volumes, tested against volumes. |
Ray2d, Ray3d | A ray. get_point(distance), intersect_plane(origin, plane). |
Every shape can compute its bounds at a given position:
let a = Cuboid::new(1.0, 1.0, 1.0).aabb_3d(Isometry3d::from_translation(Vec3::ZERO));
let b = Sphere::new(0.5).bounding_sphere(Isometry3d::from_translation(Vec3::X));
if a.intersects(&b) {
// overlapping
}aabb_2d and bounding_circle do the same in 2D. intersects comes from the IntersectsVolume trait.
Example: cargo run --example bounding_2d.
Curves and easing#
A Curve<T> gives a value for each point of its domain. Sample it with sample(t) (returns None outside the domain), sample_clamped(t) or, for many points, samples(n).
| Type | What it is |
|---|---|
EasingCurve::new(start, end, EaseFunction::...) | Eases from one value to another over the domain 0 to 1. |
EaseFunction | Linear, QuadraticIn/Out/InOut, CubicIn/Out/InOut, SineIn, ExponentialOut, ElasticIn, BackOut, BounceOut, SmoothStep, Steps(n, JumpAt) and more. |
CubicBezier, CubicHermite, CubicCardinalSpline, CubicBSpline, CubicNurbs | Spline builders. to_curve() (or to_curve_cyclic() for loops) makes a CubicCurve. |
FunctionCurve, SampleAutoCurve | A curve from a closure, or from evenly spaced samples. |
let fade = EasingCurve::new(0.0, 1.0, EaseFunction::CubicOut);
let alpha = fade.sample_clamped(progress);
let points = [vec3(0.0, 0.0, 0.0), vec3(1.0, 2.0, 0.0), vec3(3.0, 1.0, 0.0), vec3(4.0, 0.0, 0.0)];
let path = CubicCardinalSpline::new_catmull_rom(points).to_curve().unwrap();
let position = path.position(1.5);Curves combine: map, reparametrize, chain, reverse, ping_pong and graph build new curves from old ones. Curves also drive animation; see Tweening.
Examples: cargo run --example cubic_splines, easing_functions.
Smooth following#
smooth_nudge moves a value toward a target at a rate that doesn't depend on the frame rate, which a plain lerp with a fixed factor doesn't do. It works on vectors, quaternions, directions and floats.
fn follow(time: Res<Time>, target: Single<&Transform, With<Player>>, mut cam: Single<&mut Transform, (With<Camera>, Without<Player>)>) {
let decay_rate = 4.0; // higher is snappier
cam.translation.smooth_nudge(&target.translation, decay_rate, time.delta_secs());
}Example: cargo run --example smooth_follow.
Random sampling#
With a random number generator from the rand crate, ShapeSample picks random points on or in any shape (sample_iter needs rand::distr::Distribution in scope):
let p = Sphere::new(2.0).sample_interior(&mut rng); // inside
let q = Circle::new(1.0).sample_boundary(&mut rng); // on the edge
let many: Vec<Vec2> = Rectangle::new(4.0, 2.0).interior_dist().sample_iter(&mut rng).take(100).collect();Add rand (and a seeded generator such as chacha20's ChaCha8Rng, for repeatable results) to your crate's dependencies.
Example: cargo run --example random_sampling.