# Crate al_jabr

Expand description

A generic linear algebra library for computer graphics.

`al_jabr` is roughly compatibly 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`.

#### §Vector

Vectors can be constructed from arrays of any type and size. Under the hood, a Vector is a one-dimensional Matrix. Use the vector! macro to easily construct a vector:

``````let a = vector![ 0u32, 1, 2, 3 ];
assert_eq!(
a,
Vector::<u32, 4>::from([ 0u32, 1, 2, 3 ])
);``````

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

``````let b = vector![ 0.0f32, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, ];
let c = vector![ 1.0f32, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, ] * 0.5;
assert_eq!(
b + c,
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 = vector!(1i32, 1);
let b = vector!(5i32, 5);
assert_eq!(a.distance2(b), 32);       // distance method not implemented.
assert_eq!((b - a).magnitude2(), 32); // magnitude method not implemented.

let a = vector!(1.0f32, 1.0);
let b = vector!(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!(
vector!(0.0f32, 20.0, 0.0)
.normalize(),
vector!(0.0f32, 1.0, 0.0)
);``````

#### §Matrix

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:

``````let a = Matrix::<f32, 3, 3>::from([
[1.0, 0.0, 0.0],
[0.0, 1.0, 0.0],
[0.0, 0.0, 1.0],
]);

let b: Matrix::<i32, 3, 3> = matrix![
[ 0, -3, 5 ],
[ 6, 1, -4 ],
[ 2, 3, -2 ]
];``````

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
);``````

## Modules§

• 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§

• 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.
• Construct a new Point of any size.
• Construct a new Vector of any size.

## Structs§

• A representation of a rotation in three dimensional space. Each component is the rotation around its respective axis in radians.
• The result of LU factorizing a square matrix with partial-pivoting.
• An `N`-by-`M` Column Major matrix.
• A Matrix that forms an orthonormal basis. Commonly known as a rotation matrix.
• Permutation matrix created for LU decomposition.
• A point in space.
• A quaternion, composed of a scalar and a `Vector3`.
• An object with a magnitude of one

## Traits§

• Vector spaces that have an inner (also known as “dot”) product.
• Convert a object to a unit object
• A type with a distance function between two values.
• Defines the multiplicative identity element for `Self`.
• Values that are real numbers.
• Defines an InnerSpace where the Scalar is a real number. Automatically implemented.
• A MetricSpace where the metric is a real number.
• A type that can rotate a Vector (or Point) of a given dimension.
• Vectors that can be added together and multiplied by scalars form a `VectorSpace`.
• Defines the additive identity for `Self`.