Crate al_jabr

Expand description

A generic linear algebra library for computer graphics.

al_jabr is roughly compatible with cgmath and is intended to provide a small set of lightweight linear algebra operations typically useful in interactive computer graphics.

al_jabr is n-dimensional, meaning that its data structures support an arbitrary number of elements. If you wish to create a five-dimensional rigid body simulation, al_jabr can help you.

§Getting started

All of al_jabr’s types are exported in the root of the crate, so importing them all is as easy as adding the following to the top of your source file:

use al_jabr::*;

After that, you can begin using al_jabr.

§Vectors

Small (N = 1, 2, 3, 4) vectors as well as an N-dimensional ColumnVector are provided. Unless you have a need for larger vectors, it is recommended to use Vector1, Vector2, Vector3 or Vector4.

Add, Sub, and Neg will be properly implemented for any Vector and ColumnVector<Scalar, N> for any respective implementation of such operations for Scalar. Operations are only implemented for vectors of equal sizes.

let a = Vector4::new(0.0f32, 1.0, 2.0, 3.0);
let b = Vector4::new(1.0f32, 1.0, 1.0, 1.0);
assert_eq!(
    a + b,
    Vector4::new(1.0, 2.0, 3.0, 4.0),
);

let d = column_vector![ 0.0f32, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, ];
let e = column_vector![ 1.0f32, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, ] * 0.5;
assert_eq!(
    d + e,
    column_vector![ 0.5f32, 1.5, 2.5, 3.5, 4.5, 5.5, 6.5 ]
);

If the scalar type implements Mul as well, then the Vector will be an InnerSpace and have the dot product defined for it, as well as the ability to find the squared distance between two vectors (implements MetricSpace) and the squared magnitude of a vector. If the scalar type is a real number then the distance between two vectors and the magnitude of a vector can be found in addition:

let a = Vector2::new(1i32, 1);
let b = Vector2::new(5i32, 5);
assert_eq!(a.distance2(b), 32);       // distance method not implemented.
assert_eq!((b - a).magnitude2(), 32); // magnitude method not implemented.

let a = Vector2::new(1.0f32, 1.0);
let b = Vector2::new(5.0f32, 5.0);
const close: f32 = 5.65685424949;
assert_eq!(a.distance(b), close);       // distance is implemented.
assert_eq!((b - a).magnitude(), close); // magnitude is implemented.

// Vector normalization is also supported for floating point scalars.
assert_eq!(
    Vector3::new(0.0f32, 20.0, 0.0)
        .normalize(),
    Vector3::new(0.0f32, 1.0, 0.0)
);

§Swizzling

ColumnVectors of any size and Vectors of size 2, 3 and 4 support swizzling. The methods are hidden as to not pollute the docs, but are still available:

assert_eq!(Vector3::new(1i32, 2, 3).xy(), Vector2::new(1i32, 2));

§Points

Small (N = 1, 2, 3, 4) points in space are provided.

Points are far less flexible and useful than vectors and are used to express the purpose or meaning of a variable through its type.

Points can be moved through space by adding or subtracting Vectors from them.

The only mathematical operator supported between two points is subtraction, which results in the vector between the two points.

Points can be freely converted to and from vectors via from_vec and to_vec.

let a = Point3::new(5, 4, 3);
let b = Point3::new(1, 1, 1);
assert_eq!(a - b, Vector3::new(4, 3, 2));

§Matrices

Matrices can be created from an array of arrays of any size and scalar type. Matrices are column-major and constructing a matrix from a raw array reflects that. The matrix! macro can be used to construct a matrix in row-major order:

// Construct in column-major order:
let a = Matrix::<i32, 3, 3>::from([
    [  0,  6,  2 ],
    [ -3,  1,  3 ],
    [  5, -4, -2 ],
]);

// Construct in row-major order:
let b: Matrix::<i32, 3, 3> = matrix![
    [ 0, -3, 5 ],
    [ 6, 1, -4 ],
    [ 2, 3, -2 ]
];

assert_eq!(a, b);

All operations performed on matrices produce fixed-size outputs. For example, taking the transpose of a non-square matrix will produce a matrix with the width and height swapped:

