M_Matrix interfaces implement linear algebra operations on (real or complex valued)
n dimensional vectors, and
Optimized interfaces are provided for fixed-dimensional types (which have
entries directly accessible as
x, y, z and
w). Arbitrary-dimensional types may or may not use fixed arrays in memory.
For example, the "sparse" backend uses a sparse matrix representation,
and the "db" backend stores vector entries in a database.
Backends can be selected at run-time, or Agar-Math can be compiled to provide inline expansions of all operations of a specific backend. Vector extensions (such as SSE and AltiVec) are used by default, if a runtime cpuinfo check determines that they are available (the build remains compatible with non-vector platforms, at the cost of extra function calls). For best performance on vector-capable platforms, all M_Matrix operations may be expanded inline for the target platform (using the Agar build options "--with-sse-inline" and "--with-altivec-inline").
The following routines operate on dynamically-allocated
M-BY-N MATRICES: INITIALIZATION
The M_New() function allocates a new m by n matrix. M_Free() releases all resources allocated for the specified matrix. M_Resize() resizes M to m by n. Existing entries are preserved, but new entries are left uninitialized. If insufficient memory is available, -1 is returned and an error message is set. On success, the function returns 0.
M_SetIdentity() initializes M to the identity matrix. M_SetZero() initializes M to all zeros.
M_Copy() copies the contents of matrix A into D, which is assumed to have the same dimensions (otherwise, -1 is returned). M_Dup() returns a duplicate of M.
The M_ReadMatrix() and M_WriteMatrix() functions are used to (de)serialize the contents of matrix A from/to the specified AG_DataSource(3).
M-BY-N MATRICES: ACCESSING ELEMENTS
The M_Get() and M_Set() routines respectively retrieve and set the element i, j.
M_GetElement() returns a pointer to the element i, j. As long as the entry exists, it is safe to read and write the element.
The M_ToFloats() and M_ToDoubles() functions return a representation of matrix A as an array of float or double values in row-major order. The M_FromFloats() and M_FromDoubles() functions initialize matrix A from an array of float or double values in row-major order. In both cases, it is assumed that the arrays are of the correct size for the given matrix dimensions.
M_Print() dumps the individual matrix entries to the standard error output. It is only for debugging purposes. Agar GUI applications can use the provided M_Matview(3) widget to display matrix contents.
M-BY-N MATRICES: OPERATIONS
The following routines are optimized for 4x4 matrices, as frequently
encountered in computer graphics.
Entries are directly accessible as structure members.
Available backends include:
4-BY-4 MATRICES: INITIALIZATION
The M_MatZero44() and M_MatZero44v() functions initializes the target matrix Z to the zero matrix.
M_MatIdentity44() and M_MatIdentity44v() initializes the target matrix I to the identity matrix.
The M_MatCopy44() routine copies the contents of matrix Msrc into Mdst. The original contents of Mdst are overwritten.
4-BY-4 MATRICES: ACCESSING ELEMENTS
The elements of
M_Matrix44 are directly accessible via the
m member of the structure.
Elements of the matrix are stored in row-major format.
The structure is defined as:
Notice that SIMD extensions force single-precision floats, regardless of the precision for which Agar-Math was built (if a 4x4 matrix of higher precision is required, the general M_Matrix type may be used).
The following functions convert between M_Matrix44 and numerical arrays:
M_MatToFloats44() converts matrix A to a 4x4 array of floats flts. M_MatToDoubles44() converts matrix A to a 4x4 array of doubles dbls. M_MatFromFloats44() initializes matrix M from the contents of a 4x4 array of floats flts. M_MatFromDoubles44() initializes matrix M from the contents of a 4x4 array of doubles dbls.
4-BY-4 MATRICES: OPERATIONS
The M_MatTranspose44(), M_MatTranspose44p() and M_MatTranspose44v() function compute and return the transpose of matrix A (i.e., all elements i,j are swapped for elements j,i).
The function M_MatInvert44() computes the inverse of A using Cramer's rule and cofactors. If the matrix is not invertible, the return value is undefined.
The M_MatInvertElim44() function computes the inverse of A by systematic Gaussian elimination. If the matrix is not invertible (singular up to M_MACHEP precision), the function fails.
M_MatMult44(), M_MatMult44v() and M_MatMult44pv() compute the product of matrices A and B.
The M_MatMultVector44(), M_MatMultVector44p() and M_MatMultVector44v() functions perform matrix-vector multiplication Ax, and returns x.
M_MatRotateAxis44() multiplies matrix T against a rotation matrix describing a rotation of theta radians about axis (relative to the origin). The M_MatOrbitAxis44() variant takes axis to be relative to the specified center point as opposed to the origin.
M_MatRotateEul44() multiplies T against a matrix describing a rotation about the origin in terms of Euler angles pitch, roll and yaw (given in radians).
M_MatRotate44I(), M_MatRotate44J() and M_MatRotate44K() multiply T with a matrix describing a rotation of theta radians about the basis vector i, j or k, respectively.
M_MatTranslate44v() multiplies T against a matrix describing a translation by vector v. M_MatTranslate44(), M_MatTranslate44X(), M_MatTranslate44Y() and M_MatTranslate44Z() accept individual coordinate arguments.
M_MatScale44() multiplies T against a matrix describing uniform/non-uniform scaling by [x,y,z,w]. M_MatUniScale44() performs uniform scaling by c.
|AG_Intro(3), M_Complex(3), M_Quaternion(3), M_Real(3), M_Vector(3)|
|The M_Matrix interface first appeared in Agar 1.3.3.|