SYNOPSIS
|
DESCRIPTION
![]() 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, Agar should be compiled with "--with-sse=inline", or "--with-altivec=inline". |
M-BY-N MATRICES
The following routines operate on dynamically-allocated
m by
n matrices:
|
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
4-BY-4 MATRICES
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[4][4] 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. |
SEE ALSO
AG_Intro(3), M_Complex(3), M_Quaternion(3), M_Real(3), M_Vector(3) |
HISTORY
The M_Matrix interface first appeared in Agar 1.3.3. |