# XMTRX API Source: https://sh4zam.com/api/xmtrx/ > API for managing the SH4's "active matrix", the 16 back-bank FP registers `XMTRX` is the name given to identify the 16 FP registers contained within the back-bank of the SH4's FPU. These 16 registers combine to represent the SH4's 4x4 "active matrix", which can be subsequently transformed against using the `FTRV` instruction (`shz_xmtrx_transform_vec4()`). For maximum FP performance on the SH4, strategic usage of `XMTRX` to batch transform operations together without having to reload FP registers is key. Typically, for one-off operations, the in-memory Matrix API is what should be used; however, when operations can be batched, using `XMTRX` to hold your matrix within registers is going to give the best performance. Unless TLS has been disabled, the XMTRX API is thread-safe, with each thread getting its own unique copy of XMTRX. - **C header:** `#include ` - **C++ header:** `#include ` - **C++ types:** [`shz::xmtrx`](https://sh4zam.com/api/cpp/xmtrx/) - **Symbols:** 140 ## 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](https://sh4zam.com/concepts/naming-and-suffixes/). - `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. - `_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). - `_reverse`: Reversed multiplication order (pre-multiply instead of post-multiply). - `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ## Accessors Setting and retrieving individual XMTRX register values. | Symbol | Description | | --- | --- | | [`shz_xmtrx_read`](https://sh4zam.com/api/xmtrx/shz_xmtrx_read/) | Returns the floating-point value held within the given XMTRX register. | | [`shz_xmtrx_write`](https://sh4zam.com/api/xmtrx/shz_xmtrx_write/) | Sets the floating-point value held within the given XMTRX register to `value`. | | [`shz_xmtrx_read_row`](https://sh4zam.com/api/xmtrx/shz_xmtrx_read_row/) | Returns the values at the the given row `index`, as a 4D vector. | | [`shz_xmtrx_read_col`](https://sh4zam.com/api/xmtrx/shz_xmtrx_read_col/) | Returns the values at the given column `index`, as a 4D vector. | | [`shz_xmtrx_write_row`](https://sh4zam.com/api/xmtrx/shz_xmtrx_write_row/) | Sets the values at the given row `index` to the given 4D vector. | | [`shz_xmtrx_write_col`](https://sh4zam.com/api/xmtrx/shz_xmtrx_write_col/) | Sets the values at the given column `index` to the given 4D vector. | | [`shz_xmtrx_swap_rows`](https://sh4zam.com/api/xmtrx/shz_xmtrx_swap_rows/) | Swaps the values of the rows with the given indices. | | [`shz_xmtrx_swap_cols`](https://sh4zam.com/api/xmtrx/shz_xmtrx_swap_cols/) | Swaps the values of the columns with the given indices. | ## Loading Routines for loading XMTRX contents from memory. | Symbol | Description | | --- | --- | | [`shz_xmtrx_load_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_4x4/) | Loads the given 4x4 matrix as XMTRX. | | [`shz_xmtrx_load_wxyz_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_wxyz_4x4/) | Loads the given 4x4 matrix as XMTRX, with the 4th column for translation being loaded as the first column. | | [`shz_xmtrx_load_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_unaligned_4x4/) | Loads the given array of unaligned 16 float values as the 4x4 XMTRX matrix. | | [`shz_xmtrx_load_cols_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_cols_4x4/) | Sets XMTRX equal to the 4x4 matrix created from the 4 given 4D column vectors. | | [`shz_xmtrx_load_rows_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_rows_4x4/) | Sets XMTRX equal to the 4x4 matrix created from the 4 given 4D row vectors. | | [`shz_xmtrx_load_transpose_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_4x4/) | Loads XMTRX with the transpose of the given 4x4 matrix. | | [`shz_xmtrx_load_transpose_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_unaligned_4x4/) | Loads XMTRX with the transpose of the 4x4 matrix created from the given unaligned array of 16 floats. | | [`shz_xmtrx_load_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x4/) | Loads the given 3x4 matrix into XMTRX, initializing its remaining elements to identity. | | [`shz_xmtrx_load_transpose_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_3x4/) | Loads XMTRX with the transpose of the given 3x4 matrix, initializing the bottom row to identity. | | [`shz_xmtrx_load_cols_4x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_cols_4x3/) | Loads the 3x4 matrix formed from the given 3 4D column vectors into XMTRX. | | [`shz_xmtrx_load_rows_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_rows_3x4/) | Loads the 3x4 matrix formed from the given 3 4D row vectors into XMTRX. | | [`shz_xmtrx_load_cols_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_cols_3x4/) | Loads the 3x4 matrix formed from the given 4 3D column vectors into XMTRX. | | [`shz_xmtrx_load_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x3/) | Loads the given 3x3 matrix into XMTRX, initalizing its remaining elements to identity. | | [`shz_xmtrx_load_transpose_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_3x3/) | Loads the transpose of the given 3x3 matrix into XMTRX, initializing its remaining elements to identity. | | [`shz_xmtrx_load_2x2`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_2x2/) | Loads the given 2x2 matrix into XMTRX, initializing its remaining elements to identity. | ## Storing Routines for saving XMTRX contents to memory. | Symbol | Description | | --- | --- | | [`shz_xmtrx_store_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_4x4/) | Stores the current values held within XMTRX into the given 4x4 matrix. | | [`shz_xmtrx_store_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_unaligned_4x4/) | Stores the current values held within XMTRX into the given unaligned 16-float array. | | [`shz_xmtrx_store_transpose_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_4x4/) | Stores the transpose of the current values held within XMTRX into the given 4x4 matrix. | | [`shz_xmtrx_store_transpose_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_unaligned_4x4/) | Stores the transpose of the the current values held within XMTRX into the given 16-element float array. | | [`shz_xmtrx_store_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_3x4/) | Stores the top-left 3x4 values currently held within XMTRX into the given matrix. | | [`shz_xmtrx_store_transpose_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_3x4/) | Stores the transpose of the top-left 3x4 values currently held within XMTRX into the given matrix. | | [`shz_xmtrx_store_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_3x3/) | Stores the top-left 3x3 values currently held within XMTRX into the given matrix. | | [`shz_xmtrx_store_transpose_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_3x3/) | Stores the transpose of the top-left 3x3 values currently held within XMTRX into the given matrix. | | [`shz_xmtrx_store_2x2`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_2x2/) | Stores the top-left 2x2 values currently held within XMTRX into the given matrix. | ## Initialization Routines used to initialize the entirety of XMTRX. | Symbol | Description | | --- | --- | | [`shz_xmtrx_init_identity`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_identity/) | Initializes XMTRX to the 4x4 identity matrix. | | [`shz_xmtrx_init_identity_safe`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_identity_safe/) | Safely initializes XMTRX to be a 4D identity matrix. | | [`shz_xmtrx_init_zero`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_zero/) | Initializes XMTRX to contain the value of 0.0f for each element. | | [`shz_xmtrx_init_one`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_one/) | Initializes XMTRX to contain the value of 1.0f for each element. | | [`shz_xmtrx_init_fill`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_fill/) | Initializes XMTRX to contain the given `value` for each element. | | [`shz_xmtrx_init_translation`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_translation/) | Initializes XMTRX to be a 3D translation matrix to the given coordinates. | | [`shz_xmtrx_init_scale`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_scale/) | Initializes XMTRX to be a 3D scale matrix with the given dimensions. | | [`shz_xmtrx_init_rotation_x`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_x/) | Initializes XMTRX to be a 3D rotation matrix by `x` radians about the X axis. | | [`shz_xmtrx_init_rotation_y`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_y/) | Initializes XMTRX to be a 3D rotation matrix by `y` radians about the Y axis. | | [`shz_xmtrx_init_rotation_z`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_z/) | Initializes XMTRX to be a 3D rotation matrix by `z` radians about the Z axis. | | [`shz_xmtrx_init_rotation_xyz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_xyz/) | Initializes XMTRX to be a 3D X-Y-Z rotation matrix, with the corresponding angles given in radians. | | [`shz_xmtrx_init_rotation_zyx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_zyx/) | Initializes XMTRX to be a 3D Z-Y-X rotation matrix, with the corresponding angles given in radians. | | [`shz_xmtrx_init_rotation_zxy`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_zxy/) | Initializes XMTRX to be a 3D Z-X-Y rotation matrix, with the corresponding angles given in radians. | | [`shz_xmtrx_init_rotation_yxz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_yxz/) | Initializes XMTRX to be a 3D Y-X-Z rotation matrix, with the corresponding angles given in radians. | | [`shz_xmtrx_init_rotation`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation/) | Initializes XMTRX to a 3D rotation matrix of `angle` radians about the vector with the given components. | | [`shz_xmtrx_init_rotation_dir`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_dir/) | Initializes XMTRX to contain a 3D rotation matrix of `angle` radians about the given `axis`. | | [`shz_xmtrx_init_diagonal`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_diagonal/) | Initializes XMTRX to be a diagonal matrix with the given diagonal values. | | [`shz_xmtrx_init_upper_triangular`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_upper_triangular/) | Initializes XMTRX to be an upper triangular matrix with the given column values. | | [`shz_xmtrx_init_lower_triangular`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_lower_triangular/) | Initializes XMTRX to be a lower triangular matrix with the given column values. | | [`shz_xmtrx_init_symmetric_skew`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_symmetric_skew/) | Initializes XMTRX to be the 3D symmetric skew matrix formed from the given vector components. | | [`shz_xmtrx_init_outer_product`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_outer_product/) | Initializes XMTRX to the 4D matrix resulting from taking the outer product of the two 4D vectors. | | [`shz_xmtrx_init_permutation_wxyz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_permutation_wxyz/) | Initializes XMTRX to a permutation matrix, which reorders the components of transformed vectors to be in WXYZ order. | | [`shz_xmtrx_init_permutation_yzwx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_permutation_yzwx/) | Initializes XMTRX to a permutation matrix, which reorders the components of transformed vectors to be in YZWX order. | | [`shz_xmtrx_init_permutation_wzyx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_permutation_wzyx/) | Initializes XMTRX to a permutation matrix, which reorders the components of transformed vectors to be in WZYX order. | | [`shz_xmtrx_init_screen`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_screen/) | Initializes XMTRX to the viewport matrix with the given dimensions. | | [`shz_xmtrx_init_lookat`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_lookat/) | Initializes XMTRX to a "lookAt" view matrix, equivalent to gluLookAt(). | | [`shz_xmtrx_init_ortho`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_ortho/) | Initializes XMTRX to an orthographic projection matrix, equivalent to glOrtho(). | | [`shz_xmtrx_init_frustum`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_frustum/) | Initializes XMTRX to a frustum projection matrix, equivalent to glFrustum(). | | [`shz_xmtrx_init_perspective`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_perspective/) | Initializes XMTRX to a perspective projection matrix. | | [`shz_xmtrx_init_rotation_quat`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_quat/) | Initializes XMTRX to a 3D rotation matrix with its orientation given by a quaternion. | ## Apply Operation Updates only relevant values of XMTRX based on the given transform. | Symbol | Description | | --- | --- | | [`shz_xmtrx_apply_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_4x4/) | Multiplies and accumulates the given 4x4 matrix onto XMTRX. | | [`shz_xmtrx_apply_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_unaligned_4x4/) | Multiplies and accumulates the given 16-entry float array as a 4x4 matrix onto XMTRX. | | [`shz_xmtrx_apply_transpose_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_4x4/) | Multiplies and accumulates the transpose of the given 4x4 matrix onto XMTRX. | | [`shz_xmtrx_apply_transpose_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_unaligned_4x4/) | Multiplies and accumulates the transpose of the given 16-entry float array as a 4x4 matrix onto XMTRX. | | [`shz_xmtrx_apply_reverse_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_4x4/) | Multiplies and accumulates XMTRX onto `matrix`, storing the result as XMTRX. | | [`shz_xmtrx_apply_reverse_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_unaligned_4x4/) | Multiplies and accumulates XMTRX onto the given float array as a 4x4 matrix, storing the result as XMTRX. | | [`shz_xmtrx_apply_reverse_transpose_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_transpose_4x4/) | Multiplies and accumulates XMTRX onto the transpose of `matrix`, storing the result as XMTRX. | | [`shz_xmtrx_apply_reverse_transpose_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_transpose_unaligned_4x4/) | Multiplies and accumulates XMTRX onto the transpose of the given float array as a 4x4 matrix, storing the result as XMTRX. | | [`shz_xmtrx_apply_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x4/) | Multiplies and accumulates the given 3x4 matrix onto XMTRX, not modifying other elements. | | [`shz_xmtrx_apply_transpose_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_3x4/) | Multiplies and accumulates the transpose of the given 3x4 matrix onto XMTRX, not modifying other elements. | | [`shz_xmtrx_apply_reverse_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_3x4/) | Multiplies and accumulates XMTRX onto `matrix`, storing the result as XMTRX. | | [`shz_xmtrx_apply_reverse_transpose_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_transpose_3x4/) | Multiplies and accumulates XMTRX onto the transpose of `matrix`, storing the result as XMTRX. | | [`shz_xmtrx_apply_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x3/) | Multiplies and accumulates the given 3x3 matrix onto XMTRX, not modifying other elements. | | [`shz_xmtrx_apply_transpose_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_3x3/) | Multiplies and accumulates the transpose of the given 3x3 matrix onto XMTRX, not modifying other elements. | | [`shz_xmtrx_apply_2x2`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_2x2/) | Multiplies and accumulates the given 2x2 matrix onto XMTRX, not modifying other elements. | | [`shz_xmtrx_apply_translation`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_translation/) | Adds the values of the given 3 components to the 3D translation components of XMTRX. | | [`shz_xmtrx_apply_scale`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_scale/) | Multiplies the values of the inner 3x3 matrix by the given 3D scaling terms. | | [`shz_xmtrx_apply_rotation_x`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_x/) | Transforms the values of the inner 3x3 matrix by a rotation matrix of `x` radians about the X axis. | | [`shz_xmtrx_apply_rotation_y`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_y/) | Transforms the values of the inner 3x3 matrix by a rotation matrix of `y` radians about the Y axis. | | [`shz_xmtrx_apply_rotation_z`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_z/) | Transforms the values of the inner 3x3 matrix by a rotation matrix of `z` radians about the Z axis. | | [`shz_xmtrx_apply_rotation_xyz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_xyz/) | Multiplies and accumulates XMTRX by a 3D X-Y-Z rotation matrix, with the corresponding angles given in radians. | | [`shz_xmtrx_apply_rotation_zyx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_zyx/) | Multiplies and accumulates XMTRX by a 3D Z-Y-X rotation matrix, with the corresponding angles given in radians. | | [`shz_xmtrx_apply_rotation_zxy`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_zxy/) | Multiplies and accumulates XMTRX by a 3D Z-X-Y rotation matrix, with the corresponding angles given in radians. | | [`shz_xmtrx_apply_rotation_yxz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_yxz/) | Multiplies and accumulates XMTRX by a 3D Y-X-Z rotation matrix, with the corresponding angles given in radians. | | [`shz_xmtrx_apply_rotation`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation/) | Transforms the values of the inner 3x3 matrix by a rotation matrix of `angle` radians about the axis with the given components. | | [`shz_xmtrx_apply_rotation_quat`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_quat/) | Transforms the values of the inner 3x3 matrix by the rotation matrix represented by the given quaternion. | | [`shz_xmtrx_apply_lookat`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_lookat/) | Applies the 3D "lookAt" matrix constructed with the given vector components onto XMTRX. Equivalent to gluLookAt(). | | [`shz_xmtrx_apply_ortho`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_ortho/) | Applies a 2D orthographic projection matrix onto XMTRX, equivalent to glOrtho(). | | [`shz_xmtrx_apply_frustum`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_frustum/) | Applies a frustum projection matrix onto XMTRX, equivalent to glFrustum(). | | [`shz_xmtrx_apply_perspective`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_perspective/) | Multiplies and accumulates the perspective matrix constructed from the given values onto XMTRX. | | [`shz_xmtrx_apply_screen`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_screen/) | Multiplies and accumulates the viewport matrix created with the given components. | | [`shz_xmtrx_apply_symmetric_skew`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_symmetric_skew/) | Multiplies and accumulates the 3D symmetric skew matrix with the given components onto XMTRX. | | [`shz_xmtrx_apply_permutation_wxyz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_permutation_wxyz/) | Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in WXYZ order. | | [`shz_xmtrx_apply_permutation_yzwx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_permutation_yzwx/) | Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in YZWX order. | | [`shz_xmtrx_apply_permutation_wzyx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_permutation_wzyx/) | Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in WZYX order. | | [`shz_xmtrx_apply_self`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_self/) | Multiplies and accumulatse the XMTRX matrix by itself, squaring it. | ## GL Transformations OpenGL-style 4x4 matrix transforms. | Symbol | Description | | --- | --- | | [`shz_xmtrx_translate`](https://sh4zam.com/api/xmtrx/shz_xmtrx_translate/) | Multiplies and accumulates XMTRX by a 3D translation matrix with the given components (glTranslatef() equivalent). | | [`shz_xmtrx_scale`](https://sh4zam.com/api/xmtrx/shz_xmtrx_scale/) | Multiplies and accumulates XMTRX by a 3D scaling matrix with the given components (glScalef() equivalent). | | [`shz_xmtrx_rotate_x`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_x/) | Multiplies and accumulates XMTRX by a 3D rotation matrix about the X axis. | | [`shz_xmtrx_rotate_y`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_y/) | Multiplies and accumulates XMTRX by a 3D rotation matrix about the Y axis. | | [`shz_xmtrx_rotate_z`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_z/) | Multiplies and accumulates XMTRX by a 3D rotation matrix about the Z axis. | | [`shz_xmtrx_rotate_xyz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_xyz/) | Multiplies and accumulates XMTRX by 3D rotation matrices about the X then Y then Z axes. | | [`shz_xmtrx_rotate_zyx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_zyx/) | Multiplies and accumulates XMTRX by 3D rotation matrices about the Z then Y then X axes. | | [`shz_xmtrx_rotate_zxy`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_zxy/) | Multiplies and accumulates XMTRX by 3D rotation matrices about the Z then X then Y axes. | | [`shz_xmtrx_rotate_yxz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_yxz/) | Multiplies and accumulates XMTRX by 3D rotation matrices about the Y then X then Z axes. | | [`shz_xmtrx_rotate`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate/) | Multiplies and accumulates XMTRX by the 3D rotation matrix formed by the given axis and angle (glRotatef equivalent). | ## Reverse GL Transformations Pre-multiplication variants of OpenGL-style 4x4 matrix transforms. | Symbol | Description | | --- | --- | | [`shz_xmtrx_translate_reverse`](https://sh4zam.com/api/xmtrx/shz_xmtrx_translate_reverse/) | Pre-multiplies and accumulates XMTRX onto the 3D translation matrix with the given components. | | [`shz_xmtrx_scale_reverse`](https://sh4zam.com/api/xmtrx/shz_xmtrx_scale_reverse/) | Pre-multiplies and accumulates XMTRX onto the 3D scaling matrix with the given components. | ## Compound Operations Multiple operations combined into one pipelined transaction. | Symbol | Description | | --- | --- | | [`shz_xmtrx_load_apply_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_4x4/) | Loads XMTRX with the result of applying `matrix2` onto `matrix1`. | | [`shz_xmtrx_load_apply_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_unaligned_4x4/) | Loads XMTRX with the result of applying unaligned `matrix2` onto `matrix1`. | | [`shz_xmtrx_apply_store_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_store_4x4/) | Multiplies XMTRX by the matrix, `in`, storing the result within the matrix, `out`. | | [`shz_xmtrx_apply_store_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_store_unaligned_4x4/) | Multiplies XMTRX by the unaligned matrix, `in`, storing the result within the unaligned matrix, `out`. | | [`shz_xmtrx_load_apply_store_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_4x4/) | Loads XMTRX with the 4x4 result of applying `matrix2` onto `matrix1`, storing the result. | | [`shz_xmtrx_load_apply_store_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_unaligned_4x4/) | Loads XMTRX with the result of applying unaligned `matrix2` onto unaligned `matrix1`, storing the result. | | [`shz_xmtrx_load_apply_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_3x4/) | Loads XMTRX with the result of applying `matrix2` onto `matrix1`. | | [`shz_xmtrx_load_apply_store_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_3x4/) | Loads XMTRX with the 3x4 result of applying `matrix2` onto `matrix1`, storing the result. | | [`shz_xmtrx_load_apply_store_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_3x3/) | Loads XMTRX with the 3x3 result of applying `matrix2` onto `matrix1`, storing the result. | ## Transformations Transforming vectors and points against XMTRX. | Symbol | Description | | --- | --- | | [`shz_xmtrx_transform_vec4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec4/) | Returns the 4D vector that is the result of transforming `vec` by XMTRX. | | [`shz_xmtrx_transform_vec3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec3/) | Returns the 3D vector that is the result of transforming `vec` by XMTRX. | | [`shz_xmtrx_transform_vec2`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec2/) | Returns the 2D vector that is the result of transforming `vec` by XMTRX. | | [`shz_xmtrx_transform_point2`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_point2/) | Returns the 2D point that is the result of transforming `pt` by XMTRX. | | [`shz_xmtrx_transform_point3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_point3/) | Returns the 3D point that is the result of transforming `pt` by XMTRX. | ## Setters Sets the values of related XMTRX components. | Symbol | Description | | --- | --- | | [`shz_xmtrx_set_translation`](https://sh4zam.com/api/xmtrx/shz_xmtrx_set_translation/) | Sets only the translational components of XMTRX to the given values. | | [`shz_xmtrx_set_scale`](https://sh4zam.com/api/xmtrx/shz_xmtrx_set_scale/) | Sets only the inner 3x3 submatrix of XMTRX to be a scaling matrix. | ## Getters Gets the values of related XMTRX components. | Symbol | Description | | --- | --- | | [`shz_xmtrx_get_translation`](https://sh4zam.com/api/xmtrx/shz_xmtrx_get_translation/) | Returns the translational components from the last column of XMTRX, as a 3D vector. | | [`shz_xmtrx_get_scale`](https://sh4zam.com/api/xmtrx/shz_xmtrx_get_scale/) | Returns the scaling components from the inner 3x3 matrix of XMTRX, as a 3D vector. | ## Component-Wise Matrix Operations Operations applying each component of a matrix onto XMTRX. | Symbol | Description | | --- | --- | | [`shz_xmtrx_add_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_add_4x4/) | Adds each element within `mat` to each element within XMTRX, storing the result in XMTRX. | | [`shz_xmtrx_sub_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_sub_4x4/) | Subtracts each element within `mat` from each element within XMTRX, storing the result in XMTRX. | ## Miscellaneous Random operations and conversions on XMTRX. | Symbol | Description | | --- | --- | | [`shz_xmtrx_transpose`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transpose/) | Transposes the elements within XMTRX, in-place. | | [`shz_xmtrx_negate`](https://sh4zam.com/api/xmtrx/shz_xmtrx_negate/) | Negates each element held within XMTRX. | | [`shz_xmtrx_abs`](https://sh4zam.com/api/xmtrx/shz_xmtrx_abs/) | Takes the absolute value of each element held within XMTRX. | | [`shz_xmtrx_to_quat`](https://sh4zam.com/api/xmtrx/shz_xmtrx_to_quat/) | Constructs a quaternion from the 3D rotation matrix within XMTRX. | | [`shz_xmtrx_determinant`](https://sh4zam.com/api/xmtrx/shz_xmtrx_determinant/) | Returns the determinant of XMTRX. | | [`shz_xmtrx_invert`](https://sh4zam.com/api/xmtrx/shz_xmtrx_invert/) | Inverts XMTRX in-place. | | [`shz_xmtrx_blend`](https://sh4zam.com/api/xmtrx/shz_xmtrx_blend/) | Deprecated way to add and accumulate a scaled 4x4 matrix onto XMTRX. | | [`shz_xmtrx_blend_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_blend_4x4/) | Adds and accumulates a scaled 4x4 matrix onto XMTRX. | | [`shz_xmtrx_blend_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_blend_3x4/) | Adds and accumulates a scaled 3x4 matrix onto XMTRX. | ## Enumerations | Symbol | Description | | --- | --- | | [`shz_xmtrx_reg`](https://sh4zam.com/api/xmtrx/shz_xmtrx_reg/) | Registers comprising XMTRX, in the FPU back-bank. |