XMTRX API

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 <sh4zam/shz_xmtrx.h>
• C++ header: #include <sh4zam/shz_xmtrx.hpp>
• C++ types: shz::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.

• _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	Returns the floating-point value held within the given XMTRX register.
shz_xmtrx_write	Sets the floating-point value held within the given XMTRX register to value.
shz_xmtrx_read_row	Returns the values at the the given row index, as a 4D vector.
shz_xmtrx_read_col	Returns the values at the given column index, as a 4D vector.
shz_xmtrx_write_row	Sets the values at the given row index to the given 4D vector.
shz_xmtrx_write_col	Sets the values at the given column index to the given 4D vector.
shz_xmtrx_swap_rows	Swaps the values of the rows with the given indices.
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	Loads the given 4x4 matrix as 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	Loads the given array of unaligned 16 float values as the 4x4 XMTRX matrix.
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	Sets XMTRX equal to the 4x4 matrix created from the 4 given 4D row vectors.
shz_xmtrx_load_transpose_4x4	Loads XMTRX with the transpose of the given 4x4 matrix.
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	Loads the given 3x4 matrix into XMTRX, initializing its remaining elements to identity.
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	Loads the 3x4 matrix formed from the given 3 4D column vectors into 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	Loads the 3x4 matrix formed from the given 4 3D column vectors into XMTRX.
shz_xmtrx_load_3x3	Loads the given 3x3 matrix into XMTRX, initalizing its remaining elements to identity.
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	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	Stores the current values held within XMTRX into the given 4x4 matrix.
shz_xmtrx_store_unaligned_4x4	Stores the current values held within XMTRX into the given unaligned 16-float array.
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	Stores the transpose of the the current values held within XMTRX into the given 16-element float array.
shz_xmtrx_store_3x4	Stores the top-left 3x4 values currently held within XMTRX into the given matrix.
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	Stores the top-left 3x3 values currently held within XMTRX into the given matrix.
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	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	Initializes XMTRX to the 4x4 identity matrix.
shz_xmtrx_init_identity_safe	Safely initializes XMTRX to be a 4D identity matrix.
shz_xmtrx_init_zero	Initializes XMTRX to contain the value of 0.0f for each element.
shz_xmtrx_init_one	Initializes XMTRX to contain the value of 1.0f for each element.
shz_xmtrx_init_fill	Initializes XMTRX to contain the given value for each element.
shz_xmtrx_init_translation	Initializes XMTRX to be a 3D translation matrix to the given coordinates.
shz_xmtrx_init_scale	Initializes XMTRX to be a 3D scale matrix with the given dimensions.
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	Initializes XMTRX to be a 3D rotation matrix by y radians about the Y axis.
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	Initializes XMTRX to be a 3D X-Y-Z rotation matrix, with the corresponding angles given in radians.
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	Initializes XMTRX to be a 3D Z-X-Y rotation matrix, with the corresponding angles given in radians.
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	Initializes XMTRX to a 3D rotation matrix of angle radians about the vector with the given components.
shz_xmtrx_init_rotation_dir	Initializes XMTRX to contain a 3D rotation matrix of angle radians about the given axis.
shz_xmtrx_init_diagonal	Initializes XMTRX to be a diagonal matrix with the given diagonal values.
shz_xmtrx_init_upper_triangular	Initializes XMTRX to be an upper triangular matrix with the given column values.
shz_xmtrx_init_lower_triangular	Initializes XMTRX to be a lower triangular matrix with the given column values.
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	Initializes XMTRX to the 4D matrix resulting from taking the outer product of the two 4D vectors.
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	Initializes XMTRX to a permutation matrix, which reorders the components of transformed vectors to be in YZWX order.
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	Initializes XMTRX to the viewport matrix with the given dimensions.
shz_xmtrx_init_lookat	Initializes XMTRX to a "lookAt" view matrix, equivalent to gluLookAt().
shz_xmtrx_init_ortho	Initializes XMTRX to an orthographic projection matrix, equivalent to glOrtho().
shz_xmtrx_init_frustum	Initializes XMTRX to a frustum projection matrix, equivalent to glFrustum().
shz_xmtrx_init_perspective	Initializes XMTRX to a perspective projection matrix.
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	Multiplies and accumulates the given 4x4 matrix onto 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	Multiplies and accumulates the transpose of the given 4x4 matrix onto 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	Multiplies and accumulates XMTRX onto matrix, storing the result as 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	Multiplies and accumulates XMTRX onto the transpose of matrix, storing the result as 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	Multiplies and accumulates the given 3x4 matrix onto XMTRX, not modifying other elements.
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	Multiplies and accumulates XMTRX onto matrix, storing the result as 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	Multiplies and accumulates the given 3x3 matrix onto XMTRX, not modifying other elements.
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	Multiplies and accumulates the given 2x2 matrix onto XMTRX, not modifying other elements.
shz_xmtrx_apply_translation	Adds the values of the given 3 components to the 3D translation components of XMTRX.
shz_xmtrx_apply_scale	Multiplies the values of the inner 3x3 matrix by the given 3D scaling terms.
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	Transforms the values of the inner 3x3 matrix by a rotation matrix of y radians about the Y axis.
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	Multiplies and accumulates XMTRX by a 3D X-Y-Z rotation matrix, with the corresponding angles given in radians.
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	Multiplies and accumulates XMTRX by a 3D Z-X-Y rotation matrix, with the corresponding angles given in radians.
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	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	Transforms the values of the inner 3x3 matrix by the rotation matrix represented by the given quaternion.
shz_xmtrx_apply_lookat	Applies the 3D "lookAt" matrix constructed with the given vector components onto XMTRX. Equivalent to gluLookAt().
shz_xmtrx_apply_ortho	Applies a 2D orthographic projection matrix onto XMTRX, equivalent to glOrtho().
shz_xmtrx_apply_frustum	Applies a frustum projection matrix onto XMTRX, equivalent to glFrustum().
shz_xmtrx_apply_perspective	Multiplies and accumulates the perspective matrix constructed from the given values onto XMTRX.
shz_xmtrx_apply_screen	Multiplies and accumulates the viewport matrix created with the given components.
shz_xmtrx_apply_symmetric_skew	Multiplies and accumulates the 3D symmetric skew matrix with the given components onto 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	Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in YZWX order.
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	Multiplies and accumulatse the XMTRX matrix by itself, squaring it.

