Matrix API

Markdown

These types and their corresponding functions are for working with matrices stored within memory, as opposed to being preloaded within the XMTRX back-bank of FP registers. Typically this is desirable for one-off operations where there is no batching of matrix operations, especially when clobbering XMTRX is undesirable. Matrices are column-major, as with GL, and shz_mat4x4_t must be aligned on 8-byte boundaries unless you use an _unaligned routine. Beware that some of these routines clobber the matrix currently loaded as the active 4x4 matrix, XMTRX.

C header: #include <sh4zam/shz_matrix.h>
C++ header: #include <sh4zam/shz_matrix.hpp>
C++ types: shz::mat4x4
Symbols: 120

Verb model

For most transform types this API offers several versions of the same operation. Using translation as the example:

Verb	Meaning
`init_*`	Initializes the whole matrix to the given transform, setting the other components to identity.
`set_*`	Sets only the values corresponding to the given transform, leaving the others alone.
`apply_*`	Applies the transform, updating only the affected values based on their current values (additively for translation, multiplicatively for scaling and rotation).
`translate / scale / rotate_*`	GL-style: multiplies and accumulates the matrix by a matrix initialized to the given transform. The most general form.
`load_* / store_*`	Moves a matrix between memory and XMTRX. `load_apply_` and `load_apply_store_` are fused combinations.
`transform_*`	Transforms vectors or points. For `vec3` variants, `transform_point` implies w = 1 and `transform_vec` implies w = 0.

Suffixes

Suffixes used in this module. The full list is in Naming and Suffixes.

_unaligned: Works on matrix data that is not 8-byte aligned, passed as a plain float[16]. The default routines use 64-bit paired FMOV loads that need 8-byte alignment.
_transpose: Operates with the transposed matrix (row-major input, or inverse-rotation use).
_wxyz: Register/column permutation so that FTRV yields W first (cycle 4 instead of 7), which helps perspective division.
_safe: Guards degenerate input (zero-length vectors, zero denominators) at a small cost.

Initialization

Routines for fully initializing a matrix.

Symbol	Description
`shz_mat4x4_init_identity`	Initializes the given matrix to the 4x4 identity matrix.
`shz_mat4x4_init_identity_safe`	Safely initializes the given matrix to the 4x4 identity matrix.
`shz_mat4x4_init_zero`	Initializes the given matrix with all 0s for its element values.
`shz_mat4x4_init_one`	Initializes the given matrix with all 1s for its element values.
`shz_mat4x4_init_fill`	Initializes the given matrix with all elements assigned to the given value.
`shz_mat4x4_init_translation`	Initializes the given matrix to a 3D translation matrix with the given coordinates.
`shz_mat4x4_init_scale`	Initializes the given matrix to a 3D scaling matrix with the given dimensions.
`shz_mat4x4_init_rotation_x`	Initializes the given matrix to a 3D rotation matrix by `xAngle` radians over the X-axis.
`shz_mat4x4_init_rotation_y`	Initializes the given matrix to a 3D rotation matrix by `yAngle` radians over the Y-axis.
`shz_mat4x4_init_rotation_z`	Initializes the given matrix to a 3D rotation matrix by `zAngle` radians over the Z-axis.
`shz_mat4x4_init_rotation_xyz`	Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan X-Y-Z angles.
`shz_mat4x4_init_rotation_zyx`	Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan Z-Y-X angles.
`shz_mat4x4_init_rotation_zxy`	Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan Z-X-Y angles.
`shz_mat4x4_init_rotation_yxz`	Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan Y-X-Z angles.
`shz_mat4x4_init_rotation`	Initializes the given 4x4 matrix to a 3D rotation matrix of `angle` radians about the vector with the given components.
`shz_mat4x4_init_rotation_dir`	Initializes the given 4x4 matrix to contain a 3D rotation matrix of `angle` radians about the given direction.
`shz_mat4x4_init_rotation_quat`	Initializes the given matrix to a 3D rotation matrix with its orientation given by a quaternion.
`shz_mat4x4_init_diagonal`	Initializes the given matrix to a diagonal matrix with the given 4 values.
`shz_mat4x4_init_upper_triangular`	Initializes the given matrix to an upper triangular matrix whose nonzero entries have the given value.
`shz_mat4x4_init_lower_triangular`	Initializes the given matrix to a lower triangular matrix whose nonzero entries have the given value.
`shz_mat4x4_init_symmetric_skew`	Initializes the given matrix to be the symmetric skew of the given 3D vector components.
`shz_mat4x4_init_outer_product`	Initializes the given matrix to be the result from taking the outer product of the two given 4D vectors.
`shz_mat4x4_init_permutation_wxyz`	Initializes the matrix to to a permutation matrix, which reorders the components of transformed vectors to be in WXYZ order.
`shz_mat4x4_init_permutation_yzwx`	Initializes the matrix to to a permutation matrix, which reorders the components of transformed vectors to be in YZWX order.
`shz_mat4x4_init_screen`	Initializes the given matrix to the viewport matrix with the given dimenions.
`shz_mat4x4_init_lookat`	Initializes the given matrix to a "lookAt" view matrix.
`shz_mat4x4_init_ortho`	Initializes the given matrix to an orthographic projection matrix.
`shz_mat4x4_init_frustum`	Initializes the given matrix to a frustum projection matrix.
`shz_mat4x4_init_perspective`	Initializes the given matrix to a perspective projection matrix.

