Module ggez::graphics::na

nalgebra

nalgebra is a linear algebra library written for Rust targeting:

• General-purpose linear algebra (still lacks a lot of features…)
• Real time computer graphics.
• Real time computer physics.

Using nalgebra

You will need the last stable build of the rust compiler and the official package manager: cargo.

Simply add the following to your Cargo.toml file:

[dependencies]
nalgebra = "0.13"

Most useful functionalities of nalgebra are grouped in the root module nalgebra::.

However, the recommended way to use nalgebra is to import types and traits explicitly, and call free-functions using the na:: prefix:

#[macro_use]
extern crate approx; // For the macro relative_eq!
extern crate nalgebra as na;
use na::{Vector3, Rotation3};

fn main() {
    let axis  = Vector3::x_axis();
    let angle = 1.57;
    let b     = Rotation3::from_axis_angle(&axis, angle);

    relative_eq!(b.axis().unwrap(), axis);
    relative_eq!(b.angle(), angle);
}

Features

nalgebra is meant to be a general-purpose, low-dimensional, linear algebra library, with an optimized set of tools for computer graphics and physics. Those features include:

• A single parametrizable type Matrix for vectors, (square or rectangular) matrices, and slices with dimensions known either at compile-time (using type-level integers) or at runtime.
• Matrices and vectors with compile-time sizes are statically allocated while dynamic ones are allocated on the heap.
• Convenient aliases for low-dimensional matrices and vectors: Vector1 to Vector6 and Matrix1x1 to Matrix6x6, including rectangular matrices like Matrix2x5.
• Points sizes known at compile time, and convenience aliases: Point1 to Point6.
• Translation (seen as a transformation that composes by multiplication): Translation2, Translation3.
• Rotation matrices: Rotation2, Rotation3.
• Quaternions: Quaternion, UnitQuaternion (for 3D rotation).
• Unit complex numbers can be used for 2D rotation: UnitComplex.
• Algebraic entities with a norm equal to one: Unit<T>, e.g., Unit<Vector3<f32>>.
• Isometries (translation ⨯ rotation): Isometry2, Isometry3
• Similarity transformations (translation ⨯ rotation ⨯ uniform scale): Similarity2, Similarity3.
• Affine transformations stored as an homogeneous matrix: Affine2, Affine3.
• Projective (i.e. invertible) transformations stored as an homogeneous matrix: Projective2, Projective3.
• General transformations that does not have to be invertible, stored as an homogeneous matrix: Transform2, Transform3.
• 3D projections for computer graphics: Perspective3, Orthographic3.
• Matrix factorizations: Cholesky, QR, LU, FullPivLU, SVD, RealSchur, Hessenberg, SymmetricEigen.
• Insertion and removal of rows of columns of a matrix.
• Implements traits from the alga crate for generic programming.

Modules

allocator	Abstract definition of a matrix data storage allocator.
balancing	Functions for balancing a matrix.
constraint	Compatibility constraints between matrix shapes, e.g., for addition or multiplication.
coordinates	Structures to which matrices and vector can be auto-dereferenced (through Deref) to access components using their names. For example, if v is a 3D vector, one can write v.z instead of v[2].
core	[Reexported at the root of this crate.] Data structures for vector and matrix computations.
default_allocator	The default matrix data storage allocator.
dimension	Traits and tags for identifying the dimension of all algebraic entities.
geometry	[Reexported at the root of this crate.] Data structures for points and usual transformations (rotations, isometries, etc.)
givens	Construction of givens rotations.
householder	Construction of householder elementary reflections.
iter	Matrix iterators.
linalg	[Reexported at the root of this crate.] Factorization of real matrices.
storage	Abstract definition of a matrix data storage.

Structs

