# Quick reference§

Free functions are noted with a leading `::`

while methods start with a dot.
Most types are type aliases. Refer to the API
documentation for details about the functions arguments
and type parameters.

Serialization with serde can be enabled by enabling the
**serde-serialize** feature.

### Matrices and vectors§

- Within this reference,
`N`

is the scalar type,`R`

,`C`

and`D`

are type-level integers. - Matrices are stored in column-major order.
- Vectors are type aliases for matrices with only one column or one row.
- Overloaded operators:
`*`

,`/`

,`+`

,`-`

(binary and unary), and corresponding assignement operators. - Comparison operators
`==`

,`>=`

,`<=`

,`>`

,`<`

, using column-major lexicographic ordering. - Mutable and non-mutable indexing:
`the_vector[usize]`

and`the_matrix[(usize, usize)]`

. - All angles are in radian.

`Matrix<...>`

Generic matrix type.

`Matrix1<N> .. Matrix6<N>`

, `MatrixN<N, D>`

Statically-sized square matrix.

`Matrix1x2<N> .. Matrix6x5<N>`

, `MatrixNM<N, R, C>`

Statically-sized rectangular matrix.

`DMatrix<N>`

Dynamically-sized matrix.

`Vector1<N> .. Vector6<N>`

, `VectorN<N, D>`

Statically-sized column vector.

`DVector<N>`

Dynamically-sized column vector.

`RowVector1<N> .. RowVector6<N>`

, `RowVectorN<N, D>`

Statically-sized row vector.

`RowDVector<N>`

Dynamically-sized row vector.

`Unit<T>`

Wrapper that ensures the underlying value of type `T`

is normalized.

#### Construction§

The exact number of argument, and the existence of some constructors depend on
the result matrix type. For example, dynamically-sized or 2D vectors do not
have a `::z()`

constructors. In the following “Low-dimensional” means with
dimensions 1 to 6 for vectors and 1x1 to 6x6 for matrices.

`::x(), ::y(), ::z(), ::w(), ::a(), ::b()`

Low-dimensional vector with one component set to 1 and others to 0.

`::x_axis() .. ::b_axis()`

Low-dimensional vector wrapped in `Unit<...>`

.

`::new(x, y, .. b)`

Low-dimensional vector constructed from its components values.

`::new(m11, m12, .. m66)`

Low-dimensional matrix constructed from its components values.

`::new_uninitialized(...)`

*[unsafe]* Matrix with uninitialized components.

`::new_random(...)`

Matrix filled with random values.

`::identity(...)`

The identity matrix.

`::from_element(...)`

Matrix filled with the given element.

`::from_iterator(...)`

Matrix filled with the content of the given iterator.

`::from_row_slice(...)`

Matrix filled with the content of the components given in **row-major** order.

`::from_column_slice(...)`

Matrix filled with the content of the components given in **column-major** order.

`::from_fn(...)`

Matrix filled with the result of a closure called for each entry.

`::from_diagonal(...)`

Diagonal matrix with the given diagonal vector.

`::from_diagonal_element(...)`

Diagonal matrix with the diagonal filled with one value.

`::from_rows(...)`

Matrix formed by the concatenation of the given rows.

`::from_columns(...)`

Matrix formed by the concatenation of the given columns.

`Zero::zero()`

Matrix filled with zeroes.

`One::one()`

The identity matrix.

`Bounded::min_value()`

Matrix filled with the min value of the scalar type.

`Bounded::max_value()`

Matrix filled with the max value of the scalar type.

`Rand::rand(...)`

Matrix filled with random values.

#### Common methods§

`.len()`

The number of components.

`.shape()`

The number of rows and columns.

`.nrows()`

The number of rows.

`.ncols()`

The number of columns.

`.strides()`

Number of skipped original rows/columns in-between each row/column of a slice.

`.iter()`

An iterator through the matrix components in column-major order.

`.iter_mut()`

A mutable iterator through the matrix components in column-major order.

`.get_unchecked(i, j)`

*[unsafe]* The matrix component at row `i`

and column `j`

. No bound-checking.

`.get_unchecked_mut(i, j)`

*[unsafe]* The mutable matrix component at row `i`

and column `j`

. No bound-checking.

`.swap_unchecked(i, j)`

*[unsafe]* Swaps two components. No bound-checking.

`.as_slice()`

Reference to the internal column-major array of component.

`.as_mut_slice()`

Mutable reference to the internal column-major array of component.

`.copy_from(m)`

Copies the content of another matrix with the same shape.

`.fill(e)`

Sets all components to `e`

.

`.map(f)`

Applies `f`

to each component and stores the results on a new matrix.

`.zip_map(m2, f)`

Applies `f`

to the pair of component from `self`