assert_eq!(
    Matrix::<i32, 1, 2>::from([ [ 1 ], [ 2 ] ])
        .transpose(),
    Matrix::<i32, 2, 1>::from([ [ 1, 2 ] ])
);

As with Vectors, if the underlying scalar type supports the appropriate operations, a matrix will implement element-wise Add and Sub for matrices of equal size:

let a = matrix!([1_u32]);
let b = matrix!([2_u32]);
let c = matrix!([3_u32]);
assert_eq!(a + b, c);

And this is true for any type that implements Add, so therefore the following is possible as well:

let a = matrix!([matrix!([1_u32])]);
let b = matrix!([matrix!([2_u32])]);
let c = matrix!([matrix!([3_u32])]);
assert_eq!(a + b, c);

For a given type T, if T: Clone and Vector<T, _> is an InnerSpace, then multiplication is defined for Matrix<T, N, M> * Matrix<T, M, P>. The result is a Matrix<T, N, P>:

let a: Matrix::<i32, 3, 3> = matrix![
    [ 0, -3, 5 ],
    [ 6, 1, -4 ],
    [ 2, 3, -2 ],
];
let b: Matrix::<i32, 3, 3> = matrix![
    [ -1, 0, -3 ],
    [  4, 5,  1 ],
    [  2, 6, -2 ],
];
let c: Matrix::<i32, 3, 3> = matrix![
    [  -2,  15, -13 ],
    [ -10, -19,  -9 ],
    [   6,   3,   1 ],
];
assert_eq!(
    a * b,
    c
);

Some matrices have special functions defined for them. Check out Matrix3 and Matrix4 for more information.

Modules§

row_view: Support for iterating over matrix rows. This is less natural than iterating over columns due to the iteration not matching the stride of the underlying storage.

Macros§

column_vector: Construct a new ColumnVector of any size.
matrix: Construct a Matrix of any size. The matrix is specified in row-major order, but this function converts it to al_jabr’s native column-major order.

Structs§

Euler: A representation of a rotation in three dimensional space. Each component is the rotation around its respective axis in radians.
LU: The result of LU factorizing a square matrix with partial-pivoting.
Matrix: An N-by-M Column Major matrix.
Orthonormal: A Matrix that forms an orthonormal basis. Commonly known as a rotation matrix.
Permutation: Permutation matrix created for LU decomposition.
Point1: A point in 1-dimensional space.
Point2: A point in 2-dimensional space.
Point3: A point in 3-dimensional space.
Point4: A point in 4-dimensional space.
Quaternion: A quaternion, composed of a scalar and a Vector3.
Unit: An object with a magnitude of one
Vector1: A vector in 1-dimensional space.
Vector2: A vector in 2-dimensional space.
Vector3: A vector in 3-dimensional space.
Vector4: A vector in 4-dimensional space.

Traits§

InnerSpace: Vector spaces that have an inner (also known as “dot”) product.
IntoUnit: Convert a object to a unit object
MetricSpace: A type with a distance function between two values.
One: Defines the multiplicative identity element for Self.
Real: Values that are real numbers.
RealInnerSpace: Defines an InnerSpace where the Scalar is a real number. Automatically implemented.
RealMetricSpace: A MetricSpace where the metric is a real number.
Rotation2: A type that can rotate a Vector2 or Point2
Rotation3: A type that can rotate a Vector3 or Point3
RotationN: A type that can rotate a ColumnVector of a given dimension.
VectorSpace: Vectors that can be added together and multiplied by scalars form a VectorSpace.
Zero: Defines the additive identity for Self.

Type Aliases§

ColumnVector: N-element column vector.
ColumnVector1: 1-element vector.
ColumnVector2: 2-element vector.
ColumnVector3: 3-element vector.
ColumnVector4: 4-element vector.
Matrix2: A 2-by-2 square matrix.
Matrix3: A 3-by-3 square matrix.
Matrix4: A 4-by-4 square matrix.
SquareMatrix

Crate al_jabr

Crate al_jabr Copy item path

§Getting started

§Vectors

§Swizzling

§Points

§Matrices

Modules§

Macros§

Structs§

Traits§

Type Aliases§

Crate al_jabr