Bidiagonal	The bidiagonalization of a general matrix.
Cholesky	The Cholesky decomposion of a symmetric-definite-positive matrix.
DefaultAllocator	An allocator based on GenericArray and MatrixVec for statically-sized and dynamically-sized matrices respectively.
Dynamic	Dim of dynamically-sized algebraic entities.
FullPivLU	LU decomposition with full row and column pivoting.
Hessenberg	Hessenberg decomposition of a general matrix.
Id	The universal identity element wrt. a given operator, usually noted Id with a context-dependent subscript.
Isometry	A direct isometry, i.e., a rotation followed by a translation.
LU	LU decomposition with partial (row) pivoting.
Matrix	The most generic column-major matrix (and vector) type.
MatrixArray	A array-based statically sized matrix data storage.
MatrixVec	A Vec-based matrix data storage. It may be dynamically-sized.
Orthographic3	A 3D orthographic projection stored as an homogeneous 4x4 matrix.
PermutationSequence	A sequence of row or column permutations.
Perspective3	A 3D perspective projection stored as an homogeneous 4x4 matrix.
Point	A point in a n-dimensional euclidean space.
QR	The QR decomposition of a general matrix.
Quaternion	A quaternion. See the type alias UnitQuaternion = Unit<Quaternion> for a quaternion that may be used as a rotation.
RealSchur	Real Schur decomposition of a square matrix.
Reflection	A reflection wrt. a plane.
Rotation	A rotation matrix.
SVD	Singular Value Decomposition of a general matrix.
Similarity	A similarity, i.e., an uniform scaling, followed by a rotation, followed by a translation.
SliceStorage
SliceStorageMut
SymmetricEigen	Eigendecomposition of a symmetric matrix.
SymmetricTridiagonal	Tridiagonalization of a symmetric matrix.
Transform	A transformation matrix in homogeneous coordinates.
Translation	A translation.
U0
U1
U2
U3
U4
U5
U6
U7
U8
U9
U10
U11
U12
U13
U14
U15
U16
U17
U18
U19
U20
U21
U22
U23
U24
U25
U26
U27
U28
U29
U30
U31
U32
U33
U34
U35
U36
U37
U38
U39
U40
U41
U42
U43
U44
U45
U46
U47
U48
U49
U50
U51
U52
U53
U54
U55
U56
U57
U58
U59
U60
U61
U62
U63
U64
U65
U66
U67
U68
U69
U70
U71
U72
U73
U74
U75
U76
U77
U78
U79
U80
U81
U82
U83
U84
U85
U86
U87
U88
U89
U90
U91
U92
U93
U94
U95
U96
U97
U98
U99
U100
U101
U102
U103
U104
U105
U106
U107
U108
U109
U110
U111
U112
U113
U114
U115
U116
U117
U118
U119
U120
U121
U122
U123
U124
U125
U126
U127
Unit	A wrapper that ensures the undelying algebraic entity has a unit norm.

Enums

TAffine	Tag representing an affine Transform. Its bottom-row is equal to (0, 0 ... 0, 1).
TGeneral	Tag representing the most general (not necessarily inversible) Transform type.
TProjective	Tag representing the most general inversible Transform type.

Traits

Dim	Trait implemented by any type that can be used as a dimension. This includes type-level integers and Dynamic (for dimensions not known at compile-time).
DimAdd
DimDiv
DimMax
DimMin
DimMul
DimName	Trait implemented exclusively by type-level integers.
DimNameAdd
DimNameDiv
DimNameMax
DimNameMin
DimNameMul
DimNameSub
DimSub
IsDynamic	Trait implemented by Dynamic.
IsNotStaticOne	Trait implemented by Dynamic and type-level integers different from U1.
NamedDim
Real	Trait shared by all reals.
Scalar	The basic scalar type for all structures of nalgebra.
SliceRange	A range with a size that may be known at compile-time.
SubTCategoryOf	Indicates that Self is a more specific Transform category than Other.
SuperTCategoryOf	Indicates that Self is a more general Transform category than Other.
TCategory	Trait implemented by phantom types identifying the projective transformation type.
TCategoryMul	Traits that gives the Transform category that is compatible with the result of the multiplication of transformations with categories Self and Other.

Functions

