Vector API

The Vector API provides structures representing commonly-used vector types as well as routines implementing various mathematical operations on them. Every operation exists per dimension (shz_vec2_*, shz_vec3_*, shz_vec4_*), and C code can call the type-generic shz_vec_* macros, which forward to the proper routine based on the argument type. Dot products and magnitudes are routed through the SH4 FIPR instruction, and normalization uses FSRRA. In C++, shz::vec2, shz::vec3 and shz::vec4 derive from the C structs and expose the same routines as methods and operators.

• C header: #include <sh4zam/shz_vector.h>
• C++ header: #include <sh4zam/shz_vector.hpp>
• C++ types: shz::vecN, shz::vec2, shz::vec3, shz::vec4
• Symbols: 229

Suffixes

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

• _safe: Guards degenerate input (zero-length vectors, zero denominators) at a small cost.
• _fsrra: Uses FSRRA (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise.
• _deg: Angle argument is in degrees. The default is radians.
• dot2/dot3: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined FIPR sequence.

Adapters

Macros for converting between SH4ZAM and other compatible formats.

Symbol	Description
shz_vec2_deref	Dereferences the given pointer to a sequence of 2 floats as a shz_vec2_t.
shz_vec3_deref	Dereferences the given pointer to a sequence of 3 floats as a shz_vec3_t.
shz_vec4_deref	Dereferences the given pointer to a sequence of 4 floats as a shz_vec4_t.
shz_vec2_from	Converts the given value or expression to the equivalent 2D SH4ZAM vector value.
shz_vec3_from	Converts the given value or expression to the equivalent 3D SH4ZAM vector value.
shz_vec4_from	Converts the given value or expression to the equivalent 4D SH4ZAM vector value.
shz_vec2_to	Converts the given 2D vector into a value of the given type.
shz_vec3_to	Converts the given 3D vector into a value of the given type.
shz_vec4_to	Converts the given 4D vector into a value of the given type.

Type-Generic Routines

Generalized vector routines for C and C++.

Symbol	Description
shz_vec_abs	C type-generic vector absolute value.
shz_vec_neg	C type-generic vector negation.
shz_vec_inv	C type-generic vector inversion.
shz_vec_max	C type-generic vector maximum value.
shz_vec_min	C type-generic vector minimum value.
shz_vec_clamp	C type-generic vector minimum value.
shz_vec_equal	C type-generic vector equals.
shz_vec_add	C type-generic vector addition.
shz_vec_sub	C type-generic vector subtraction.
shz_vec_mul	C type-generic vector multiplication.
shz_vec_div	C type-generic vector division.
shz_vec_scale	C type-generic vector scaling.
shz_vec_dot	C type-generic vector dot product.
shz_vec_dot2	C type-generic vector chained double dot product.
shz_vec_dot3	C type-generic vector chained triple dot product.
shz_vec_magnitude_sqr	C type-generic vector squared magnitude.
shz_vec_magnitude	C type-generic vector magnitude.
shz_vec_magnitude_inv	C type-generic vector inverse magnitude.
shz_vec_normalize	C type-generic vector normalization.
shz_vec_normalize_safe	C type-generic safe vector normalization.
shz_vec_distance	C type-generic vector distance.
shz_vec_move	C type-generic vector move.
shz_vec_distance_sqr	C type-generic vector squared distance.
shz_vec_lerp	C type-generic linear interpolation between two vectors.
shz_vec_reflect	C type-generic vector reflection.
shz_vec_refract	C type-generic vector refraction.
shz_vec_cross	C type-generic vector cross-product.
shz_vec_project	C type-generic vector projection.
shz_vec_project_safe	C type-generic safe vector projection.
shz_vec_angles	C type-generic angle-from-vector extraction.
shz_vec_angle_between	C type-generic angle between two vectors.
shz_vec_swizzle	C type-generic vector swizzling.
shz_vec_floor	C type-generic component-wise floor.
shz_vec_ceil	C type-generic component-wise ceil.
shz_vec_round	C type-generic component-wise round.
shz_vec_fract	C type-generic component-wise fract.
shz_vec_sign	C type-generic component-wise sign.
shz_vec_saturate	C type-generic component-wise saturate.
shz_vec_minv	C type-generic pairwise minimum.
shz_vec_maxv	C type-generic pairwise maximum.
shz_vec_inv_sqrtf	C type-generic inv_sqrtf.
shz_vec_sqrtf	C type-generic sqrtf.
shz_vec_stepv	C type-generic component-wise step.
shz_vec_step	C type-generic step.
shz_vec_smoothstepv	C type-generic component-wise smoothstep.
shz_vec_smoothstep	C type-generic smoothstep.
shz_vec_smoothstepv_safe	C type-generic component-wise smoothstep_safe.
shz_vec_smoothstep_safe	C type-generic smoothstep_safe.

Initializers

Component-based initialization routines.

Symbol	Description
shz_vec2_init	Returns a 2D vector with the given x, and y coordinates.
shz_vec3_init	Returns a 3D vector with the given x, y, and z coordinates.
shz_vec4_init	Returns a 4D vector with the given x, y, z, and w coordinates.
shz_vec2_fill	Returns a 2D vector with the value of each component equal to v.
shz_vec3_fill	Returns a 3D vector with the value of each compoonent equal to v.
shz_vec4_fill	Returns a 4D vector with the value of each component equal to v.

Component-wise Operations

Routines which apply to each vector component.

Symbol	Description
shz_vec2_abs	Returns a 2D vector whose components are the absolute values of the given vector's components.
shz_vec3_abs	Returns a 3D vector whose components are the absolute values of the given vector's components.
shz_vec4_abs	Returns a 4D vector whose components are the absolute values of the given vector's components.
shz_vec2_neg	Returns a 2D vector whose components are the negative values of the given vector's components.
shz_vec3_neg	Returns a 3D vector whose components are the negative values of the given vector's components.
shz_vec4_neg	Returns a 4D vector whose components are the negative values of the given vector's components.
shz_vec2_inv	Returns the 2D vector whose components have been inverted or reciprocated.
shz_vec3_inv	Returns the 3D vector whose components have been inverted or reciprocated.
shz_vec4_inv	Returns the 4D vector whose components have been inverted or reciprocated.
shz_vec2_max	Returns the maximum value of both of the given vector's components.
shz_vec3_max	Returns the maximum value of the given vector's 3 components.
shz_vec4_max	Returns the maximum value of the given vector's 4 componetns.
shz_vec2_min	Retuns the minimum value of both of the given vector's components.
shz_vec3_min	Returns the minimum value of the given vector's 3 components.
shz_vec4_min	Returns the minimum value of the given vector's 4 components.
shz_vec2_clamp	Clamps the values of the given 2D vec between min and max, returning a new vector.
shz_vec3_clamp	Clamps the values of the given 3D vec between min and max, returning a new vector.
shz_vec4_clamp	Clamps the values of the given 4D vec between min and max, returning a new vector.
shz_vec2_floor	Returns a 2D vector whose components are the floor of the given vector's components.
shz_vec3_floor	Returns a 3D vector whose components are the floor of the given vector's components.
shz_vec4_floor	Returns a 4D vector whose components are the floor of the given vector's components.
shz_vec2_ceil	Returns a 2D vector whose components are the ceil of the given vector's components.
shz_vec3_ceil	Returns a 3D vector whose components are the ceil of the given vector's components.
shz_vec4_ceil	Returns a 4D vector whose components are the ceil of the given vector's components.
shz_vec2_round	Returns a 2D vector whose components are the rounded values of the given vector's components.
shz_vec3_round	Returns a 3D vector whose components are the rounded values of the given vector's components.
shz_vec4_round	Returns a 4D vector whose components are the rounded values of the given vector's components.
shz_vec2_fract	Returns a 2D vector whose components are the fractional parts of the given vector's components.
shz_vec3_fract	Returns a 3D vector whose components are the fractional parts of the given vector's components.
shz_vec4_fract	Returns a 4D vector whose components are the fractional parts of the given vector's components.
shz_vec2_sign	Returns a 2D vector whose components are the signs (-1, 0, or 1) of the given vector's components.
shz_vec3_sign	Returns a 3D vector whose components are the signs (-1, 0, or 1) of the given vector's components.
shz_vec4_sign	Returns a 4D vector whose components are the signs (-1, 0, or 1) of the given vector's components.
shz_vec2_saturate	Returns a 2D vector whose components are saturated (clamped to [0, 1]) values of the given vector's components.
shz_vec3_saturate	Returns a 3D vector whose components are saturated (clamped to [0, 1]) values of the given vector's components.
shz_vec4_saturate	Returns a 4D vector whose components are saturated (clamped to [0, 1]) values of the given vector's components.
shz_vec2_minv	Returns a 2D vector whose components are the pairwise minimums of the two given vectors' components.
shz_vec3_minv	Returns a 3D vector whose components are the pairwise minimums of the two given vectors' components.
shz_vec4_minv	Returns a 4D vector whose components are the pairwise minimums of the two given vectors' components.
shz_vec2_maxv	Returns a 2D vector whose components are the pairwise maximums of the two given vectors' components.
shz_vec3_maxv	Returns a 3D vector whose components are the pairwise maximums of the two given vectors' components.
shz_vec4_maxv	Returns a 4D vector whose components are the pairwise maximums of the two given vectors' components.
shz_vec2_equal	Returns true if the values of each element within the two 2D vectors are approximately equal based on relative or absolute tolerance.
shz_vec3_equal	Returns true if the values of each element within the two 3D vectors are approximately equal based on relative or absolute tolerance.
shz_vec4_equal	Returns true if the values of each element within the two 4D vectors are approximately equal based on relative or absolute tolerance.
shz_vec2_stepv	For each component: returns 0.0f if vec[i] < edge[i], otherwise 1.0f.
shz_vec3_stepv	For each component: returns 0.0f if vec[i] < edge[i], otherwise 1.0f.
shz_vec4_stepv	For each component: returns 0.0f if vec[i] < edge[i], otherwise 1.0f.
shz_vec2_step	For each component: returns 0.0f if vec[i] < edge, otherwise 1.0f.
shz_vec3_step	For each component: returns 0.0f if vec[i] < edge, otherwise 1.0f.
shz_vec4_step	For each component: returns 0.0f if vec[i] < edge, otherwise 1.0f.
shz_vec2_smoothstep	For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between.
shz_vec3_smoothstep	For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between.
shz_vec4_smoothstep	For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between.
shz_vec2_smoothstepv	For each component: returns 0.0f at/below edge0[i], 1.0f at/above edge1[i], smoothly varying in-between.
shz_vec3_smoothstepv	For each component i: returns 0.0f at/below edge0[i], 1.0f at/above edge1[i], smoothly varying in-between.
shz_vec4_smoothstepv	For each component i: returns 0.0f at/below edge0[i], 1.0f at/above edge1[i], smoothly varying in-between.
shz_vec2_smoothstep_safe	For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. Accepts inverse edges.
shz_vec3_smoothstep_safe	For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. Accepts inverse edges.
shz_vec4_smoothstep_safe	For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. Accepts inverse edges.
shz_vec2_smoothstepv_safe	For each component: returns 0.0f at/below edge0[i], 1.0f at/above edge1[i], smoothly varying in-between. Accepts inverse edges.
shz_vec3_smoothstepv_safe	For each component i: returns 0.0f at/below edge0[i], 1.0f at/above edge1[i], smoothly varying in-between. Accepts inverse edges.
shz_vec4_smoothstepv_safe	For each component i: returns 0.0f at/below edge0[i], 1.0f at/above edge1[i], smoothly varying in-between. Accepts inverse edges.
shz_vec2_inv_sqrtf	Returns a 2D vector whose components are the inverse square root of the given vector's components.
shz_vec3_inv_sqrtf	Returns a 3D vector whose components are the inverse square root of the given vector's components.
shz_vec4_inv_sqrtf	Returns a 4D vector whose components are the inverse square root of the given vector's components.
shz_vec2_sqrtf	Returns a 2D vector whose components are the square root of the given vector's components.
shz_vec3_sqrtf	Returns a 3D vector whose components are the square root of the given vector's components.
shz_vec4_sqrtf	Returns a 4D vector whose components are the square root of the given vector's components.

Arithmetic

Routines for basic vector arithmetic operations.

Symbol	Description
shz_vec2_add	Returns a 2D vector whose components are the sums of the given vectors' components.
shz_vec3_add	Returns a 3D vector whose components are the sums of the given vectors' components.
shz_vec4_add	Returns a 4D vector whose components are the sums of the given vectors' components.
shz_vec2_sub	Returns a 2D vector whose components are equal to the values of vec1 minus vec2.
shz_vec3_sub	Returns a 3D vector whose components are equal to the values of vec1 minus vec2.
shz_vec4_sub	Returns a 4D vector whose components are equal to the values of vec1 minus vec2.
shz_vec2_mul	Returns a 2D vector whose component values are those of vec1 times vec2.
shz_vec3_mul	Returns a 3D vector whose component values are those of vec1 times vec2.
shz_vec4_mul	Returns a 4D vector whose component values are those of vec1 times vec2.
shz_vec2_div	Returns a 2D vector whose component values are those of vec1 divided by vec2.
shz_vec3_div	Returns a 3D vector whose component values are those of vec1 divided by vec2.
shz_vec4_div	Returns a 4D vector whose component values are those of vec1 divided by vec2.
shz_vec2_scale	Returns a 2D vector whose component values are those of the given vector multiplied by a factor.
shz_vec3_scale	Returns a 3D vector whose component values are those of the given vector multiplied by a factor.
shz_vec4_scale	Returns a 4D vector whose component values are those of the given vector multiplied by a factor.

Magnitude

Math routines for vector length and normalization.

Symbol	Description
shz_vec2_magnitude_sqr	Returns the squared magnitude of the given 2D vector.
shz_vec4_magnitude_sqr	Returns the squared magnitude of the given 4D vector.
shz_vec3_magnitude_sqr	Returns the squared magnitude of the given 3D vector.
shz_vec2_magnitude	Returns the magnitude of the given 2D vector.
shz_vec3_magnitude	Returns the magnitude of the given 3D vector.
shz_vec4_magnitude	Returns the magnitude of the given 4D vector.
shz_vec2_magnitude_inv	Returns the inverse magnitude of the given 2D vector.
shz_vec3_magnitude_inv	Returns the inverse magnitude of the given 3D vector.
shz_vec4_magnitude_inv	Returns the inverse magnitude of the given 4D vector.
shz_vec2_normalize	Returns a normalized unit vector from the given 2D vector.
shz_vec3_normalize	Returns a normalized unit vector from the given 3D vector.
shz_vec4_normalize	Returns a normalized unit vector from the given 4D vector.
shz_vec2_normalize_safe	SAFELY returns a normalized unit vector from the given 2D vector.
shz_vec3_normalize_safe	SAFELY returns a normalized unit vector from the given 3D vector.
shz_vec4_normalize_safe	SAFELY returns a normalized unit vector from the given 4D vector.

Binary Operations

Linear algebra operations performed with multiple vectors.

Symbol	Description
shz_vec2_dot	Returns the dot product between the two given 2D vectors.
shz_vec2_dot2	Returns the two dot products taken between the 2D vector l and 2D vectors r1 and r2.
shz_vec2_dot3	Returns the three dot products taken between the 2D vector l and 2D vectors r1, r2, and r3.
shz_vec3_dot	Returns the dot product between the two given 3D vectors.
shz_vec3_dot2	Returns the two dot products taken between the 3D vector l and 3D vectors r1 and r2.
shz_vec3_dot3	Returns the three dot products taken between the 3D vector l and 3D vectors r1, r2, and r3.
shz_vec4_dot	Returns the dot product between the two given 4D vectors.
shz_vec4_dot2	Returns the two dot products taken between the 4D vector l and 4D vectors r1 and r2.
shz_vec4_dot3	Returns the three dot products taken between the 4D vector l and 4D vectors r1, r2, and r3.
shz_vec2_distance	Returns the distance between the two given 2D vectors.
shz_vec3_distance	Returns the distance between the two given 3D vectors.
shz_vec4_distance	Returns the distance between the two given 4D vectors.
shz_vec2_distance_sqr	Returns the squared-distance between the two given 2D vectors.
shz_vec3_distance_sqr	Returns the squared-distance between the two given 3D vectors.
shz_vec4_distance_sqr	Returns the squared-distance between the two given 4D vectors.
shz_vec2_move	Returns the given 2D vector, translated towards the target by the given max_distance.
shz_vec3_move	Returns the given 3D vector, translated towards the target by the given max_distance.
shz_vec4_move	Returns the given 4D vector, translated towards the target by the given max_distance.
shz_vec2_lerp	Returns a 2D vector that is linearly interpolated from a to b by the given 0.0f-1.0f factor, t.
shz_vec3_lerp	Returns a 3D vector that is linearly interpolated from a to b by the given 0.0f-1.0f factor, t.
shz_vec4_lerp	Returns a 4D vector that is linearly interpolated from a to b by the given 0.0f-1.0f factor, t.
shz_vec2_reflect	Reflects the given 2D incidence vector against a surface with the given normal, returning the result.
shz_vec3_reflect	Reflects the given 3D incidence vector against a surface with the given normal, returning the result.
shz_vec4_reflect	Reflects the given 4D incidence vector against a surface with the given normal, returning the result.
shz_vec2_refract	Refracts the given 2D incidence vector against a surface with the given normal using the given refraction index ratio, eta.
shz_vec3_refract	Refracts the given 3D incidence vector against a surface with the given normal using the given refraction index ratio, eta.
shz_vec4_refract	Refracts the given 4D incidence vector against a surface with the given normal using the given refraction index ratio, eta.
shz_vec2_cross	Returns the cross product, as a scalar, between two 2D vectors.
shz_vec3_cross	Returns the vector produced by taking the cross-product of the two given 3D vectors.
shz_vec2_project	Returns the resulting vector from projecting the given 2D vector along the given (unit) axis.
shz_vec3_project	Returns the resulting vector from projecting the given 3D vector along the given (unit) axis.
shz_vec4_project	Returns the resulting vector from projecting the given 4D vector along the given (unit) axis.
shz_vec2_project_safe	Returns the resulting vector from projecting the given 2D vector along the given (unit) axis.
shz_vec3_project_safe	Returns the resulting vector from projecting the given 3D vector along the given (unit) axis.
shz_vec4_project_safe	Returns the resulting vector from projecting the given 4D vector along the given (unit) axis.
shz_vec3_reject	Returns the rejection of the given vector, vec, onto another vector, onto.

Miscellaneous

Other specialized vector routines.

Symbol	Description
shz_vec3_triple	Returns the 3D vector "triple product" between vector's a, b, and c.
shz_vec3_perp	Returns a vector which is perpendicular to the given vector.
shz_vec3_barycenter	Computes barycentric coordinates <u, v, w> for point p, within the plane of the triangle with vertices a, b, and c.
shz_vec3_orthonormalize	Returns 2 3D vectors which are normalized and orthogonal to the two input vectors.
shz_vec3_cubic_hermite	Calculates the cubic hermite interpolation between two vectors and their tangents.

Angles

Routines for working with vectors and angles.

Symbol	Description
shz_vec2_angle_between	Returns the angle formed between the given 2D vectors in radians.
shz_vec3_angle_between	Returns the angle formed between the given 3D vectors in radians.
shz_vec2_angle	Returns the angle formed between the positive X axis and the given 2D vector, in radians.
shz_vec3_angles	Returns the angles formed between the positive X axis and the given 3D vector, in radians.
shz_vec2_from_sincos	Returns the 2D unit vector representing a rotation from the positive X axis.
shz_vec3_from_sincos	Returns the 3D unit vector representing the given rotation angles relative to the positive X axis.
shz_vec2_from_angle	Returns the 2D unit vector representing a rotation from the positive X axis in radians.
shz_vec3_from_angles	Returns the 3D unit vector representing the given rotation angles relative to the positive X axis in radians.
shz_vec2_from_angle_deg	Returns the 2D unit vector representing a rotation from the positive X axis in degrees.
shz_vec3_from_angles_deg	Returns the 3D unit vector representing the given rotation angles relative to the positive X axis in degrees.
shz_vec2_rotate	Rotates the given 2D vector about the Z axis by the given angle in radians.
shz_vec3_rotate_x	Rotates the given 3D vector about the X axis by the given angle in radians.
shz_vec3_rotate_y	Rotates the given 3D vector about the Y axis by the given angle in radians.
shz_vec3_rotate_z	Rotates the given 3D vector about the Z axis by the given angle in radians.

Extending

Routines for extending vectors into other dimensions.

Symbol	Description
shz_vec2_vec3	Extends a 2D vector to 3D, using z as the value of the Z component.
shz_vec2_vec4	Extends a 2D vector to 4D, using z and w as the values of the Z and W components.
shz_vec3_vec4	Extends a 3D vector to 4D, using w as the value of the W component.

Swizzling

Routines for swizzling the order of a vector's components.

Symbol	Description
shz_vec2_swizzle	Returns a 2D vector whose elements are equal to the source vector's values at the given indices.
shz_vec3_swizzle	Returns a 3D vector whose elements are equal to the source vector's values at the given indices.
shz_vec4_swizzle	Returns a new 2D vector whose elements are equal to the source vector's values at the given indices.

Types

Symbol	Description
shz_vec2_t	2D Vector type
shz_vec2	Alternate typedef for the shz_vec2 struct for those who hate POSIX-style.
shz_vec3_t	3D Vector type
shz_vec3	Alternate typedef for the shz_vec3 struct for those who hate POSIX-style.
shz_vec4_t	4D Vector type
shz_vec4	Alternate typedef for the shz_vec4 struct for those who hate POSIX-style.