Crate maths_rs

Expand description

A linear algebra library for gamedev and graphics.

§Conventions

§Angles

All angles are in radians unless the function name explicitly states otherwise. The exceptions are focal_length_to_fov and fov_to_focal_length, which work in degrees to match common camera/lens tooling conventions.

§Matrix Layout

Matrices are stored in row-major order in memory. The element m[row * cols + col] accesses the element at a given row and column.

§Handedness

The library does not enforce a single coordinate system handedness. Functions that depend on handedness — such as perspective projection — are provided in both variants and indicate their convention explicitly in the function name (e.g. _lh_yup for left-handed y-up, _rh_yup for right-handed y-up).

Modules§

mat: multi dimensional row-major matrix with generic mat2, mat3, mat34 and mat4 implementations there is a mat43 type for mat34 transposes but it does not support the full functionality
num: base traits and operations for scalar numbers, signed numbers, integers and floats
prelude: export float types and all functions for qick and easy integration
quat: generic quaternion for varying floating point precision
swizz: module containing vector swizzling traits
vec: multi dimensional column vector with generic vec2, vec3 and vec4 implementations

Enums§

Classification: classification for tests vs planes (behind, infront or intersects)

Functions§

aabb_vs_aabb: returns true if the aabb defined by aabb_min1 to aabb_max1 intersects aabb_min2-aabb_max2
aabb_vs_frustum: returns true if the aabb defined by aabb_pos (centre) and aabb_extent is inside the frustum defined by 6 planes packed as vec4’s .xyz = normal, .w = plane distance
aabb_vs_obb: returns true if the aabb defined by aabb_min to aabb_max overlaps obb defined by matrix obb, where the matrix transforms an aabb with -1 to 1 extents into an obb
aabb_vs_plane: returns the classification of the 3D aabb defined as aabb_min to aabb_max vs the plane defined by point on plane x and normal n
aabb_vs_sphere: returns true if the aabb defined by aabb_min to aabb_max intersects the sphere (or circle) centred at s with radius r
abs: returns the absolute (positive) value of a
acos: returns the arc-cosine of v where the value v is in radians
almost_identity: returns soft clipping (in a cubic fashion) of x; let m be the threshold (anything above m stays unchanged), and n the value things will take when the signal is zero
approx: returns true if value a is approximately equal to value b within the specified epsilon eps
asin: returns the arc-sine of v where the value v is in radians
atan: returns the arc-tangent of v where the value v is in radians
atan2: returns the arc-tangent of v where the value v is in radians
azimuth_altitude_to_xyz: returns an xyz directional unit vector converted from azimuth and altitude angles in radians
barycentric: returns the barycentric coordinate (u, v, w) of point p inside triangle t1-t2-t3
capsule_vs_capsule: returns true if the capsule cp0-cp1 with radius cr0 overlaps the capsule cp2-cp3 with radius cr1
capsule_vs_plane: returns the classification of a capsule defined by line c1-c2 with radius r vs a plane defined by point on plane x and normal n
ceil: returns the ceil’d value of a (round up to nearest integer)
chebyshev_normalize: returns a Chebyshev normalized unit vector of a (where the normalization projects onto the unit cube)
clamp: returns the value x clamped to the range of min and max
closest_point_on_aabb: returns the closest point on the aabb defined by aabb_min and aabb_max to point p, if the point is inside the aabb it will return p
closest_point_on_cone: returns the closest point to p on the cone defined by cp position, with direction cv height h and radius r
closest_point_on_convex_hull: returns the clostest point to p on the edge of the convex hull defined by point list ‘hull’ with clockwise winding
closest_point_on_line_segment: returns the closest point on the line l1-l2 to point p
closest_point_on_obb: returns the closest point to point p on the obb defined by mat which will transform an aabb with extents -1 to 1 into an obb
closest_point_on_plane: returns the closest point on the plane to point p where the plane is defined by point on plane x and normal n
closest_point_on_polygon: returns the clostest point to p on the edge of the polygon defined by point list poly.
closest_point_on_ray: returns the closest point to p on the the ray starting at r0 with direction rv
closest_point_on_sphere: returns the closest point from p on sphere or circle centred at s with radius r
closest_point_on_triangle: returns the closest point to p on the triangle defined by t1-t2-t3
cone_vs_plane: return the classification of cone defined by position cp, direction cv with height h and radius at the base of r vs the plane defined by point x and normal n
convex_hull_from_points: returns a convex hull wound clockwise from point cloud points
convex_hull_vs_convex_hull: returns true if the convex hull convex0 overlaps convex1 where convex hull is an array of vertices forming a 2D convex polygon
copysign: returns the value a with the same sign as second parameter sign
cos: returns the cosine of v where the value v is in radians
cosh: returns the hyperbolic cosine of v where the value v is in radians
cross: returns the vector cross product of a x b, makes sense only for 3 or 7 dimensional vectors
cube: returns value a cubed (raised to the power 3)
cubic_interpolate: returns the cubic interpolation of bezier control points p1-p2-p3-p4 with percentage t
cubic_pulse: returns a cubic pulse (y position on a graph for x); equivalent to: smoothstep(c-w,c,x)-smoothstep(c,c+w,x)
cubic_tangent: returns the tangent of bezier control points p1-p2-p3-p4 with percentage t
deg_to_rad: returns the radian value converted from value a which is specified in degrees
dist: returns scalar distance between 2 points a and b (magnitude of the vector between the 2 points)
dist2: returns scalar squared distance between 2 points a and b to avoid using sqrt
distance: returns scalar distance between 2 points a and b (magnitude of the vector between the 2 points)
distance_on_line: returns the distance parameter t of point p projected along the line l1-l2, the value is not clamped to the line segment extents
distance_on_ray: returns the distance parameter t of point p projected along the ray r0 with direction rv, the value is not clamped to 0 or the start of the ray
dot: returns the vector dot product between a . b
exp: returns the base-e exponential function of v, which is e raised to the power v
exp2: returns 2 raised to the given power v
exp_impulse: returns an exponential impulse (y position on a graph for x); k controls the stretching of the function
exp_step: returns an exponential step (y position on a graph for x); k is control parameter, n is power which gives sharper curves.
exp_sustained_impulse: returns an exponential sustained impulse (y position on a graph for x); control on the width of attack with k and release with f
floor: returns the floored value of a (round down to nearest integer)
fmod: returns the floating point remainder of a / b
focal_length_to_fov: returns field of view in degrees converted from focal length with the specified aperture_width
fov_to_focal_length: returns focal length converted from field of view fov in degrees with the specified aperture_width
frac: returns the fractional part of value a
gain: returns gain (y position on a graph for x); remapping the unit interval into the unit interval by expanding the sides and compressing the center
get_triangle_normal: returns the normalized unit vector normal of triangle t1-t2-t3
gjk_2d: returns true if the 2d convex hull convex0 overlaps with convex1 using the gjk algorithm
gjk_3d: returns true if the 3D convex hull convex0 overlaps with convex1 using the gjk algorithm
gjk_mesh_support_function: finds support vertices for gjk based on convex meshses where convex0 and convex1 are an array of vertices that form a convex hull
hsv_to_rgb: returns an rgb value in 0-1 range converted from hsv in 0-1 range
integral_smoothstep: returns the integral smoothstep of x it’s derivative is never larger than 1
length: returns the scalar magnitude or length of vector a
lerp: returns a value interpolated between edges e0 and e1 by percentage t
line_segment_vs_line_segment: returns the intersection point if the line segment l1-l2 intersects with s1-s2
line_segment_vs_plane: returns the intersection point of the line segment l1-l2 and plane defined by point on plane x and normal n, returns None if no intersection exists
line_vs_line: returns the intersection point if the infinite line l1-l2 intersects with s1-s2
line_vs_plane: returns the intersection point of the infinite line defined as point on line l0 and direction lv with the plane defined by point on plane x and normal n
log: returns the logarithm of v in base
log2: returns the binary (base-2) logarithm of v
log10: returns the common (base-10) logarithm of v
mad: returns fused multiply add m * a + b
mag: returns the scalar magnitude or length of vector a
mag2: returns the scalar magnitude or length of vector a squared to avoid using sqrt
map_to_range: remap v within in_start -> in_end range to the new range out_start -> out_end
max: returns the maximum of a and b
min: returns the minimum of a and b
min_max: returns the tuple (min, max) of the value a and min_max tuple (min, max)
modf: returns the value v broken down into a tuple (fractional, integer) parts
morton_1: returns the number even bits extracted from x as set bits in the return; value 0b010101 returns 0b111
morton_2: returns the number of bits divisible by 3 in x. value 0b001001001 returns 0b111
morton_to_xy: returns the x,y grid position for morten order index d
morton_to_xyz: returns the x,y,z grid position for morten order index d
morton_xy: returns the morten order index from x,y position
morton_xyz: returns the morten order index from x,y,z position
nlerp: returns a value interpolated between edges e0 and e1 by percentage t with the result being normalised
normalize: returns a normalized unit vector of a
obb_vs_obb: returns true if the aabb defined by obb0 overlaps obb1 where the obb’s are defined by a matrix and the matrix transforms an aabb with -1 to 1 extents into an obb
parabola: returns a parabola (y position on a graph for x); use k to control its shape
pcurve: returns a power curve (y position on a graph for x); this is a generalziation of the parabola
perp: returns the perpendicular vector of a performing anti-clockwise rotation by 90 degrees
plane_distance: returns the distance to the plane define by a point on the plane x and normal of the plane n
plane_from_normal_and_point: returns a plane packed into Vec4 in the form .xyz = plane normal, .w = plane distance (constant) from x (point on plane) and n (planes normal)
point_aabb_distance: returns the distance that point p is from an aabb defined by aabb_min to aabb_max
point_cone_distance: returns the distance from point p to the cone defined by position cp, with height h and radius at the base of r
point_convex_hull_distance: returns the distance from point p to the edge of the convex hull defined by point list ‘hull’ with clockwise winding
point_inside_aabb: returns true if point p is inside the aabb defined by aabb_min and aabb_max
point_inside_cone: returns true if point p is inside cone defined by position cp facing direction cv with height h and radius r
point_inside_convex_hull: returns true if the point p is inside the 2D convex hull defined by point list hull with clockwise winding
point_inside_frustum: returns true if the point p is inside the frustum defined by 6 planes packed as vec4’s .xyz = normal, .w = plane distance
point_inside_obb: returns true if the point p is inside the obb defined by mat which will transform an aabb with extents -1 to 1 into an obb
point_inside_polygon: returns true if point p is inside the polygon defined by point list poly
point_inside_sphere: returns true if sphere (or circle) with centre s and radius r contains point p
point_inside_triangle: returns true if the point p is inside the triangle defined by t1-t2-t3
point_line_segment_distance: returns the distance that point p is from the line segment defined by l1-l2
point_obb_distance: returns the unsigned distance from point p to the obb defined by matrix obb, where the matrix transforms a unit cube from -1 to 1 into an obb
point_plane_distance: returns the distance to the plane from point p where the plane is defined by point on plane x and normal n
point_polygon_distance: returns the distance from point p to the edge of the polygon defined by point list ‘poly’
point_sphere_distance: returns the unsigned distance from point p0 to the sphere (or 2d circle) centred at s0 with radius r
point_triangle_distance: returns the distance point p is from a triangle defined by t1-t2-t3
point_vs_plane: returns the classification of point p vs the plane defined by point on plane x and normal n
poly_impulse: returns a quadratic impulse (y position on a graph for x); n is the degree of the polynomial and k controls the stretching of the function
powf: returns value a raised to the floating point power of value b
powi: returns value a raised to the integer power of value b
project_to_ndc: returns the 3D normalized device coordinate of point p projected by view_projection matrix, performing homogenous divide
project_to_sc: returns the 2D screen coordinate of 3D point p projected with view_projection, performing homogenous divide and viewport correction assumes screen coordinates are vup in the y-axis y.0 = bottom y.height = top
project_to_sc_vdown: returns the 2D screen coordinate of 3D point p projected with view_projection, performing homogenous divide and viewport correction coordinates are vdown in the y-axis vdown = y.0 = top y.height = bottom
quad_impulse: returns an quadratic impulse (y position on a graph for x); k controls the stretching of the function
rad_to_deg: returns the degree value converted from value a which is specified in radians
ray_vs_aabb: returns the intersection point of the ray with origin r0 and direction rv with the aabb defined by aabb_min and aabb_max
ray_vs_capsule: returns the intersection point of ray wih origin r0 and direction rv against the capsule with line c0-c1 and radius cr
ray_vs_cylinder: returns true if there is an intersection between ray wih origin r0 and direction rv against the cylinder with line c0-c1 and radius cr the intersection point is return as an Option if it exists.
ray_vs_line_segment: returns the intersection point if the ray with origin r0 and direction rv intersects the line segment l1-l2
ray_vs_obb: returns the intersection of the 3D ray with origin r0 and direction rv with the obb defined by mat
ray_vs_plane: returns the intersection point of the ray defined as origin of ray r0 and direction rv with the plane defined by point on plane x and normal n
ray_vs_sphere: returns the intersection point of ray with origin r0 and direction rv against the sphere (or circle) centred at s0 with radius r
ray_vs_triangle: returns the intersection point of ray r0 and normalized direction rv with triangle t0-t1-t2
recip: returns the reciprocal of value a
rgb_to_hsv: returns a hsv value in 0-1 range converted from rgb in 0-1 range
rgba8_to_vec4: returns a vec4 of rgba in 0-1 range from a packed rgba which is inside u32 (4 bytes, 0xRRGGBBAA)
rotate_2d: returns the vec2 rotated anti-clockwise rotation by radian angle
round: returns the value a rounded to closest integer floor if a < 0.5 or ceil if a >= 0.5
rsqrt: returns the reciprocal square root of value a
saturate: returns the saturated value of x into to the 0-1 range, this is the same as clamp(x, 0.0, 1.0)
scalar_triple: returns the scalar triple product of a x b x c, makes sense only for 3 dimensional vectors
shortest_line_segment_between_line_and_line_segment: returns the shortest line segment between 2 line segments p1-p2 and p3-p4 as an option tuple where .0 is the point on line segment 1 and .1 is the point on line segment 2
shortest_line_segment_between_line_segments: returns the shortest line segment between 2 line segments p1-p2 and p3-p4 as an option tuple where .0 is the point on line segment 1 and .1 is the point on line segment 2
shortest_line_segment_between_lines: returns the shortest line segment between 2 lines p1-p2 and p3-p4 as an option tuple where .0 is the point on line segment 1 and .1 is the point on line segment 2
signum: returns -1 if value a is negative, 1 if positive and 0 if zero (integers)
sin: returns the sine of v where the value v is in radians
sin_cos: returns a tuple of (sin(v), cos(v)) of v where the value v is in radian
sinc: returns a sin curve (y position on a graph for x); can be used for some bouncing behaviors. give k different integer values to tweak the amount of bounces
sinh: returns the hyperbolic sine of v where the value v is in radians
slerp: returns a value spherically interpolated between edges e0 and e1 by percentage t
smooth_start2: returns value t between the range c and d with offset b creating smooth easing at the start (t^2)
smooth_start3: returns value t between the range c and d with offset b creating smooth easing at the start (t^3)
smooth_start4: returns value t between the range c and d with offset b creating smooth easing at the start (t^4)
smooth_start5: returns value t between the range c and d with offset b creating smooth easing at the start (t^5)
smooth_stop2: returns value t between the range c and d with offset b creating smooth easing at the end of t (t^2)
smooth_stop3: returns value t between the range c and d with offset b creating smooth easing at the end of t (t^3)
smooth_stop4: returns value t between the range c and d with offset b creating smooth easing at the end of t (t^4)
smooth_stop5: returns value t between the range c and d with offset b creating smooth easing at the end of t (t^5)
smoothstep: returns the hermite interpolated value between edge e0 and e1 by percentage t
sphere_vs_capsule: returns true if the sphere or circle at centre s1 with radius r1 intersects capsule c0-c1 with radius cr
sphere_vs_frustum: returns true if the sphere with centre s and radius r is inside the frustum defined by 6 planes packed as vec4’s .xyz = normal, .w = plane distance
sphere_vs_obb: returns true if the sphere with centre s0 and radius r0 overlaps obb defined by matrix obb, where the matrix transforms a unit cube with extents -1 to 1 into an obb
sphere_vs_plane: returns the classification of sphere defined by centre s and radius r vs the plane defined by point on plane x and normal n
sphere_vs_sphere: returns true if the sphere or circle at centre s1 with radius r1 intersects s2-r2
sqr: returns value a squared (raised to the power 2)
sqrt: returns the square root of value a
step: returns 1 if a > b or 0 otherwise
tan: returns the tangent of v where the value v is in radians
tanh: returns the hyperbolic tangent of v where the value v is in radians
trunc: truncates value a - removing the fractional part, truncating to an integer
unproject_ndc: returns the unprojected 3D world position of point p which is specified in normalized device coordinates
unproject_sc: returns the unprojected 3D world position of screen coordinate p assumes screen coordinates are vup in the y-axis y.0 = bottom y.height = top
unproject_sc_vdown: returns the unprojected 3D world position of screen coordinate p coordinates are vdown in the y-axis vdown = y.0 = top y.height = bottom
vec4_to_rgba8: returns a packed u32 containing rgba8 (4 bytes, R8G8B8A8) converted from a Vec4 v of rgba in 0-1 range
vector_triple: returns the vector triple product of a x b x c, mainly used for 3D vectors, but with a 2D specialisation leveraging z-up
xyz_to_azimuth_altitude: returns (azimuth, altitude) in radians converted from directional unit vector xyz

Type Aliases§

Mat2d
Mat2f
Mat3d
Mat3f
Mat4d
Mat4f
Mat34d
Mat34f
Mat43d
Mat43f
Quatd
Quatf
Vec2d
Vec2f: opinionated type abbreviations
Vec2i
Vec2u
Vec3d
Vec3f
Vec3i
Vec3u
Vec4d
Vec4f
Vec4i
Vec4u

Crate maths_rs

Crate maths_rs Copy item path

§Conventions

§Angles

§Matrix Layout

§Handedness

Modules§

Enums§

Functions§

Type Aliases§

Crate maths_rs