Decomposition

Routines for decomposing a matrix into its constituent transforms.

Symbol	Description
`shz_mat4x4_decompose`	Decomposes a 4x4 transform matrix into translation, rotation, and scale.

Getting

Routines for getting specific values within a matrix.

Symbol	Description
`shz_mat4x4_row`	Extracts the `row` index as a 4D row vector from the given matrix.
`shz_mat4x4_col`	Extracts the `col` index as a 4D column vector from the given matrix.
`shz_mat4x4_get_translation`	Returns the translational components from the 4th column as a 3D vector.
`shz_mat4x4_get_scale`	Exracts the 3D scale factors from the given 4x4 matrix.
`shz_mat4x4_determinant`	Returns the determinant of the given 4x4 matrix.
`shz_mat4x4_trace`	Returns the trace of the given 4x4 matrix.
`shz_mat4x4_3x3`	Extracts the top-left 3x3 of the given 4D matrix.
`shz_mat4x4_3x3_inverse_unscaled`	Extracts and inverts the top-level, unscaled 3x3 of the given 4x4 matrix.
`shz_mat4x4_3x3_inverse`	Extracts and inverts the top-level 3x3 (which may be scaled) of the given 4x4 matrix.
`shz_mat4x4_3x3_determinant`	Returns the determinant of the given 4x4 matrix's internal top-level 3x3 matrix.

Setting

Routines for setting specific values within a matrix

Symbol	Description
`shz_mat4x4_set_row`	Sets the values of `mat` at the given `row` to those of the 4D vector, `vec`.
`shz_mat4x4_set_col`	Sets the values of `mat` at the given `col` to those of the 4D vector, `vec`.
`shz_mat4x4_swap_rows`	Swaps the 4D row vectors located at `row1` and `row2` within `mat`.
`shz_mat4x4_swap_cols`	Swaps the 4D column vectors located at `col1` and `col2` within `mat`.
`shz_mat4x4_set_translation`	Assigns only the 3D translation-related elements of the given matrix to the given values.
`shz_mat4x4_set_scale`	Assigns only the 3D scale-related elements of the given matrix to the given values.
`shz_mat4x4_set_rotation_quat`	Sets just the rotational component of the matrix to the orientation given by a quaternion, keeping the other elements in-tact.
`shz_mat4x4_set_diagonal`	Assigns only the 4 elements along the diagonal of the given matrix to the given values.

Applying

Routines for multiplying and accumulating onto the given matrix.