abs	The absolute value of a.
angle	Computes the smallest angle between two vectors.
center	The center of two points.
clamp	Returns a reference to the input value clamped to the interval [min, max].
convert	Converts an object from one type to an equivalent or more general one.
convert_ref	Converts an object from one type to an equivalent or more general one.
convert_ref_unchecked⚠	Use with care! Same as try_convert but without any property checks.
convert_unchecked⚠	Use with care! Same as try_convert but without any property checks.
dimension	The dimension of the given algebraic entity seen as a vector space.
distance	The distance between two points.
distance_squared	The squared distance between two points.
dot	Computes the dot product of two vectors.
id	Gets the ubiquitous multiplicative identity element.
inf	Returns the infimum of a and b.
inf_sup	Returns simultaneously the infimum and supremum of a and b.
inverse	Computes the multiplicative inverse of an (always invertible) algebraic entity.
is_convertible	Indicates if ::try_convert will succeed without actually performing the conversion.
max	Same as cmp::max.
min	Same as cmp::min.
norm	Computes the L2 (euclidean) norm of a vector.
norm_squared	Computes the squared L2 (euclidean) norm of the vector v.
normalize	Computes the normalized version of the vector v.
one	Gets the multiplicative identity element.
origin	Gets the origin of the given point.
partial_clamp	Clamp value between min and max. Returns None if value is not comparable to min or max.
partial_cmp	Compare a and b using a partial ordering relation.
partial_ge	Returns true iff a and b are comparable and a >= b.
partial_gt	Returns true iff a and b are comparable and a > b.
partial_le	Returns true iff a and b are comparable and a <= b.
partial_lt	Returns true iff a and b are comparable and a < b.
partial_max	Return the maximum of a and b if they are comparable.
partial_min	Return the minimum of a and b if they are comparable.
partial_sort2	Sorts two values in increasing order using a partial ordering.
sup	Returns the supremum of a and b.
try_convert	Attempts to convert an object to a more specific one.
try_convert_ref	Attempts to convert an object to a more specific one.
try_inverse	Tries to gets an inverted copy of a square matrix.
try_invert_to	Performs a LU decomposition to overwrite out with the inverse of matrix.
try_normalize	Computes the normalized version of the vector v or returns None if its norm is smaller than min_norm.
wilkinson_shift	Computes the wilkinson shift, i.e., the 2x2 symmetric matrix eigenvalue to its tailing component tnn.
wrap	Wraps val into the range [min, max] using modular arithmetics.
zero	Gets the additive identity element.

Type Definitions

