# Vector API

Source: https://sh4zam.com/api/vector/

> API for vector math: 2D, 3D and 4D vector types and operations

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`](https://sh4zam.com/api/cpp/vecn/), [`shz::vec2`](https://sh4zam.com/api/cpp/vec2/), [`shz::vec3`](https://sh4zam.com/api/cpp/vec3/), [`shz::vec4`](https://sh4zam.com/api/cpp/vec4/)
- **Symbols:** 229

## Suffixes

Suffixes used in this module. The full list is in [Naming and Suffixes](https://sh4zam.com/concepts/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`](https://sh4zam.com/api/vector/shz_vec2_deref/) | Dereferences the given pointer to a sequence of 2 floats as a [`shz_vec2_t`](https://sh4zam.com/api/vector/shz_vec2_t/). |
| [`shz_vec3_deref`](https://sh4zam.com/api/vector/shz_vec3_deref/) | Dereferences the given pointer to a sequence of 3 floats as a [`shz_vec3_t`](https://sh4zam.com/api/vector/shz_vec3_t/). |
| [`shz_vec4_deref`](https://sh4zam.com/api/vector/shz_vec4_deref/) | Dereferences the given pointer to a sequence of 4 floats as a [`shz_vec4_t`](https://sh4zam.com/api/vector/shz_vec4_t/). |
| [`shz_vec2_from`](https://sh4zam.com/api/vector/shz_vec2_from/) | Converts the given `value` or expression to the equivalent 2D SH4ZAM vector value. |
| [`shz_vec3_from`](https://sh4zam.com/api/vector/shz_vec3_from/) | Converts the given `value` or expression to the equivalent 3D SH4ZAM vector value. |
| [`shz_vec4_from`](https://sh4zam.com/api/vector/shz_vec4_from/) | Converts the given `value` or expression to the equivalent 4D SH4ZAM vector value. |
| [`shz_vec2_to`](https://sh4zam.com/api/vector/shz_vec2_to/) | Converts the given 2D `vector` into a value of the given `type`. |
| [`shz_vec3_to`](https://sh4zam.com/api/vector/shz_vec3_to/) | Converts the given 3D `vector` into a value of the given `type`. |
| [`shz_vec4_to`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec_abs/) | C type-generic vector absolute value. |
| [`shz_vec_neg`](https://sh4zam.com/api/vector/shz_vec_neg/) | C type-generic vector negation. |
| [`shz_vec_inv`](https://sh4zam.com/api/vector/shz_vec_inv/) | C type-generic vector inversion. |
| [`shz_vec_max`](https://sh4zam.com/api/vector/shz_vec_max/) | C type-generic vector maximum value. |
| [`shz_vec_min`](https://sh4zam.com/api/vector/shz_vec_min/) | C type-generic vector minimum value. |
| [`shz_vec_clamp`](https://sh4zam.com/api/vector/shz_vec_clamp/) | C type-generic vector minimum value. |
| [`shz_vec_equal`](https://sh4zam.com/api/vector/shz_vec_equal/) | C type-generic vector equals. |
| [`shz_vec_add`](https://sh4zam.com/api/vector/shz_vec_add/) | C type-generic vector addition. |
| [`shz_vec_sub`](https://sh4zam.com/api/vector/shz_vec_sub/) | C type-generic vector subtraction. |
| [`shz_vec_mul`](https://sh4zam.com/api/vector/shz_vec_mul/) | C type-generic vector multiplication. |
| [`shz_vec_div`](https://sh4zam.com/api/vector/shz_vec_div/) | C type-generic vector division. |
| [`shz_vec_scale`](https://sh4zam.com/api/vector/shz_vec_scale/) | C type-generic vector scaling. |
| [`shz_vec_dot`](https://sh4zam.com/api/vector/shz_vec_dot/) | C type-generic vector dot product. |
| [`shz_vec_dot2`](https://sh4zam.com/api/vector/shz_vec_dot2/) | C type-generic vector chained double dot product. |
| [`shz_vec_dot3`](https://sh4zam.com/api/vector/shz_vec_dot3/) | C type-generic vector chained triple dot product. |
| [`shz_vec_magnitude_sqr`](https://sh4zam.com/api/vector/shz_vec_magnitude_sqr/) | C type-generic vector squared magnitude. |
| [`shz_vec_magnitude`](https://sh4zam.com/api/vector/shz_vec_magnitude/) | C type-generic vector magnitude. |
| [`shz_vec_magnitude_inv`](https://sh4zam.com/api/vector/shz_vec_magnitude_inv/) | C type-generic vector inverse magnitude. |
| [`shz_vec_normalize`](https://sh4zam.com/api/vector/shz_vec_normalize/) | C type-generic vector normalization. |
| [`shz_vec_normalize_safe`](https://sh4zam.com/api/vector/shz_vec_normalize_safe/) | C type-generic safe vector normalization. |
| [`shz_vec_distance`](https://sh4zam.com/api/vector/shz_vec_distance/) | C type-generic vector distance. |
| [`shz_vec_move`](https://sh4zam.com/api/vector/shz_vec_move/) | C type-generic vector move. |
| [`shz_vec_distance_sqr`](https://sh4zam.com/api/vector/shz_vec_distance_sqr/) | C type-generic vector squared distance. |
| [`shz_vec_lerp`](https://sh4zam.com/api/vector/shz_vec_lerp/) | C type-generic linear interpolation between two vectors. |
| [`shz_vec_reflect`](https://sh4zam.com/api/vector/shz_vec_reflect/) | C type-generic vector reflection. |
| [`shz_vec_refract`](https://sh4zam.com/api/vector/shz_vec_refract/) | C type-generic vector refraction. |
| [`shz_vec_cross`](https://sh4zam.com/api/vector/shz_vec_cross/) | C type-generic vector cross-product. |
| [`shz_vec_project`](https://sh4zam.com/api/vector/shz_vec_project/) | C type-generic vector projection. |
| [`shz_vec_project_safe`](https://sh4zam.com/api/vector/shz_vec_project_safe/) | C type-generic safe vector projection. |
| [`shz_vec_angles`](https://sh4zam.com/api/vector/shz_vec_angles/) | C type-generic angle-from-vector extraction. |
| [`shz_vec_angle_between`](https://sh4zam.com/api/vector/shz_vec_angle_between/) | C type-generic angle between two vectors. |
| [`shz_vec_swizzle`](https://sh4zam.com/api/vector/shz_vec_swizzle/) | C type-generic vector swizzling. |
| [`shz_vec_floor`](https://sh4zam.com/api/vector/shz_vec_floor/) | C type-generic component-wise floor. |
| [`shz_vec_ceil`](https://sh4zam.com/api/vector/shz_vec_ceil/) | C type-generic component-wise ceil. |
| [`shz_vec_round`](https://sh4zam.com/api/vector/shz_vec_round/) | C type-generic component-wise round. |
| [`shz_vec_fract`](https://sh4zam.com/api/vector/shz_vec_fract/) | C type-generic component-wise fract. |
| [`shz_vec_sign`](https://sh4zam.com/api/vector/shz_vec_sign/) | C type-generic component-wise sign. |
| [`shz_vec_saturate`](https://sh4zam.com/api/vector/shz_vec_saturate/) | C type-generic component-wise saturate. |
| [`shz_vec_minv`](https://sh4zam.com/api/vector/shz_vec_minv/) | C type-generic pairwise minimum. |
| [`shz_vec_maxv`](https://sh4zam.com/api/vector/shz_vec_maxv/) | C type-generic pairwise maximum. |
| [`shz_vec_inv_sqrtf`](https://sh4zam.com/api/vector/shz_vec_inv_sqrtf/) | C type-generic inv_sqrtf. |
| [`shz_vec_sqrtf`](https://sh4zam.com/api/vector/shz_vec_sqrtf/) | C type-generic sqrtf. |
| [`shz_vec_stepv`](https://sh4zam.com/api/vector/shz_vec_stepv/) | C type-generic component-wise step. |
| [`shz_vec_step`](https://sh4zam.com/api/vector/shz_vec_step/) | C type-generic step. |
| [`shz_vec_smoothstepv`](https://sh4zam.com/api/vector/shz_vec_smoothstepv/) | C type-generic component-wise smoothstep. |
| [`shz_vec_smoothstep`](https://sh4zam.com/api/vector/shz_vec_smoothstep/) | C type-generic smoothstep. |
| [`shz_vec_smoothstepv_safe`](https://sh4zam.com/api/vector/shz_vec_smoothstepv_safe/) | C type-generic component-wise smoothstep_safe. |
| [`shz_vec_smoothstep_safe`](https://sh4zam.com/api/vector/shz_vec_smoothstep_safe/) | C type-generic smoothstep_safe. |

## Initializers

Component-based initialization routines.

| Symbol | Description |
| --- | --- |
| [`shz_vec2_init`](https://sh4zam.com/api/vector/shz_vec2_init/) | Returns a 2D vector with the given `x`, and `y` coordinates. |
| [`shz_vec3_init`](https://sh4zam.com/api/vector/shz_vec3_init/) | Returns a 3D vector with the given `x`, `y`, and `z` coordinates. |
| [`shz_vec4_init`](https://sh4zam.com/api/vector/shz_vec4_init/) | Returns a 4D vector with the given `x`, `y`, `z`, and `w` coordinates. |
| [`shz_vec2_fill`](https://sh4zam.com/api/vector/shz_vec2_fill/) | Returns a 2D vector with the value of each component equal to `v`. |
| [`shz_vec3_fill`](https://sh4zam.com/api/vector/shz_vec3_fill/) | Returns a 3D vector with the value of each compoonent equal to `v`. |
| [`shz_vec4_fill`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_abs/) | Returns a 2D vector whose components are the absolute values of the given vector's components. |
| [`shz_vec3_abs`](https://sh4zam.com/api/vector/shz_vec3_abs/) | Returns a 3D vector whose components are the absolute values of the given vector's components. |
| [`shz_vec4_abs`](https://sh4zam.com/api/vector/shz_vec4_abs/) | Returns a 4D vector whose components are the absolute values of the given vector's components. |
| [`shz_vec2_neg`](https://sh4zam.com/api/vector/shz_vec2_neg/) | Returns a 2D vector whose components are the negative values of the given vector's components. |
| [`shz_vec3_neg`](https://sh4zam.com/api/vector/shz_vec3_neg/) | Returns a 3D vector whose components are the negative values of the given vector's components. |
| [`shz_vec4_neg`](https://sh4zam.com/api/vector/shz_vec4_neg/) | Returns a 4D vector whose components are the negative values of the given vector's components. |
| [`shz_vec2_inv`](https://sh4zam.com/api/vector/shz_vec2_inv/) | Returns the 2D vector whose components have been inverted or reciprocated. |
| [`shz_vec3_inv`](https://sh4zam.com/api/vector/shz_vec3_inv/) | Returns the 3D vector whose components have been inverted or reciprocated. |
| [`shz_vec4_inv`](https://sh4zam.com/api/vector/shz_vec4_inv/) | Returns the 4D vector whose components have been inverted or reciprocated. |
| [`shz_vec2_max`](https://sh4zam.com/api/vector/shz_vec2_max/) | Returns the maximum value of both of the given vector's components. |
| [`shz_vec3_max`](https://sh4zam.com/api/vector/shz_vec3_max/) | Returns the maximum value of the given vector's 3 components. |
| [`shz_vec4_max`](https://sh4zam.com/api/vector/shz_vec4_max/) | Returns the maximum value of the given vector's 4 componetns. |
| [`shz_vec2_min`](https://sh4zam.com/api/vector/shz_vec2_min/) | Retuns the minimum value of both of the given vector's components. |
| [`shz_vec3_min`](https://sh4zam.com/api/vector/shz_vec3_min/) | Returns the minimum value of the given vector's 3 components. |
| [`shz_vec4_min`](https://sh4zam.com/api/vector/shz_vec4_min/) | Returns the minimum value of the given vector's 4 components. |
| [`shz_vec2_clamp`](https://sh4zam.com/api/vector/shz_vec2_clamp/) | Clamps the values of the given 2D `vec` between `min` and `max`, returning a new vector. |
| [`shz_vec3_clamp`](https://sh4zam.com/api/vector/shz_vec3_clamp/) | Clamps the values of the given 3D `vec` between `min` and `max`, returning a new vector. |
| [`shz_vec4_clamp`](https://sh4zam.com/api/vector/shz_vec4_clamp/) | Clamps the values of the given 4D `vec` between `min` and `max`, returning a new vector. |
| [`shz_vec2_floor`](https://sh4zam.com/api/vector/shz_vec2_floor/) | Returns a 2D vector whose components are the floor of the given vector's components. |
| [`shz_vec3_floor`](https://sh4zam.com/api/vector/shz_vec3_floor/) | Returns a 3D vector whose components are the floor of the given vector's components. |
| [`shz_vec4_floor`](https://sh4zam.com/api/vector/shz_vec4_floor/) | Returns a 4D vector whose components are the floor of the given vector's components. |
| [`shz_vec2_ceil`](https://sh4zam.com/api/vector/shz_vec2_ceil/) | Returns a 2D vector whose components are the ceil of the given vector's components. |
| [`shz_vec3_ceil`](https://sh4zam.com/api/vector/shz_vec3_ceil/) | Returns a 3D vector whose components are the ceil of the given vector's components. |
| [`shz_vec4_ceil`](https://sh4zam.com/api/vector/shz_vec4_ceil/) | Returns a 4D vector whose components are the ceil of the given vector's components. |
| [`shz_vec2_round`](https://sh4zam.com/api/vector/shz_vec2_round/) | Returns a 2D vector whose components are the rounded values of the given vector's components. |
| [`shz_vec3_round`](https://sh4zam.com/api/vector/shz_vec3_round/) | Returns a 3D vector whose components are the rounded values of the given vector's components. |
| [`shz_vec4_round`](https://sh4zam.com/api/vector/shz_vec4_round/) | Returns a 4D vector whose components are the rounded values of the given vector's components. |
| [`shz_vec2_fract`](https://sh4zam.com/api/vector/shz_vec2_fract/) | Returns a 2D vector whose components are the fractional parts of the given vector's components. |
| [`shz_vec3_fract`](https://sh4zam.com/api/vector/shz_vec3_fract/) | Returns a 3D vector whose components are the fractional parts of the given vector's components. |
| [`shz_vec4_fract`](https://sh4zam.com/api/vector/shz_vec4_fract/) | Returns a 4D vector whose components are the fractional parts of the given vector's components. |
| [`shz_vec2_sign`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_minv/) | Returns a 2D vector whose components are the pairwise minimums of the two given vectors' components. |
| [`shz_vec3_minv`](https://sh4zam.com/api/vector/shz_vec3_minv/) | Returns a 3D vector whose components are the pairwise minimums of the two given vectors' components. |
| [`shz_vec4_minv`](https://sh4zam.com/api/vector/shz_vec4_minv/) | Returns a 4D vector whose components are the pairwise minimums of the two given vectors' components. |
| [`shz_vec2_maxv`](https://sh4zam.com/api/vector/shz_vec2_maxv/) | Returns a 2D vector whose components are the pairwise maximums of the two given vectors' components. |
| [`shz_vec3_maxv`](https://sh4zam.com/api/vector/shz_vec3_maxv/) | Returns a 3D vector whose components are the pairwise maximums of the two given vectors' components. |
| [`shz_vec4_maxv`](https://sh4zam.com/api/vector/shz_vec4_maxv/) | Returns a 4D vector whose components are the pairwise maximums of the two given vectors' components. |
| [`shz_vec2_equal`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_stepv/) | For each component: returns 0.0f if vec\[i\] \< edge\[i\], otherwise 1.0f. |
| [`shz_vec3_stepv`](https://sh4zam.com/api/vector/shz_vec3_stepv/) | For each component: returns 0.0f if vec\[i\] \< edge\[i\], otherwise 1.0f. |
| [`shz_vec4_stepv`](https://sh4zam.com/api/vector/shz_vec4_stepv/) | For each component: returns 0.0f if vec\[i\] \< edge\[i\], otherwise 1.0f. |
| [`shz_vec2_step`](https://sh4zam.com/api/vector/shz_vec2_step/) | For each component: returns 0.0f if vec\[i\] \< edge, otherwise 1.0f. |
| [`shz_vec3_step`](https://sh4zam.com/api/vector/shz_vec3_step/) | For each component: returns 0.0f if vec\[i\] \< edge, otherwise 1.0f. |
| [`shz_vec4_step`](https://sh4zam.com/api/vector/shz_vec4_step/) | For each component: returns 0.0f if vec\[i\] \< edge, otherwise 1.0f. |
| [`shz_vec2_smoothstep`](https://sh4zam.com/api/vector/shz_vec2_smoothstep/) | For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. |
| [`shz_vec3_smoothstep`](https://sh4zam.com/api/vector/shz_vec3_smoothstep/) | For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. |
| [`shz_vec4_smoothstep`](https://sh4zam.com/api/vector/shz_vec4_smoothstep/) | For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. |
| [`shz_vec2_smoothstepv`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec4_inv_sqrtf/) | Returns a 4D vector whose components are the inverse square root of the given vector's components. |
| [`shz_vec2_sqrtf`](https://sh4zam.com/api/vector/shz_vec2_sqrtf/) | Returns a 2D vector whose components are the square root of the given vector's components. |
| [`shz_vec3_sqrtf`](https://sh4zam.com/api/vector/shz_vec3_sqrtf/) | Returns a 3D vector whose components are the square root of the given vector's components. |
| [`shz_vec4_sqrtf`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_add/) | Returns a 2D vector whose components are the sums of the given vectors' components. |
| [`shz_vec3_add`](https://sh4zam.com/api/vector/shz_vec3_add/) | Returns a 3D vector whose components are the sums of the given vectors' components. |
| [`shz_vec4_add`](https://sh4zam.com/api/vector/shz_vec4_add/) | Returns a 4D vector whose components are the sums of the given vectors' components. |
| [`shz_vec2_sub`](https://sh4zam.com/api/vector/shz_vec2_sub/) | Returns a 2D vector whose components are equal to the values of `vec1` minus `vec2`. |
| [`shz_vec3_sub`](https://sh4zam.com/api/vector/shz_vec3_sub/) | Returns a 3D vector whose components are equal to the values of `vec1` minus `vec2`. |
| [`shz_vec4_sub`](https://sh4zam.com/api/vector/shz_vec4_sub/) | Returns a 4D vector whose components are equal to the values of `vec1` minus `vec2`. |
| [`shz_vec2_mul`](https://sh4zam.com/api/vector/shz_vec2_mul/) | Returns a 2D vector whose component values are those of `vec1` times `vec2`. |
| [`shz_vec3_mul`](https://sh4zam.com/api/vector/shz_vec3_mul/) | Returns a 3D vector whose component values are those of `vec1` times `vec2`. |
| [`shz_vec4_mul`](https://sh4zam.com/api/vector/shz_vec4_mul/) | Returns a 4D vector whose component values are those of `vec1` times `vec2`. |
| [`shz_vec2_div`](https://sh4zam.com/api/vector/shz_vec2_div/) | Returns a 2D vector whose component values are those of `vec1` divided by `vec2`. |
| [`shz_vec3_div`](https://sh4zam.com/api/vector/shz_vec3_div/) | Returns a 3D vector whose component values are those of `vec1` divided by `vec2`. |
| [`shz_vec4_div`](https://sh4zam.com/api/vector/shz_vec4_div/) | Returns a 4D vector whose component values are those of `vec1` divided by `vec2`. |
| [`shz_vec2_scale`](https://sh4zam.com/api/vector/shz_vec2_scale/) | Returns a 2D vector whose component values are those of the given vector multiplied by a factor. |
| [`shz_vec3_scale`](https://sh4zam.com/api/vector/shz_vec3_scale/) | Returns a 3D vector whose component values are those of the given vector multiplied by a factor. |
| [`shz_vec4_scale`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_magnitude_sqr/) | Returns the squared magnitude of the given 2D vector. |
| [`shz_vec4_magnitude_sqr`](https://sh4zam.com/api/vector/shz_vec4_magnitude_sqr/) | Returns the squared magnitude of the given 4D vector. |
| [`shz_vec3_magnitude_sqr`](https://sh4zam.com/api/vector/shz_vec3_magnitude_sqr/) | Returns the squared magnitude of the given 3D vector. |
| [`shz_vec2_magnitude`](https://sh4zam.com/api/vector/shz_vec2_magnitude/) | Returns the magnitude of the given 2D vector. |
| [`shz_vec3_magnitude`](https://sh4zam.com/api/vector/shz_vec3_magnitude/) | Returns the magnitude of the given 3D vector. |
| [`shz_vec4_magnitude`](https://sh4zam.com/api/vector/shz_vec4_magnitude/) | Returns the magnitude of the given 4D vector. |
| [`shz_vec2_magnitude_inv`](https://sh4zam.com/api/vector/shz_vec2_magnitude_inv/) | Returns the inverse magnitude of the given 2D vector. |
| [`shz_vec3_magnitude_inv`](https://sh4zam.com/api/vector/shz_vec3_magnitude_inv/) | Returns the inverse magnitude of the given 3D vector. |
| [`shz_vec4_magnitude_inv`](https://sh4zam.com/api/vector/shz_vec4_magnitude_inv/) | Returns the inverse magnitude of the given 4D vector. |
| [`shz_vec2_normalize`](https://sh4zam.com/api/vector/shz_vec2_normalize/) | Returns a normalized unit vector from the given 2D vector. |
| [`shz_vec3_normalize`](https://sh4zam.com/api/vector/shz_vec3_normalize/) | Returns a normalized unit vector from the given 3D vector. |
| [`shz_vec4_normalize`](https://sh4zam.com/api/vector/shz_vec4_normalize/) | Returns a normalized unit vector from the given 4D vector. |
| [`shz_vec2_normalize_safe`](https://sh4zam.com/api/vector/shz_vec2_normalize_safe/) | SAFELY returns a normalized unit vector from the given 2D vector. |
| [`shz_vec3_normalize_safe`](https://sh4zam.com/api/vector/shz_vec3_normalize_safe/) | SAFELY returns a normalized unit vector from the given 3D vector. |
| [`shz_vec4_normalize_safe`](https://sh4zam.com/api/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`](https://sh4zam.com/api/vector/shz_vec2_dot/) | Returns the dot product between the two given 2D vectors. |
| [`shz_vec2_dot2`](https://sh4zam.com/api/vector/shz_vec2_dot2/) | Returns the two dot products taken between the 2D vector `l` and 2D vectors `r1` and `r2`. |
| [`shz_vec2_dot3`](https://sh4zam.com/api/vector/shz_vec2_dot3/) | Returns the three dot products taken between the 2D vector `l` and 2D vectors `r1`, `r2`, and `r3`. |
| [`shz_vec3_dot`](https://sh4zam.com/api/vector/shz_vec3_dot/) | Returns the dot product between the two given 3D vectors. |
| [`shz_vec3_dot2`](https://sh4zam.com/api/vector/shz_vec3_dot2/) | Returns the two dot products taken between the 3D vector `l` and 3D vectors `r1` and `r2`. |
| [`shz_vec3_dot3`](https://sh4zam.com/api/vector/shz_vec3_dot3/) | Returns the three dot products taken between the 3D vector `l` and 3D vectors `r1`, `r2`, and `r3`. |
| [`shz_vec4_dot`](https://sh4zam.com/api/vector/shz_vec4_dot/) | Returns the dot product between the two given 4D vectors. |
| [`shz_vec4_dot2`](https://sh4zam.com/api/vector/shz_vec4_dot2/) | Returns the two dot products taken between the 4D vector `l` and 4D vectors `r1` and `r2`. |
| [`shz_vec4_dot3`](https://sh4zam.com/api/vector/shz_vec4_dot3/) | Returns the three dot products taken between the 4D vector `l` and 4D vectors `r1`, `r2`, and `r3`. |
| [`shz_vec2_distance`](https://sh4zam.com/api/vector/shz_vec2_distance/) | Returns the distance between the two given 2D vectors. |
| [`shz_vec3_distance`](https://sh4zam.com/api/vector/shz_vec3_distance/) | Returns the distance between the two given 3D vectors. |
| [`shz_vec4_distance`](https://sh4zam.com/api/vector/shz_vec4_distance/) | Returns the distance between the two given 4D vectors. |
| [`shz_vec2_distance_sqr`](https://sh4zam.com/api/vector/shz_vec2_distance_sqr/) | Returns the squared-distance between the two given 2D vectors. |
| [`shz_vec3_distance_sqr`](https://sh4zam.com/api/vector/shz_vec3_distance_sqr/) | Returns the squared-distance between the two given 3D vectors. |
| [`shz_vec4_distance_sqr`](https://sh4zam.com/api/vector/shz_vec4_distance_sqr/) | Returns the squared-distance between the two given 4D vectors. |
| [`shz_vec2_move`](https://sh4zam.com/api/vector/shz_vec2_move/) | Returns the given 2D vector, translated towards the `target` by the given `max_distance`. |
| [`shz_vec3_move`](https://sh4zam.com/api/vector/shz_vec3_move/) | Returns the given 3D vector, translated towards the `target` by the given `max_distance`. |
| [`shz_vec4_move`](https://sh4zam.com/api/vector/shz_vec4_move/) | Returns the given 4D vector, translated towards the `target` by the given `max_distance`. |
| [`shz_vec2_lerp`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_reflect/) | Reflects the given 2D `incidence` vector against a surface with the given `normal`, returning the result. |
| [`shz_vec3_reflect`](https://sh4zam.com/api/vector/shz_vec3_reflect/) | Reflects the given 3D `incidence` vector against a surface with the given `normal`, returning the result. |
| [`shz_vec4_reflect`](https://sh4zam.com/api/vector/shz_vec4_reflect/) | Reflects the given 4D `incidence` vector against a surface with the given `normal`, returning the result. |
| [`shz_vec2_refract`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_cross/) | Returns the cross product, as a scalar, between two 2D vectors. |
| [`shz_vec3_cross`](https://sh4zam.com/api/vector/shz_vec3_cross/) | Returns the vector produced by taking the cross-product of the two given 3D vectors. |
| [`shz_vec2_project`](https://sh4zam.com/api/vector/shz_vec2_project/) | Returns the resulting vector from projecting the given 2D vector along the given (unit) axis. |
| [`shz_vec3_project`](https://sh4zam.com/api/vector/shz_vec3_project/) | Returns the resulting vector from projecting the given 3D vector along the given (unit) axis. |
| [`shz_vec4_project`](https://sh4zam.com/api/vector/shz_vec4_project/) | Returns the resulting vector from projecting the given 4D vector along the given (unit) axis. |
| [`shz_vec2_project_safe`](https://sh4zam.com/api/vector/shz_vec2_project_safe/) | Returns the resulting vector from projecting the given 2D vector along the given (unit) axis. |
| [`shz_vec3_project_safe`](https://sh4zam.com/api/vector/shz_vec3_project_safe/) | Returns the resulting vector from projecting the given 3D vector along the given (unit) axis. |
| [`shz_vec4_project_safe`](https://sh4zam.com/api/vector/shz_vec4_project_safe/) | Returns the resulting vector from projecting the given 4D vector along the given (unit) axis. |
| [`shz_vec3_reject`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec3_triple/) | Returns the 3D vector "triple product" between vector's `a`, `b`, and `c`. |
| [`shz_vec3_perp`](https://sh4zam.com/api/vector/shz_vec3_perp/) | Returns a vector which is perpendicular to the given vector. |
| [`shz_vec3_barycenter`](https://sh4zam.com/api/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`](https://sh4zam.com/api/vector/shz_vec3_orthonormalize/) | Returns 2 3D vectors which are normalized and orthogonal to the two input vectors. |
| [`shz_vec3_cubic_hermite`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_angle_between/) | Returns the angle formed between the given 2D vectors in radians. |
| [`shz_vec3_angle_between`](https://sh4zam.com/api/vector/shz_vec3_angle_between/) | Returns the angle formed between the given 3D vectors in radians. |
| [`shz_vec2_angle`](https://sh4zam.com/api/vector/shz_vec2_angle/) | Returns the angle formed between the positive X axis and the given 2D vector, in radians. |
| [`shz_vec3_angles`](https://sh4zam.com/api/vector/shz_vec3_angles/) | Returns the angles formed between the positive X axis and the given 3D vector, in radians. |
| [`shz_vec2_from_sincos`](https://sh4zam.com/api/vector/shz_vec2_from_sincos/) | Returns the 2D unit vector representing a rotation from the positive X axis. |
| [`shz_vec3_from_sincos`](https://sh4zam.com/api/vector/shz_vec3_from_sincos/) | Returns the 3D unit vector representing the given rotation angles relative to the positive X axis. |
| [`shz_vec2_from_angle`](https://sh4zam.com/api/vector/shz_vec2_from_angle/) | Returns the 2D unit vector representing a rotation from the positive X axis in radians. |
| [`shz_vec3_from_angles`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_rotate/) | Rotates the given 2D vector about the Z axis by the given angle in radians. |
| [`shz_vec3_rotate_x`](https://sh4zam.com/api/vector/shz_vec3_rotate_x/) | Rotates the given 3D vector about the X axis by the given angle in radians. |
| [`shz_vec3_rotate_y`](https://sh4zam.com/api/vector/shz_vec3_rotate_y/) | Rotates the given 3D vector about the Y axis by the given angle in radians. |
| [`shz_vec3_rotate_z`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_vec3/) | Extends a 2D vector to 3D, using `z` as the value of the Z component. |
| [`shz_vec2_vec4`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_swizzle/) | Returns a 2D vector whose elements are equal to the source vector's values at the given indices. |
| [`shz_vec3_swizzle`](https://sh4zam.com/api/vector/shz_vec3_swizzle/) | Returns a 3D vector whose elements are equal to the source vector's values at the given indices. |
| [`shz_vec4_swizzle`](https://sh4zam.com/api/vector/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`](https://sh4zam.com/api/vector/shz_vec2_t/) | 2D Vector type |
| [`shz_vec2`](https://sh4zam.com/api/vector/shz_vec2/) | Alternate typedef for the [`shz_vec2`](https://sh4zam.com/api/vector/shz_vec2/) struct for those who hate POSIX-style. |
| [`shz_vec3_t`](https://sh4zam.com/api/vector/shz_vec3_t/) | 3D Vector type |
| [`shz_vec3`](https://sh4zam.com/api/vector/shz_vec3/) | Alternate typedef for the [`shz_vec3`](https://sh4zam.com/api/vector/shz_vec3/) struct for those who hate POSIX-style. |
| [`shz_vec4_t`](https://sh4zam.com/api/vector/shz_vec4_t/) | 4D Vector type |
| [`shz_vec4`](https://sh4zam.com/api/vector/shz_vec4/) | Alternate typedef for the [`shz_vec4`](https://sh4zam.com/api/vector/shz_vec4/) struct for those who hate POSIX-style. |