Symbol	Description
`shz_mat4x4_apply`	Multiplies and accumulates the `src` 4x4 matrix onto the `dst` 4x4 matrix.
`shz_mat4x4_apply_unaligned`	Multiplies and accumulates the unaligned `src` 4x4 matrix onto the `dst` 4x4 matrix.
`shz_mat4x4_apply_transpose`	Multiplies and accumulates the transposed `src` 4x4 matrix onto the `dst` 4x4 matrix.
`shz_mat4x4_apply_transpose_unaligned`	Multiplies and accumulates the transposed unaligned `src` 4x4 matrix onto the `dst` 4x4 matrix.
`shz_mat4x4_apply_translation`	Adds the given 3D vector components to the translational values of the given matrix.
`shz_mat4x4_apply_scale`	Multiplies and accumulates the scale-related elements of the given matrix by the given 3D components.
`shz_mat4x4_apply_rotation_x`	Multiplies and accumulates a rotation matrix by `xAngle` radians about the X-axis onto the given matrix.
`shz_mat4x4_apply_rotation_y`	Multiplies and accumulates a rotation matrix by `yAngle` radians about the Y-axis onto the given matrix.
`shz_mat4x4_apply_rotation_z`	Multiplies and accumulates a rotation matrix by `zAngle` radians about the Z-axis onto the given matrix.
`shz_mat4x4_apply_rotation_xyz`	Rotates the given transform matrix about the X axis, then the Y axis, then the Z axis by the given angles in radians.
`shz_mat4x4_apply_rotation_zyx`	Rotates the given transform matrix about the Z axis, then the Y axis, then the X axis by the given angles in radians.
`shz_mat4x4_apply_rotation_zxy`	Rotates the given transform matrix about the Z axis, then the X axis, then the Y axis by the given angles in radians.
`shz_mat4x4_apply_rotation_yxz`	Rotates the given transform matrix about the Y axis, then the X axis, then the Z axis by the given angles in radians.
`shz_mat4x4_apply_rotation`	Rotates the given transform matrix about the arbitrary axis given by a 3D direction vector and angle of rotation in radians.
`shz_mat4x4_apply_rotation_quat`	Multiplies and accumulates the given matrix with a rotation matrix whose orientation is given by a quaternion.
`shz_mat4x4_apply_lookat`	Applies the 3D "lookAt" matrix constructed with the given vector components onto the given matrix.
`shz_mat4x4_apply_ortho`	Multiplies and accumulates the ortho matrix constructed from the given values onto the given matrix.
`shz_mat4x4_apply_frustum`	Multiplies and accumulates the frustum matrix constructed from the given values onto the given matrix.
`shz_mat4x4_apply_perspective`	Multiplies and accumulates the perspective matrix constructed from the given values onto the given matrix.
`shz_mat4x4_apply_screen`	Multiplies and accumulates the viewport matrix created with the given components ont othe given matrix.
`shz_mat4x4_apply_symmetric_skew`	Multiplies and accumulates the given matrix with a symmetric skew matrix formed from the given 3D vector components.
`shz_mat4x4_apply_permutation_wxyz`	Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in WXYZ order.
`shz_mat4x4_apply_permutation_yzwx`	Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in YZWX order.
`shz_mat4x4_apply_self`	Multiplies and accumulates the given matrix onto itself.

GL Transformations

OpenGL-style 4x4 matrix transforms.

Symbol	Description
`shz_mat4x4_translate`	Multiplies and accumulates `mat` by a 3D translation matrix with the given components.
`shz_mat4x4_scale`	Multiplies and accumulates `mat` by a 3D scaling matrix with the given components.
`shz_mat4x4_rotate_x`	Multiplies and accumulates `mat` by a 3D rotation matrix about the X axis.
`shz_mat4x4_rotate_y`	Multiplies and accumulates `mat` by a 3D rotation matrix about the Y axis.
`shz_mat4x4_rotate_z`	Multiplies and accumulates `mat` by a 3D rotation matrix about the Z axis.
`shz_mat4x4_rotate_xyz`	Multiplies and accumulates `mat` by 3D rotation matrices about the X then Y then Z axes.
`shz_mat4x4_rotate_zyx`	Multiplies and accumulates `mat` by 3D rotation matrices about the Z then Y then X axes.
`shz_mat4x4_rotate_zxy`	Multiplies and accumulates `mat` by 3D rotation matrices about the Z then X then Y axes.
`shz_mat4x4_rotate_yxz`	Multiplies and accumulates `mat` by 3D rotation matrices about the Y then X then Z axes.
`shz_mat4x4_rotate`	Multiplies and accumulates `mat` by the 3D rotation matrix formed by the given axis and angle.

Reverse GL Transformations

Pre-multiplication variants of OpenGL-style 4x4 matrix transforms.

Symbol	Description
`shz_mat4x4_translate_reverse`	Pre-multiplies and accumulates the given matrix onto the 3D translation matrix with the given components.
`shz_mat4x4_scale_reverse`	Pre-multiplies and accumulates the given matrix onto the 3D scaling matrix with the given components.