GL Transformations

OpenGL-style 4x4 matrix transforms.

Symbol	Description
shz_xmtrx_translate	Multiplies and accumulates XMTRX by a 3D translation matrix with the given components (glTranslatef() equivalent).
shz_xmtrx_scale	Multiplies and accumulates XMTRX by a 3D scaling matrix with the given components (glScalef() equivalent).
shz_xmtrx_rotate_x	Multiplies and accumulates XMTRX by a 3D rotation matrix about the X axis.
shz_xmtrx_rotate_y	Multiplies and accumulates XMTRX by a 3D rotation matrix about the Y axis.
shz_xmtrx_rotate_z	Multiplies and accumulates XMTRX by a 3D rotation matrix about the Z axis.
shz_xmtrx_rotate_xyz	Multiplies and accumulates XMTRX by 3D rotation matrices about the X then Y then Z axes.
shz_xmtrx_rotate_zyx	Multiplies and accumulates XMTRX by 3D rotation matrices about the Z then Y then X axes.
shz_xmtrx_rotate_zxy	Multiplies and accumulates XMTRX by 3D rotation matrices about the Z then X then Y axes.
shz_xmtrx_rotate_yxz	Multiplies and accumulates XMTRX by 3D rotation matrices about the Y then X then Z axes.
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	Pre-multiplies and accumulates XMTRX onto the 3D translation matrix with the given components.
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	Loads XMTRX with the result of applying matrix2 onto matrix1.
shz_xmtrx_load_apply_unaligned_4x4	Loads XMTRX with the result of applying unaligned matrix2 onto matrix1.
shz_xmtrx_apply_store_4x4	Multiplies XMTRX by the matrix, in, storing the result within the matrix, out.
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	Loads XMTRX with the 4x4 result of applying matrix2 onto matrix1, storing the result.
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	Loads XMTRX with the result of applying matrix2 onto matrix1.
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	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	Returns the 4D vector that is the result of transforming vec by XMTRX.
shz_xmtrx_transform_vec3	Returns the 3D vector that is the result of transforming vec by XMTRX.
shz_xmtrx_transform_vec2	Returns the 2D vector that is the result of transforming vec by XMTRX.
shz_xmtrx_transform_point2	Returns the 2D point that is the result of transforming pt by 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	Sets only the translational components of XMTRX to the given values.
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	Returns the translational components from the last column of XMTRX, as a 3D vector.
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	Adds each element within mat to each element within XMTRX, storing the result in 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	Transposes the elements within XMTRX, in-place.
shz_xmtrx_negate	Negates each element held within XMTRX.
shz_xmtrx_abs	Takes the absolute value of each element held within XMTRX.
shz_xmtrx_to_quat	Constructs a quaternion from the 3D rotation matrix within XMTRX.
shz_xmtrx_determinant	Returns the determinant of XMTRX.
shz_xmtrx_invert	Inverts XMTRX in-place.
shz_xmtrx_blend	Deprecated way to add and accumulate a scaled 4x4 matrix onto XMTRX.
shz_xmtrx_blend_4x4	Adds and accumulates a scaled 4x4 matrix onto XMTRX.
shz_xmtrx_blend_3x4	Adds and accumulates a scaled 3x4 matrix onto XMTRX.

Enumerations

Symbol	Description
shz_xmtrx_reg	Registers comprising XMTRX, in the FPU back-bank.