and `m2`

and stores the results on a new matrix.

`.relative_eq(...)`

Componentwise approximate matrix equality.

`.component_mul(rhs)`

Componentwise multiplication (aka. Hadamard product).

`.component_mul_mut(rhs)`

In-place componentwise multiplication (aka. Hadamard product).

`.component_div(rhs)`

Componentwise division.

`.component_div_mut(rhs)`

In-place componentwise division.

`.tranpose()`

Matrix transposition.

`.tranpose_mut()`

In-place matrix transposition.

`.try_inverse()`

Matrix inverse. Returns `None`

if it fails.

`.try_inverse_mut()`

In-place matrix inverse. Returns `false`

if it fails.

`.diagonal()`

The matrix diagonal.

`.abs()`

The absolute value of this matrix components.

`.determinant()`

The matrix determinant.

`.trace()`

The trace of this matrix.

`.norm()`

The L2 norm.

`.norm_squared()`

The squared L2 norm.

`.normalize()`

Normalization using the L2 norm.

`.normalize_mut()`

In-place normalization using the L2 norm.

`.try_normalize()`

Normalization. Returns `None`

if the norm is too small.

`.try_normalize_mut()`

In-place normalization. Returns `None`

if the norm is too small.

`.dot(rhs)`

Vector dot product.

`.tr_dot(rhs)`

Vector dot product between `self.transpose()`

and `rhs`

.

`.perp(rhs)`

2D cross product, i.e., determinant of the matrix formed by two 2D column vectors.

`.cross(rhs)`

3D cross product.

`.angle(rhs)`

Smallest angle between two vectors.

`.is_square()`

Tests if `self`

is square.

`.is_identity()`

Tests if `self`

is the identity matrix.

`.is_orthogonal()`

Tests if `self.transpose() * self`

is the identity.

`.is_special_orthogonal()`

Tests if `self.is_orthogonal()`

and has a determinant equal to 1.

`.is_invertible()`

Tests if `self`

is invertible.

#### Slicing§

Slice are references to sub-matrices. They do not own their data and cannot be converted to arrays as their data buffer may not be contiguous in memory.

`.row(...)`

A matrix row.

`.rows(...)`

Several consecutive rows.

`.rows_with_step(...)`

Several non-consecutive rows.

`.fixed_rows::<D>(...)`

A compile-time number of consecutive rows.

`.fixed_rows_with_step::<D>(...)`

A compile-time number of non-consecutive rows.

`.column(...)`

A matrix column.

`.columns(...)`

Several consecutive columns.

`.columns_with_step(...)`

Several non-consecutive columns.

`.fixed_columns::<D>(...)`

A compile-time number of consecutive columns.

`.fixed_columns_with_step::<D>(...)`

A compile-time number of non-consecutive columns.

`.slice(...)`

Consecutive rows and columns.

`.slice_with_steps(...)`

Non consecutive rows and columns.

`.fixed_slice::<R, C>(...)`

Compile-time number of consecutive rows and columns.

`.fixed_slice_with_steps::<R, C>(...)`

Compile-time number of non consecutive rows and columns.

#### Decompositions§

`.qr()`

QR decomposition.

`.eig(...)`

Eigenvalue and eigenvectors computation.

`.cholesky()`

Cholesky factorization.

`.cholesky_unchecked()`

Cholesky factorization without checking the matrix symmetry.

`.hessenberg()`

Hessenberg form computation.

#### Computer graphics§

Those are constructors and methods useful for the computer graphics community that work with homogeneous matrix coordinates, e.g., 4x4 matrices for 3D transformations. Homogeneous matrix coordinates are expected to be multiplied by homogeneous vectors (the vector goes on the right-hand-side of the operator).

`::new_scaling(...)`

An uniform scaling matrix.

`::new_nonuniform_scaling(...)`

A nonuniform scaling matrix.

`::new_translation(...)`

A translation matrix.

`::new_rotation(...)`

A rotation matrix from an axis multiplied by an angle.

`::new_rotation_wrt_point(...)`

An isometry matrix that lets the given point invariant.

`::from_scaled_axis(...)`

A rotation matrix from an axis multiplied by an angle.

`::from_euler_angles(...)`

A rotation matrix from euler angles (roll → pitch → yaw).

`::from_axis_angle(...)`

A rotation matrix from an axis and an angle.

`::new_orthographic(...)`

An orthographic projection matrix.

`::new_perspective(...)`

A perspective projection matrix.

`::new_observer_frame(...)`

The local coordinate system of a player looking toward a given point.

`::look_at_rh(...)`

A right-handed look-at matrix.

`::look_at_lh(...)`

A left-handed look-at matrix.

`.append_scaling(...)`

Applies an uniform scaling after `self`