Transforming

Routines for transforming vectors and points by a matrix.

Symbol	Description
`shz_mat4x4_mult`	Multiplies two 4x4 matrices together, storing the result into a third.
`shz_mat4x4_mult_unaligned`	Multiplies two 4x4 matrices together, with the right handed matrix being unaligned, storing the result into a third.
`shz_mat4x4_mult_transpose`	Multiplies the regular matrix, `lhs`, by the transpose of the matrix, `rhs`, storing the result into `mat`.
`shz_mat4x4_mult_transpose_unaligned`	Multiplies the regular matrix, `lhs`, by the transpose of the unaligned matrix, `rhs`, storing the result into `mat`.
`shz_mat4x4_transform_vec2`	Transforms a 2D vector by a 4x4 matrix.
`shz_mat4x4_transform_vec3`	Transforms a 3D vector by a 4x4 matrix.
`shz_mat4x4_transform_vec4`	Transforms a 4D vector by a 4x4 matrix.
`shz_mat4x4_transform_vec2_transpose`	Transforms a 2D vector the the transpose of a 4x4 matrix.
`shz_mat4x4_transform_vec3_transpose`	Transforms a 3D vector the the transpose of a 4x4 matrix.
`shz_mat4x4_transform_vec4_transpose`	Transforms a 4D vector the the transpose of a 4x4 matrix.
`shz_mat4x4_transform_point2`	Transforms a 2D point by a 4x4 matrix.
`shz_mat4x4_transform_point3`	Transforms a 3D point by a 4x4 matrix.
`shz_mat4x4_transform_point2_transpose`	Transforms a 2D point by the transpose of a 4x4 matrix.
`shz_mat4x4_transform_point3_transpose`	Transforms a 3D point by the transpose of a 4x4 matrix.

Miscellaneous

Other matrix-related operations and routines

Symbol	Description
`shz_mat4x4_to_quat`	Converts the given 4x4 orientation matrix into a quaternion.
`shz_mat4x4_transpose`	Stores the transpose of `mat` within `out`.
`shz_mat4x4_inverse`	Computes the inverse of a 4x4 matrix.
`shz_mat4x4_inverse_block_triangular`	Computes the inverse of a 4x4 matrix in block-triangular form.
`shz_mat4x4_equal`	Returns true if the two matrices are equal, based on either absolute or relative tolerance.
`shz_mat4x4_is_block_triangular`	Returns true if the given matrix is in block-triangular form: having a bottom row in the form of `<0.0f, 0.0f, 0.0f, w>`.
`shz_mat4x4_copy`	Copies the given `src` 4x4 matrix into the given `dst` 4x4 matrix.
`shz_mat4x4_copy_unaligned`	Copies the given unaligned `src` 4x4 matrix into the given `dst` 4x4 matrix.
`shz_mat4x4_swap`	Swaps the contents of the two given matrices, `matA` and `matB`.
`shz_mat4x4_blend`	Adds and accumulates a scaled 4x4 matrix into the given matrix.

Types

Symbol	Description
`shz_mat4x4_t`	Structure representing a 4x4 column-major matrix.
`shz_mat4x4`	Alternate `shz_mat4x4_t` C typedef for those who hate POSIX style.
`shz_mat2x2_t`	Structure representing a 2x2 column-major matrix.
`shz_mat3x3_t`	Structure representing a 3x3 column-major matrix.
`shz_mat3x4_t`	Structure representing a 3x4 column-major matrix.
`shz_mat4x3_t`	Structure representing a 4x3 column-major matrix.

Functions

Symbol	Description
`shz_mat3x3_transpose`	Stores the transpose of 3x3 matrix `mat` within `out`.
`shz_mat3x3_inverse_unscaled`	Computes the inverse of an orthonormal 3x3 matrix.
`shz_mat3x3_inverse`	Computes the inverse of a 3x3 matrix.
`shz_mat3x3_scale`	Uniformly scales each element within a 3x3 matrix by the given value.
`shz_mat3x3_transform_vec3`	Transforms an input vector by a 3x3 matrix, returning the resulting vector.
`shz_mat3x3_transform_vec3_transpose`	Transforms an input vector by the transpose of a 3x3 matrix, returning the resulting vector.