Affine2	A 2D affine transformation. Stored as an homogeneous 3x3 matrix.
Affine3	A 3D affine transformation. Stored as an homogeneous 4x4 matrix.
DMatrix	A dynamically sized column-major matrix.
DVector	A dynamically sized column vector.
DimDiff
DimMaximum
DimMinimum
DimNameDiff
DimNameMaximum
DimNameNimimum
DimNameProd
DimNameQuot
DimNameSum
DimProd
DimQuot
DimSum
Isometry2	A 2-dimensional isometry using a unit complex number for its rotational part.
Isometry3	A 3-dimensional isometry using a unit quaternion for its rotational part.
IsometryMatrix2	A 2-dimensional isometry using a rotation matrix for its rotational part.
IsometryMatrix3	A 3-dimensional isometry using a rotation matrix for its rotational part.
Matrix1	A stack-allocated, column-major, 1x1 square matrix.
Matrix2	A stack-allocated, column-major, 2x2 square matrix.
Matrix3	A stack-allocated, column-major, 3x3 square matrix.
Matrix4	A stack-allocated, column-major, 4x4 square matrix.
Matrix5	A stack-allocated, column-major, 5x5 square matrix.
Matrix6	A stack-allocated, column-major, 6x6 square matrix.
Matrix1x2	A stack-allocated, column-major, 1x2 square matrix.
Matrix1x3	A stack-allocated, column-major, 1x3 square matrix.
Matrix1x4	A stack-allocated, column-major, 1x4 square matrix.
Matrix1x5	A stack-allocated, column-major, 1x5 square matrix.
Matrix1x6	A stack-allocated, column-major, 1x6 square matrix.
Matrix2x1	A stack-allocated, column-major, 2x1 square matrix.
Matrix2x3	A stack-allocated, column-major, 2x3 square matrix.
Matrix2x4	A stack-allocated, column-major, 2x4 square matrix.
Matrix2x5	A stack-allocated, column-major, 2x5 square matrix.
Matrix2x6	A stack-allocated, column-major, 2x6 square matrix.
Matrix3x1	A stack-allocated, column-major, 3x1 square matrix.
Matrix3x2	A stack-allocated, column-major, 3x2 square matrix.
Matrix3x4	A stack-allocated, column-major, 3x4 square matrix.
Matrix3x5	A stack-allocated, column-major, 3x5 square matrix.
Matrix3x6	A stack-allocated, column-major, 3x6 square matrix.
Matrix4x1	A stack-allocated, column-major, 4x1 square matrix.
Matrix4x2	A stack-allocated, column-major, 4x2 square matrix.
Matrix4x3	A stack-allocated, column-major, 4x3 square matrix.
Matrix4x5	A stack-allocated, column-major, 4x5 square matrix.
Matrix4x6	A stack-allocated, column-major, 4x6 square matrix.
Matrix5x1	A stack-allocated, column-major, 5x1 square matrix.
Matrix5x2	A stack-allocated, column-major, 5x2 square matrix.
Matrix5x3	A stack-allocated, column-major, 5x3 square matrix.
Matrix5x4	A stack-allocated, column-major, 5x4 square matrix.
Matrix5x6	A stack-allocated, column-major, 5x6 square matrix.
Matrix6x1	A stack-allocated, column-major, 6x1 square matrix.
Matrix6x2	A stack-allocated, column-major, 6x2 square matrix.
Matrix6x3	A stack-allocated, column-major, 6x3 square matrix.
Matrix6x4	A stack-allocated, column-major, 6x4 square matrix.
Matrix6x5	A stack-allocated, column-major, 6x5 square matrix.
MatrixCross	The type of the result of a matrix cross product.
MatrixMN	A staticaly sized column-major matrix with R rows and C columns.
MatrixN	A staticaly sized column-major square matrix with D rows and columns.
MatrixNM	[ Deprecated ] A staticaly sized column-major matrix with R rows and C columns.
MatrixSlice	A matrix slice.
MatrixSliceMut	A matrix slice.
MatrixSum	The type of the result of a matrix sum.
Point1	A statically sized 1-dimensional column point.
Point2	A statically sized 2-dimensional column point.
Point3	A statically sized 3-dimensional column point.
Point4	A statically sized 4-dimensional column point.
Point5	A statically sized 5-dimensional column point.
Point6	A statically sized 6-dimensional column point.
Projective2	An inversible 2D general transformation. Stored as an homogeneous 3x3 matrix.
Projective3	An inversible 3D general transformation. Stored as an homogeneous 4x4 matrix.
Rotation2	A 2-dimensional rotation matrix.
Rotation3	A 3-dimensional rotation matrix.
RowDVector	A dynamically sized row vector.
RowVector	A matrix with one row and D columns .
RowVector1	A stack-allocated, 1-dimensional row vector.
RowVector2	A stack-allocated, 2-dimensional row vector.
RowVector3	A stack-allocated, 3-dimensional row vector.
RowVector4	A stack-allocated, 4-dimensional row vector.
RowVector5	A stack-allocated, 5-dimensional row vector.
RowVector6	A stack-allocated, 6-dimensional row vector.
RowVectorN	A statically sized D-dimensional row vector.
Similarity2	A 2-dimensional similarity.
Similarity3	A 3-dimensional similarity.
SimilarityMatrix2	A 2-dimensional similarity using a rotation matrix for its rotation part.
SimilarityMatrix3	A 3-dimensional similarity using a rotation matrix for its rotation part.
SquareMatrix	A square matrix.
Transform2	A 2D general transformation that may not be inversible. Stored as an homogeneous 3x3 matrix.
Transform3	A 3D general transformation that may not be inversible. Stored as an homogeneous 4x4 matrix.
Translation2	A 2-dimensional translation.
Translation3	A 3-dimensional translation.
UnitComplex	A complex number with a norm equal to 1.
UnitQuaternion	A unit quaternions. May be used to represent a rotation.
Vector	A matrix with one column and D rows.
Vector1	A stack-allocated, 1-dimensional column vector.
Vector2	A stack-allocated, 2-dimensional column vector.
Vector3	A stack-allocated, 3-dimensional column vector.
Vector4	A stack-allocated, 4-dimensional column vector.
Vector5	A stack-allocated, 5-dimensional column vector.
Vector6	A stack-allocated, 6-dimensional column vector.
VectorN	A statically sized D-dimensional column vector.
VectorSum	The type of the result of a matrix sum.