.

`.append_scaling_mut(...)`

Applies in-place an uniform scaling after `self`

.

`.prepend_scaling(...)`

Applies an uniform scaling before`self`

.

`.prepend_scaling_mut(...)`

Applies in-place an uniform scaling before `self`

.

`.append_nonuniform_scaling(...)`

Applies a non-uniform scaling after `self`

.

`.append_nonuniform_scaling_mut(...)`

Applies in-place a non-uniform scaling after `self`

.

`.prepend_nonuniform_scaling(...)`

Applies a non-uniform scaling before`self`

.

`.prepend_nonuniform_scaling_mut(...)`

Applies in-place a non-uniform scaling before `self`

.

`.append_translation(...)`

Applies a translation after `self`

.

`.append_translation_mut(...)`

Applies in-place a translation after `self`

.

`.prepend_translation(...)`

Applies a translation before `self`

.

`.prepend_translation_mut(...)`

Applies in-place a translation before `self`

.

### Geometry§

- Most geometric entities are just wrappers for a matrix (or a vector).
- Points have a very different semantic than vectors.
- Transformation types are preferred over raw matrices as they allow optimization because of their intrinsic properties.
- Use
`.to_homogeneous()`

pour obtain the corresponding homogeneous raw matrix of any geometric entity. - Transformations of different types can be multiplied together. The result type is automatically inferred.
- Transforming a point or vector can be done by multiplication. The transformation goes on the left-hand-side.
- In the following, notations like
`Transform2/3<N>`

means “either`Transform2<N>`

or`Transform3<N>`

”.

`Point2/3<N>`

A location in space.

`Quaternion<N>`

A general quaternion.

`Rotation2/3<N>`

A rotation matrix.

`UnitComplex<N>`

A 2D rotation represented as a unit complex number.

`UnitQuaternion<N>`

A 3D rotation represented as a unit quaternion.

`Translation2/3<N>`

A translation (stored as a vector).

`Isometry2/3<N>`

A 2D/3D isometry containing an unit complex/quaternion.

`Similarity2/3<N>`

A 2D/3D similarity containing an unit complex/quaternion.

`Affine2/3<N>`

An affine transformation stored as an homogeneous matrix.

`Projective2/3<N>`

An invertible transformation stored as an homogeneous matrix.

`Transform2/3<N>`

A general transformation stored as an homogeneous matrix.

#### Projections§

Projections follow the behavior expected by Computer Graphics community, i.e., they are invertible transformation from a convex shape to a unit cube centered at the origin.

`Perspective3<...>`

3D perspective projection matrix using homogeneous coordinates.

`Orthographic3<...>`

3D orthographic projection matrix using homogeneous coordinates.

#### Base types§

Base types are generic wrt. the dimension and/or the data storage type. They should not be used directly, prefer type aliases shown in the previous section instead.

`PointBase<...>`

A location in space.

`QuaternionBase<...>`

A general quaternion.

`RotationBase<...>`

A rotation matrix.

`TranslationBase<...>`

A translation vector.

`IsometryBase<...>`

An isometry containing an abstract rotation type.

`SimilarityBase<...>`

A similarity containing an abstract rotation type.

`TransformBase<..., Affine>`

An affine transformation stored as an homogeneous matrix.

`TransformBase<..., Projective>`

An invertible transformation stored as an homogeneous matrix.

`TransformBase<..., General>`

A general transformation stored as an homogeneous matrix.

`PerspectiveBase<...>`

A perspective projection matrix.

`OrthographicBase<...>`

An orthographic projection matrix.

### Data storage and allocators§

- Data storages provide access to a matrix shape and its components.
- The last type parameter of the generic
`Matrix<...>`

type is the data storage. - Allocators provide a way to allocate a data storage type that depends on whether the matrix shape is statically known.
- Transformation types require a data storage that implements
`OwnedStorage<...>`

.

#### Traits§

`Storage<...>`

Structures that give access to a buffer of data.

`StorageMut<...>`

Structures that give access to a mutable buffer of data.

`OwnedStorage<...>`

Structures that uniquely own their mutable and contiguous data buffer.

`Allocator<...>`

Structures that can allocate a data buffer.

`OwnedAllocator<...>`

An allocator for a specific owned data storage.

#### Implementors§

`MatrixArray<...>`

A stack-allocated owned data storage.

`MatrixVec<...>`

A heap-allocated owned data storage.

`MatrixSlice<...>`

A non-mutable reference to a piece of another data storage.

`MatrixSliceMut<...>`

A mutable reference to a piece of another data storage.

`DefaultAllocator<...>`

Allocates a `MatrixArray`

for compile-time-sized matrices, and a `MatrixVec`

otherwise.

Getting started Vectors and matrices