# SH4ZAM: full documentation

Source: https://sh4zam.com/
Generated from upstream commit ba1e30c88d49df0311870b229e1dd860ef26c477 (v0.9.1). Each section below is one page; its URL is on the line after its title.


---
# SH4ZAM!

Source: https://sh4zam.com/

> Fast math library for the Sega Dreamcast's SH4 CPU. Hand-optimized C and C++ linear algebra, trig, scalar, complex and memory routines

`SH4ZAM` is a hand-optimized, general-purpose math and linear algebra library for harnessing the floating-point power of the SH4 processor in the Sega Dreamcast. It originally began as a collection of inline assembly routines developed specifically to accelerate the math in the Grand Theft Auto 3 and Vice City DC ports. These routines, along with many others from various contributors, have been separated and combined into a single standalone library, which can be leveraged to bring gainz to the Dreamcast and SuperH communities at large.

## Install

**KallistiOS:** already part of [kos-ports](https://github.com/KallistiOS/kos-ports). Or by hand:

```sh
cd kos-ports/sh4zam && make install
```

**CMake (any platform):**

```sh
mkdir build && cd build && cmake .. && make && make install
```

Then `#include <sh4zam/shz_sh4zam.h>` (C) or `<sh4zam/shz_sh4zam.hpp>` (C++) and link with `-lsh4zam`. Full steps in [Getting Started](https://sh4zam.com/guides/getting-started/).

## Usage

**C23**

```c
#include <sh4zam/shz_sh4zam.h>

int main(int argc, const char *argv[]) {
    shz_vec4_t vec1 = shz_vec4_init(2.0f, 3.0f, 4.0f, 1.0f);
    shz_vec4_t vec2 = shz_vec4_normalize(shz_vec4_scale(vec1, shz_sinf(SHZ_F_PI)));
    shz_mat4x4_t mat = {};

    shz_xmtrx_init_diagonal(vec2.x, vec2.y, vec2.z, vec2.w);
    shz_xmtrx_apply_rotation_x(shz_vec4_dot(vec1, vec2));
    shz_xmtrx_apply_translation(vec1.x, vec1.y, vec1.z);
    shz_xmtrx_store_4x4(&mat);

    shz_vec4_t vec3 = shz_xmtrx_transform_vec4(vec2);

    return 0;
}
```

**C++23**

```cpp
#include <sh4zam/shz_sh4zam.hpp>

int main(int argc, const char* argv[]) {
    shz::vec4 vec1(2.0f, 3.0f, 4.0f, 1.0f);
    shz::vec4 vec2 = shz::vec4(vec1 * shz::sinf(shz::pi_f)).direction();
    shz::mat4x4 mat {};

    shz::xmtrx::init_diagonal(vec2.x, vec2.y, vec2.z, vec2.w);
    shz::xmtrx::apply_rotation_x(vec1.dot(vec2));
    shz::xmtrx::apply_translation(vec1.x, vec1.y, vec1.z);
    shz::xmtrx::store(&mat);

    shz::vec4 vec3 = shz::xmtrx::transform(vec2);

    return 0;
}
```

C++ can still use the C API by design, and every C++ type is also compatible with its corresponding C type and C API, so you can mix and match. Where applicable, the C API also includes type-generic routines: `shz_vec_dot()` forwards to the proper routine based on the type of vectors passed to it.

## Features

- Dual, interoperable C17 and C++20 APIs
- Extra API features supported for C23 and C++23
- Ergonomic, overhead-free composition from either C or C++
- Clean header files, separating interface from implementation
- Constexpr evaluation handled for both C and C++
- Zero-cost conversion operators for interop with other APIs
- Meticulously optimized for latest SH-GCC version 16.x
- Rigorously unit tested and validated on physical hardware
- Heavily documented header files
- Software back-end for using SH4ZAM in cross-platform codebases

## APIs

- [Scalar](https://sh4zam.com/api/scalar/): Scalar math operations, including faster `<math.h>` replacements.
- [Trigonometry](https://sh4zam.com/api/trig/): Trig, inverse trig and hyperbolic functions, with `FSCA` sine/cosine pairs.
- [Vector](https://sh4zam.com/api/vector/): 2D, 3D and 4D vector types and operations.
- [Matrix](https://sh4zam.com/api/matrix/): 2x2, 3x3, 3x4, 4x3 and 4x4 matrix types, in memory.
- [Quaternion](https://sh4zam.com/api/quat/): Quaternion math operations, including slerp and squad.
- [XMTRX](https://sh4zam.com/api/xmtrx/): API for manipulating the 4x4 back-bank of FP registers, the SH4's active matrix.
- [Complex](https://sh4zam.com/api/complex/): Complex and imaginary math API, including an accelerated FFT.
- [Memory](https://sh4zam.com/api/memory/): Memory routines: `memcpy()` and `memmove()` replacements, store queues, cache control.
Every public symbol has its own page. The [cheatsheet](https://sh4zam.com/cheatsheet/) has the whole API on one page.

## Conventions

The following conventions are used throughout the API by default, unless otherwise specified:

| Convention | Description |
| --- | --- |
| Coordinates | Right-handed for world/view space, left-handed for screen/clip space, as with GL. |
| Matrices | Stored in column-major order, as with GL. |
| Quaternions | Stored in `<W, X, Y, Z>` order. |

More in [Conventions](https://sh4zam.com/concepts/conventions/) and [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/).

## Showcase

The following projects have been successfully accelerated with SH4ZAM and make great references:

| Project | Description |
| --- | --- |
| [Mario Kart 64 DC](https://github.com/jnmartin84/mk64-dc) | jnmartin's Mario Kart 64 DC port with SH4ZAM acceleration. |
| [Super Mario 64 DC](https://github.com/jnmartin84/sm64-dc) | Super Mario 64 DC port with SH4ZAM acceleration. |
| [Sonic Mania DC](https://github.com/michael-fadely/Sonic-Mania-Decompilation) | Sonic Mania DC port with SH4ZAM acceleration. |
| [Quake 2 DC](https://github.com/Bruceleeto/Quake2) | Port of Quake 2 to the DC, with SH4ZAM accelerated matrix math. |
| [Simulant Engine](https://gitlab.com/simulant/simulant) | General-purpose cross-platform engine backed by SH4ZAM math. |
| [Diddy Kong Racing DC](https://github.com/Bruceleeto/Diddy-Kong-Racing) | Rare's renowned N64 kart racer, ported to the DC. SH4ZAMed to all hell for gainz. |

All twenty projects are on the [Showcase](https://sh4zam.com/showcase/) page.

## Community

The `#sh4zam` channel within the [Simulant Discord Server](https://discord.gg/G2Ay9kxec2) for Dreamcast development is the best place to ask questions, get help, give feedback, or discuss anything relating to SH4ZAM. Also, feel free to [open tickets](https://github.com/gyrovorbis/sh4zam/issues) for any issues or feature requests.


---
# API Reference

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

> Every public SH4ZAM symbol, one page each, grouped by module

SH4ZAM 0.9.1 exposes 794 public C symbols across 10 modules, plus a C++ API in `namespace shz`. Every symbol has its own page at `/api/<module>/<name>/` with a Markdown twin at `/api/<module>/<name>.md`.

| Module | Header | Symbols | Description |
| --- | --- | --- | --- |
| [Scalar](https://sh4zam.com/api/scalar/) | `sh4zam/shz_scalar.h` | 56 | Scalar functions and utilities, including faster <math.h> replacements. |
| [Trigonometry](https://sh4zam.com/api/trig/) | `sh4zam/shz_trig.h` | 51 | Trig functions and utilities built around the SH4 FSCA instruction. |
| [Vector](https://sh4zam.com/api/vector/) | `sh4zam/shz_vector.h` | 229 | API for vector math: 2D, 3D and 4D vector types and operations. |
| [Quaternion](https://sh4zam.com/api/quat/) | `sh4zam/shz_quat.h` | 47 | Routines for quaternion math. |
| [Matrix](https://sh4zam.com/api/matrix/) | `sh4zam/shz_matrix.h` | 120 | In-memory matrix manipulation for 4x4 and smaller matrices. |
| [XMTRX](https://sh4zam.com/api/xmtrx/) | `sh4zam/shz_xmtrx.h` | 140 | API for managing the SH4's "active matrix", the 16 back-bank FP registers. |
| [Complex](https://sh4zam.com/api/complex/) | `sh4zam/shz_complex.h` | 52 | API for representing and operating on complex numbers, plus an SH4-optimized FFT. |
| [Memory](https://sh4zam.com/api/memory/) | `sh4zam/shz_mem.h` | 23 | Routines for copying memory, store queues, cache operations and prefetching. |
| [Compiler Definitions](https://sh4zam.com/api/cdefs/) | `sh4zam/shz_cdefs.h` | 67 | Preprocessor definitions: back-end and target detection, TLS model, utilities and aliasing types. |
| [Version](https://sh4zam.com/api/version/) | `sh4zam/shz_version.h` | 9 | Compile-time and link-time version checking of the SH4ZAM library. |

## Other ways in

- [C++ API](https://sh4zam.com/api/cpp/): `shz::vec3`, `shz::quat`, `shz::xmtrx` and the free-function aliases, mapped back to the C functions.
- [Cheatsheet](https://sh4zam.com/cheatsheet/): the whole API on one page, signature plus one line each.
- [`/api/index.json`](https://sh4zam.com/api/index.json): machine-readable symbol index ([schema](https://sh4zam.com/api/schema.json)). Per-module files live at `/api/<module>.json`.
- Search (top of every page) indexes symbol names and descriptions.

## Naming in one line

C functions are `shz_<module>_<verb>[_<qualifier>]`, types are `shz_<name>_t`, C++ lives in `namespace shz` with the `shz_` prefix dropped. Suffixes such as `_fsrra`, `_safe`, `_deg` and `_unaligned` change behavior; see [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/).


---
# Compiler Definitions API

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

> Preprocessor definitions: back-end and target detection, TLS model, utilities and aliasing types

This file contains commonly used preprocessor definitions used throughout the project: library-wide configuration defines, compiler detection, compiler attributes, the TLS model and conversion utilities. `SHZ_TARGET` is auto-detected from compiler macros, and `SHZ_BACKEND` selects the implementation: the SH4 back-end is chosen only when targeting SH4 in single-precision FPU mode, otherwise the portable software back-end is used. `SHZ_CONVERT()` performs a zero-cost conversion between layout-compatible types and is what the `_from()` and `_to()` adapters are built on. Upstream keeps the compiler attribute macros (`SHZ_INLINE`, `SHZ_FORCE_INLINE`, `SHZ_ALIGNAS`, ...) out of its reference; they appear here only when Doxygen exposes them.

- **C header:** `#include <sh4zam/shz_cdefs.h>`
- **C++ header:** `#include <sh4zam/shz_cdefs.hpp>`
- **Symbols:** 67

## Back-Ends

List of architectures which SH4ZAM can auto-detect.

| Symbol | Description |
| --- | --- |
| [`SHZ_SH4`](https://sh4zam.com/api/cdefs/SHZ_SH4/) | Back-end for the Dreamcast's SH4. |
| [`SHZ_PPC`](https://sh4zam.com/api/cdefs/SHZ_PPC/) | Back-end for the Gamecube/Wii's Gekko PPC. |
| [`SHZ_MIPS`](https://sh4zam.com/api/cdefs/SHZ_MIPS/) | Back-end for MIPS architectures. |
| [`SHZ_ARM`](https://sh4zam.com/api/cdefs/SHZ_ARM/) | Back-end for ARM architectures. |
| [`SHZ_X86_64`](https://sh4zam.com/api/cdefs/SHZ_X86_64/) | Back-end for x86_64 architectures. |
| [`SHZ_SPU`](https://sh4zam.com/api/cdefs/SHZ_SPU/) | Back-end for the Cell B/E SPU architecture. |
| [`SHZ_WASM`](https://sh4zam.com/api/cdefs/SHZ_WASM/) | Back-end for WebAssembly. |
| [`SHZ_SW`](https://sh4zam.com/api/cdefs/SHZ_SW/) | Generic C-based software back-end. |

## TLS Models

Defines for different mechanisms for thread-local storage.

| Symbol | Description |
| --- | --- |
| [`SHZ_TLS_DISABLED`](https://sh4zam.com/api/cdefs/SHZ_TLS_DISABLED/) | No thread-local variables. |
| [`SHZ_TLS_IMPLICIT`](https://sh4zam.com/api/cdefs/SHZ_TLS_IMPLICIT/) | Use `thread_local` keyword for TLS. |
| [`SHZ_TLS_PTHREAD`](https://sh4zam.com/api/cdefs/SHZ_TLS_PTHREAD/) | Use pthread unique keys for TLS. |
| [`SHZ_TLS_CTHREAD`](https://sh4zam.com/api/cdefs/SHZ_TLS_CTHREAD/) | Use C11 thread TSS keys for TLS. |

## Compiler Detection

Defines for identifying the detected compiler.

| Symbol | Description |
| --- | --- |
| [`SHZ_GNUC`](https://sh4zam.com/api/cdefs/SHZ_GNUC/) | Defined when building with a GCC-compatible compiler. |

## Utilities

Miscellaneous function-like macros

| Symbol | Description |
| --- | --- |
| [`SHZ_STRINGIFY_LITERAL`](https://sh4zam.com/api/cdefs/SHZ_STRINGIFY_LITERAL/) | Stringifies a literal expression. |
| [`SHZ_STRINGIFY`](https://sh4zam.com/api/cdefs/SHZ_STRINGIFY/) | Stringifies an expression *after* preprocessing, supporting macro expansion. |
| [`SHZ_COUNT_OF`](https://sh4zam.com/api/cdefs/SHZ_COUNT_OF/) | Returns the number of elements within a statically sized array. |
| [`SHZ_CONTAINER_OF`](https://sh4zam.com/api/cdefs/SHZ_CONTAINER_OF/) | Returns the containing structure from a pointer to one of its members. |
| [`SHZ_SWAP`](https://sh4zam.com/api/cdefs/SHZ_SWAP/) | Macro which swaps the two values held by `a` and `b`. |
| [`SHZ_DECLARE_STRUCT`](https://sh4zam.com/api/cdefs/SHZ_DECLARE_STRUCT/) | Macro which forward declares a struct and its typedef. |
| [`SHZ_DECLARE_STRUCT_ALIGNED`](https://sh4zam.com/api/cdefs/SHZ_DECLARE_STRUCT_ALIGNED/) | Macro which forward declares a manually aligned struct and its typedef. |

## TLS Utilities

Macros for declaring and managing thread-local variables.

| Symbol | Description |
| --- | --- |
| [`SHZ_TLS_DECL`](https://sh4zam.com/api/cdefs/SHZ_TLS_DECL/) | Declares a TLS variable with disabled model (so not thread-local). |
| [`SHZ_TLS_REF`](https://sh4zam.com/api/cdefs/SHZ_TLS_REF/) | References a TLS variable, with disabled model. |

## Aliasing Types

Types which may break C/C++'s strict aliasing rules

| Symbol | Description |
| --- | --- |
| [`shz_alias_int16_t`](https://sh4zam.com/api/cdefs/shz_alias_int16_t/) | int16_t type whose value may be aliased as another type. |
| [`shz_alias_uint16_t`](https://sh4zam.com/api/cdefs/shz_alias_uint16_t/) | uint16_t type whose value may be aliased as another type. |
| [`shz_alias_int32_t`](https://sh4zam.com/api/cdefs/shz_alias_int32_t/) | int32_t type whose value may be aliased as another type. |
| [`shz_alias_uint32_t`](https://sh4zam.com/api/cdefs/shz_alias_uint32_t/) | uint32_t type whose value may be aliased as another type. |
| [`shz_alias_float_t`](https://sh4zam.com/api/cdefs/shz_alias_float_t/) | float type whose value may be aliased as another type. |
| [`shz_alias_int64_t`](https://sh4zam.com/api/cdefs/shz_alias_int64_t/) | int64_t type whose value may be aliased as another type. |
| [`shz_alias_uint64_t`](https://sh4zam.com/api/cdefs/shz_alias_uint64_t/) | uint64_t type whose value may be aliased as another type. |
| [`shz_alias_double_t`](https://sh4zam.com/api/cdefs/shz_alias_double_t/) | double type whose value may be aliased as another type. |

## Macros

| Symbol | Description |
| --- | --- |
| [`SHZ_TARGET`](https://sh4zam.com/api/cdefs/SHZ_TARGET/) | Target architecture Determines the actual architecture we're building for. |
| [`SHZ_BACKEND`](https://sh4zam.com/api/cdefs/SHZ_BACKEND/) | SH4ZAM back-end Selects which SH4ZAM implementation to use for a given target. |
| [`SHZ_TLS_MODEL`](https://sh4zam.com/api/cdefs/SHZ_TLS_MODEL/) | thread_local storage. |

## Not in upstream reference

Public declarations that upstream keeps out of its Doxygen reference. Listed for completeness; prefer the documented API.

| Symbol | Description |
| --- | --- |
| [`SHZ_MSVC`](https://sh4zam.com/api/cdefs/SHZ_MSVC/) | Defined when building with Microsoft Visual C++. |
| [`SHZ_CLANG`](https://sh4zam.com/api/cdefs/SHZ_CLANG/) | Defined when bulding with Clang. |
| [`SHZ_MINGW64`](https://sh4zam.com/api/cdefs/SHZ_MINGW64/) | Defined when bulding with MinGW-w64. |
| [`SHZ_MINGW32`](https://sh4zam.com/api/cdefs/SHZ_MINGW32/) | Defined when building for 32-bit MinGW or other MinGW compiler(s). |
| [`SHZ_GCC`](https://sh4zam.com/api/cdefs/SHZ_GCC/) | Defined when building for GCC. |
| [`SHZ_ALIGNAS`](https://sh4zam.com/api/cdefs/SHZ_ALIGNAS/) | Forces a function or type to be aligned by `N` bytes. |
| [`SHZ_SIMD`](https://sh4zam.com/api/cdefs/SHZ_SIMD/) | Tells GCC that a scalar type is to be treated as a vector of size `N.` |
| [`SHZ_HOT`](https://sh4zam.com/api/cdefs/SHZ_HOT/) | Tells GCC that a particular function should be optimized for performance. |
| [`SHZ_COLD`](https://sh4zam.com/api/cdefs/SHZ_COLD/) | Tells GCC that a particular function should be optimized for size. |
| [`SHZ_FAST_MATH`](https://sh4zam.com/api/cdefs/SHZ_FAST_MATH/) | Put this before a function definition to tell GCC to use fast math optimizations on a specific function. |
| [`SHZ_NO_FAST_MATH`](https://sh4zam.com/api/cdefs/SHZ_NO_FAST_MATH/) | Put this before a function definition to tell GCC to NOT use fast math optimizations on a specific function. |
| [`SHZ_NO_UNROLL_LOOPS`](https://sh4zam.com/api/cdefs/SHZ_NO_UNROLL_LOOPS/) | Put this before a function definition to tell GCC to NOT unroll loops in a specific function. |
| [`SHZ_NO_OPTIMIZATION`](https://sh4zam.com/api/cdefs/SHZ_NO_OPTIMIZATION/) | Tells GCC to disable any optimizations when compiling a function. |
| [`SHZ_FUNC_ALIGNAS`](https://sh4zam.com/api/cdefs/SHZ_FUNC_ALIGNAS/) | Aligns a function within the .text segment by `N` bytes. |
| [`SHZ_FORCE_INLINE`](https://sh4zam.com/api/cdefs/SHZ_FORCE_INLINE/) | Forces GCC to inline the given function. |
| [`SHZ_NO_INLINE`](https://sh4zam.com/api/cdefs/SHZ_NO_INLINE/) | Prevents GCC from inlining the given function. |
| [`SHZ_FLATTEN`](https://sh4zam.com/api/cdefs/SHZ_FLATTEN/) | Forces GCC to inline all calls to other functions made within the tagged function. |
| [`SHZ_PACKED`](https://sh4zam.com/api/cdefs/SHZ_PACKED/) | Tells GCC not to introduce any extra padding for the given type. |
| [`SHZ_PURE`](https://sh4zam.com/api/cdefs/SHZ_PURE/) | Tells GCC the function has no effects other than returning a value that depends on its arguments and global variables. |
| [`SHZ_CONST`](https://sh4zam.com/api/cdefs/SHZ_CONST/) | Tells GCC the function has no effects other than returning a value that depends only on its arguments. |
| [`SHZ_ALIASING`](https://sh4zam.com/api/cdefs/SHZ_ALIASING/) | Tells GCC that the decorated pointer may be breaking strict aliasing rules for C and C++ |
| [`SHZ_DEPRECATED`](https://sh4zam.com/api/cdefs/SHZ_DEPRECATED/) | Emits a warning that a symbol has been deprecated with a message, upon use. |
| [`SHZ_LIKELY`](https://sh4zam.com/api/cdefs/SHZ_LIKELY/) | Tells GCC that the expression is likely to be true (used for conditional and loop optimizations) |
| [`SHZ_UNLIKELY`](https://sh4zam.com/api/cdefs/SHZ_UNLIKELY/) | Tells GCC that the expression is likely to be false (used for conditional and loop optimizations) |
| [`SHZ_RESTRICT`](https://sh4zam.com/api/cdefs/SHZ_RESTRICT/) | Tells GCC the pointer paraemter is unique and is not aliased by another parameter |
| [`SHZ_MEMORY_BARRIER_SOFT`](https://sh4zam.com/api/cdefs/SHZ_MEMORY_BARRIER_SOFT/) | Creates a software memory barrier beyond which any loads or stores may not be reordered |
| [`SHZ_MEMORY_BARRIER_HARD`](https://sh4zam.com/api/cdefs/SHZ_MEMORY_BARRIER_HARD/) | Creates a hardware memory barrier beyond which any loads or stores may not be reordered |
| [`SHZ_INSTR_BARRIER`](https://sh4zam.com/api/cdefs/SHZ_INSTR_BARRIER/) | Prevents the compiler from reordering instructions beyond the barrier. |
| [`SHZ_DECLS_BEGIN`](https://sh4zam.com/api/cdefs/SHZ_DECLS_BEGIN/) | Dummy define provided for C++ compatibility |
| [`SHZ_DECLS_END`](https://sh4zam.com/api/cdefs/SHZ_DECLS_END/) | Dummy define provided for C++ compatibility |
| [`SHZ_INLINE`](https://sh4zam.com/api/cdefs/SHZ_INLINE/) | Requests a function or member to be inlined (nonforcibly) OR to have static linkage. |
| [`SHZ_NOEXCEPT`](https://sh4zam.com/api/cdefs/SHZ_NOEXCEPT/) | Dummy define provided for C++ compatibility |
| [`SHZ_INIT`](https://sh4zam.com/api/cdefs/SHZ_INIT/) | Temporary struct initialization statement to use within C. |
| [`SHZ_CONVERT`](https://sh4zam.com/api/cdefs/SHZ_CONVERT/) | Conversion macro for zero-overhead conversions, taking the given `value` to a value of the given `type.` |


---
# shz_alias_double_t

Source: https://sh4zam.com/api/cdefs/shz_alias_double_t/

```c
typedef SHZ_ALIASING double shz_alias_double_t;
```

double type whose value may be aliased as another type.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:402`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L402)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Aliasing Types"


---
# shz_alias_float_t

Source: https://sh4zam.com/api/cdefs/shz_alias_float_t/

```c
typedef SHZ_ALIASING float shz_alias_float_t;
```

float type whose value may be aliased as another type.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:396`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L396)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Aliasing Types"


---
# shz_alias_int16_t

Source: https://sh4zam.com/api/cdefs/shz_alias_int16_t/

```c
typedef SHZ_ALIASING int16_t shz_alias_int16_t;
```

int16_t type whose value may be aliased as another type.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:388`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L388)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Aliasing Types"


---
# shz_alias_int32_t

Source: https://sh4zam.com/api/cdefs/shz_alias_int32_t/

```c
typedef SHZ_ALIASING int32_t shz_alias_int32_t;
```

int32_t type whose value may be aliased as another type.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:392`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L392)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Aliasing Types"


---
# shz_alias_int64_t

Source: https://sh4zam.com/api/cdefs/shz_alias_int64_t/

```c
typedef SHZ_ALIASING int64_t shz_alias_int64_t;
```

int64_t type whose value may be aliased as another type.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:398`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L398)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Aliasing Types"


---
# shz_alias_uint16_t

Source: https://sh4zam.com/api/cdefs/shz_alias_uint16_t/

```c
typedef SHZ_ALIASING uint16_t shz_alias_uint16_t;
```

uint16_t type whose value may be aliased as another type.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:390`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L390)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Aliasing Types"


---
# shz_alias_uint32_t

Source: https://sh4zam.com/api/cdefs/shz_alias_uint32_t/

```c
typedef SHZ_ALIASING uint32_t shz_alias_uint32_t;
```

uint32_t type whose value may be aliased as another type.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:394`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L394)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Aliasing Types"


---
# shz_alias_uint64_t

Source: https://sh4zam.com/api/cdefs/shz_alias_uint64_t/

```c
typedef SHZ_ALIASING uint64_t shz_alias_uint64_t;
```

uint64_t type whose value may be aliased as another type.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:400`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L400)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Aliasing Types"


---
# SHZ_ALIASING

Source: https://sh4zam.com/api/cdefs/SHZ_ALIASING/

```c
#define SHZ_ALIASING __attribute__((__may_alias__))
```

Tells GCC that the decorated pointer may be breaking strict aliasing rules for C and C++

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:181`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L181)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_ALIGNAS

Source: https://sh4zam.com/api/cdefs/SHZ_ALIGNAS/

> Forces a function or type to be aligned by N bytes

```c
#define SHZ_ALIGNAS(N) __attribute__((aligned((N))))
```

Forces a function or type to be aligned by `N` bytes.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:151`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L151)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_ARM

Source: https://sh4zam.com/api/cdefs/SHZ_ARM/

```c
#define SHZ_ARM 4
```

Back-end for ARM architectures.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:33`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L33)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Back-Ends"


---
# SHZ_BACKEND

Source: https://sh4zam.com/api/cdefs/SHZ_BACKEND/

```c
#define SHZ_BACKEND SHZ_SPU
```

SH4ZAM back-end Selects which SH4ZAM implementation to use for a given target.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:72`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L72)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Macros"


---
# SHZ_CLANG

Source: https://sh4zam.com/api/cdefs/SHZ_CLANG/

```c
#define SHZ_CLANG 1
```

Defined when bulding with Clang.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:111`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L111)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_COLD

Source: https://sh4zam.com/api/cdefs/SHZ_COLD/

```c
#define SHZ_COLD __attribute__((cold))
```

Tells GCC that a particular function should be optimized for size.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:157`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L157)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_CONST

Source: https://sh4zam.com/api/cdefs/SHZ_CONST/

```c
#define SHZ_CONST __attribute__((const))
```

Tells GCC the function has no effects other than returning a value that depends only on its arguments.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:179`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L179)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_CONTAINER_OF

Source: https://sh4zam.com/api/cdefs/SHZ_CONTAINER_OF/

```c
#define SHZ_CONTAINER_OF(ptr, type, member) ((type*)((char*)(ptr) - offsetof(type, member)))
```

Returns the containing structure from a pointer to one of its members.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ptr` |  |  |
| `type` |  |  |
| `member` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:135`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L135)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Utilities"


---
# SHZ_CONVERT

Source: https://sh4zam.com/api/cdefs/SHZ_CONVERT/

> Conversion macro for zero-overhead conversions, taking the given value to a value of the given type

```c
#define SHZ_CONVERT(type, value)
```

Conversion macro for zero-overhead conversions, taking the given `value` to a value of the given `type.`

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:261`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L261)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_COUNT_OF

Source: https://sh4zam.com/api/cdefs/SHZ_COUNT_OF/

```c
#define SHZ_COUNT_OF(array) (sizeof(array) / sizeof((array)[0]))
```

Returns the number of elements within a statically sized array.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `array` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:133`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L133)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Utilities"


---
# SHZ_DECLARE_STRUCT_ALIGNED

Source: https://sh4zam.com/api/cdefs/SHZ_DECLARE_STRUCT_ALIGNED/

```c
#define SHZ_DECLARE_STRUCT_ALIGNED(n, t, a) struct SHZ_ALIGNAS(a) n; typedef struct n t
```

Macro which forward declares a manually aligned struct and its typedef.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `n` |  |  |
| `t` |  |  |
| `a` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:141`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L141)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Utilities"


---
# SHZ_DECLARE_STRUCT

Source: https://sh4zam.com/api/cdefs/SHZ_DECLARE_STRUCT/

```c
#define SHZ_DECLARE_STRUCT(n, t) struct n; typedef struct n t
```

Macro which forward declares a struct and its typedef.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `n` |  |  |
| `t` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:139`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L139)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Utilities"


---
# SHZ_DECLS_BEGIN

Source: https://sh4zam.com/api/cdefs/SHZ_DECLS_BEGIN/

```c
#define SHZ_DECLS_BEGIN
```

Dummy define provided for C++ compatibility

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:247`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L247)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_DECLS_END

Source: https://sh4zam.com/api/cdefs/SHZ_DECLS_END/

```c
#define SHZ_DECLS_END
```

Dummy define provided for C++ compatibility

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:249`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L249)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_DEPRECATED

Source: https://sh4zam.com/api/cdefs/SHZ_DEPRECATED/

```c
#define SHZ_DEPRECATED(m) __attribute__((deprecated(m)))
```

Emits a warning that a symbol has been deprecated with a message, upon use.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:183`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L183)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_FAST_MATH

Source: https://sh4zam.com/api/cdefs/SHZ_FAST_MATH/

```c
#define SHZ_FAST_MATH __attribute__((optimize("fast-math")))
```

Put this before a function definition to tell GCC to use fast math optimizations on a specific function.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:159`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L159)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_FLATTEN

Source: https://sh4zam.com/api/cdefs/SHZ_FLATTEN/

```c
#define SHZ_FLATTEN __attribute__((flatten))
```

Forces GCC to inline all calls to other functions made within the tagged function.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:173`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L173)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_FORCE_INLINE

Source: https://sh4zam.com/api/cdefs/SHZ_FORCE_INLINE/

```c
#define SHZ_FORCE_INLINE __attribute__((always_inline)) SHZ_INLINE
```

Forces GCC to inline the given function.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:169`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L169)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_FUNC_ALIGNAS

Source: https://sh4zam.com/api/cdefs/SHZ_FUNC_ALIGNAS/

> Aligns a function within the .text segment by N bytes

```c
#define SHZ_FUNC_ALIGNAS(N) __attribute__((aligned(N)))
```

Aligns a function within the .text segment by `N` bytes.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:167`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L167)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_GCC

Source: https://sh4zam.com/api/cdefs/SHZ_GCC/

```c
#define SHZ_GCC 1
```

Defined when building for GCC.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:117`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L117)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_GNUC

Source: https://sh4zam.com/api/cdefs/SHZ_GNUC/

```c
#define SHZ_GNUC 1
```

Defined when building with a GCC-compatible compiler.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:120`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L120)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Compiler Detection"


---
# SHZ_HOT

Source: https://sh4zam.com/api/cdefs/SHZ_HOT/

```c
#define SHZ_HOT __attribute__((hot))
```

Tells GCC that a particular function should be optimized for performance.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:155`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L155)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_INIT

Source: https://sh4zam.com/api/cdefs/SHZ_INIT/

```c
#define SHZ_INIT(type, ...) ((type){ __VA_ARGS__ })
```

Temporary struct initialization statement to use within C.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:256`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L256)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_INLINE

Source: https://sh4zam.com/api/cdefs/SHZ_INLINE/

```c
#define SHZ_INLINE inline static
```

Requests a function or member to be inlined (nonforcibly) OR to have static linkage.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:251`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L251)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_INSTR_BARRIER

Source: https://sh4zam.com/api/cdefs/SHZ_INSTR_BARRIER/

```c
#define SHZ_INSTR_BARRIER() asm volatile("")
```

Prevents the compiler from reordering instructions beyond the barrier.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:195`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L195)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_LIKELY

Source: https://sh4zam.com/api/cdefs/SHZ_LIKELY/

```c
#define SHZ_LIKELY(e) __builtin_expect(!!(e), 1)
```

Tells GCC that the expression is likely to be true (used for conditional and loop optimizations)

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:185`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L185)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_MEMORY_BARRIER_HARD

Source: https://sh4zam.com/api/cdefs/SHZ_MEMORY_BARRIER_HARD/

```c
#define SHZ_MEMORY_BARRIER_HARD() __sync_synchronize()
```

Creates a hardware memory barrier beyond which any loads or stores may not be reordered

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:193`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L193)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_MEMORY_BARRIER_SOFT

Source: https://sh4zam.com/api/cdefs/SHZ_MEMORY_BARRIER_SOFT/

```c
#define SHZ_MEMORY_BARRIER_SOFT() asm volatile("" : : : "memory")
```

Creates a software memory barrier beyond which any loads or stores may not be reordered

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:191`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L191)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_MINGW32

Source: https://sh4zam.com/api/cdefs/SHZ_MINGW32/

```c
#define SHZ_MINGW32 1
```

Defined when building for 32-bit MinGW or other MinGW compiler(s).

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:115`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L115)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_MINGW64

Source: https://sh4zam.com/api/cdefs/SHZ_MINGW64/

```c
#define SHZ_MINGW64 1
```

Defined when bulding with MinGW-w64.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:113`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L113)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_MIPS

Source: https://sh4zam.com/api/cdefs/SHZ_MIPS/

```c
#define SHZ_MIPS 3
```

Back-end for MIPS architectures.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:32`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L32)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Back-Ends"


---
# SHZ_MSVC

Source: https://sh4zam.com/api/cdefs/SHZ_MSVC/

```c
#define SHZ_MSVC 1
```

Defined when building with Microsoft Visual C++.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:107`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L107)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_NO_FAST_MATH

Source: https://sh4zam.com/api/cdefs/SHZ_NO_FAST_MATH/

```c
#define SHZ_NO_FAST_MATH __attribute__((optimize("no-fast-math")))
```

Put this before a function definition to tell GCC to NOT use fast math optimizations on a specific function.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:161`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L161)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_NO_INLINE

Source: https://sh4zam.com/api/cdefs/SHZ_NO_INLINE/

```c
#define SHZ_NO_INLINE __attribute__((noinline))
```

Prevents GCC from inlining the given function.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:171`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L171)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_NO_OPTIMIZATION

Source: https://sh4zam.com/api/cdefs/SHZ_NO_OPTIMIZATION/

```c
#define SHZ_NO_OPTIMIZATION __attribute__((optimize("O0")))
```

Tells GCC to disable any optimizations when compiling a function.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:165`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L165)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_NO_UNROLL_LOOPS

Source: https://sh4zam.com/api/cdefs/SHZ_NO_UNROLL_LOOPS/

```c
#define SHZ_NO_UNROLL_LOOPS __attribute__((optimize("no-unroll-loops")))
```

Put this before a function definition to tell GCC to NOT unroll loops in a specific function.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:163`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L163)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_NOEXCEPT

Source: https://sh4zam.com/api/cdefs/SHZ_NOEXCEPT/

```c
#define SHZ_NOEXCEPT
```

Dummy define provided for C++ compatibility

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:253`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L253)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_PACKED

Source: https://sh4zam.com/api/cdefs/SHZ_PACKED/

```c
#define SHZ_PACKED __attribute__((packed))
```

Tells GCC not to introduce any extra padding for the given type.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:175`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L175)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_PPC

Source: https://sh4zam.com/api/cdefs/SHZ_PPC/

```c
#define SHZ_PPC 2
```

Back-end for the Gamecube/Wii's Gekko PPC.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:31`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L31)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Back-Ends"


---
# SHZ_PURE

Source: https://sh4zam.com/api/cdefs/SHZ_PURE/

```c
#define SHZ_PURE __attribute__((pure))
```

Tells GCC the function has no effects other than returning a value that depends on its arguments and global variables.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:177`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L177)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_RESTRICT

Source: https://sh4zam.com/api/cdefs/SHZ_RESTRICT/

```c
#define SHZ_RESTRICT __restrict__
```

Tells GCC the pointer paraemter is unique and is not aliased by another parameter

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:189`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L189)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_SH4

Source: https://sh4zam.com/api/cdefs/SHZ_SH4/

```c
#define SHZ_SH4 1
```

Back-end for the Dreamcast's SH4.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:30`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L30)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Back-Ends"


---
# SHZ_SIMD

Source: https://sh4zam.com/api/cdefs/SHZ_SIMD/

> Tells GCC that a scalar type is to be treated as a vector of size N

```c
#define SHZ_SIMD(N) __attribute__((vector_size((N))))
```

Tells GCC that a scalar type is to be treated as a vector of size `N.`

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:153`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L153)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_SPU

Source: https://sh4zam.com/api/cdefs/SHZ_SPU/

```c
#define SHZ_SPU 6
```

Back-end for the Cell B/E SPU architecture.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:35`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L35)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Back-Ends"


---
# SHZ_STRINGIFY_LITERAL

Source: https://sh4zam.com/api/cdefs/SHZ_STRINGIFY_LITERAL/

```c
#define SHZ_STRINGIFY_LITERAL(a) #a
```

Stringifies a literal expression.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:129`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L129)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Utilities"


---
# SHZ_STRINGIFY

Source: https://sh4zam.com/api/cdefs/SHZ_STRINGIFY/

> Stringifies an expression after preprocessing, supporting macro expansion

```c
#define SHZ_STRINGIFY(a) SHZ_STRINGIFY_LITERAL(a)
```

Stringifies an expression *after* preprocessing, supporting macro expansion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:131`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L131)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Utilities"


---
# SHZ_SW

Source: https://sh4zam.com/api/cdefs/SHZ_SW/

```c
#define SHZ_SW ~0
```

Generic C-based software back-end.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:37`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L37)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Back-Ends"


---
# SHZ_SWAP

Source: https://sh4zam.com/api/cdefs/SHZ_SWAP/

> Macro which swaps the two values held by a and b

```c
#define SHZ_SWAP(a, b) do { typeof(a) tmp = a; a = b; b = tmp; } while(false)
```

Macro which swaps the two values held by `a` and `b`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` |  |  |
| `b` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:137`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L137)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Utilities"


---
# SHZ_TARGET

Source: https://sh4zam.com/api/cdefs/SHZ_TARGET/

```c
#define SHZ_TARGET SHZ_SW
```

Target architecture Determines the actual architecture we're building for.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:60`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L60)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Macros"


---
# SHZ_TLS_CTHREAD

Source: https://sh4zam.com/api/cdefs/SHZ_TLS_CTHREAD/

```c
#define SHZ_TLS_CTHREAD 3
```

Use C11 thread TSS keys for TLS.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:85`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L85)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "TLS Models"


---
# SHZ_TLS_DECL

Source: https://sh4zam.com/api/cdefs/SHZ_TLS_DECL/

```c
#define SHZ_TLS_DECL(type, name, ...) static type name = __VA_ARGS__;
```

Declares a TLS variable with disabled model (so not thread-local).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `type` |  |  |
| `name` |  |  |
| `...` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:313`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L313)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "TLS Utilities"


---
# SHZ_TLS_DISABLED

Source: https://sh4zam.com/api/cdefs/SHZ_TLS_DISABLED/

```c
#define SHZ_TLS_DISABLED 0
```

No thread-local variables.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:82`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L82)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "TLS Models"


---
# SHZ_TLS_IMPLICIT

Source: https://sh4zam.com/api/cdefs/SHZ_TLS_IMPLICIT/

> Use thread_local keyword for TLS

```c
#define SHZ_TLS_IMPLICIT 1
```

Use `thread_local` keyword for TLS.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:83`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L83)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "TLS Models"


---
# SHZ_TLS_MODEL

Source: https://sh4zam.com/api/cdefs/SHZ_TLS_MODEL/

```c
#define SHZ_TLS_MODEL SHZ_TLS_IMPLICIT
```

thread_local storage.

## Details

Selects the model used to declare access thread-local variables.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:94`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L94)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Macros"


---
# SHZ_TLS_PTHREAD

Source: https://sh4zam.com/api/cdefs/SHZ_TLS_PTHREAD/

```c
#define SHZ_TLS_PTHREAD 2
```

Use pthread unique keys for TLS.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:84`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L84)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "TLS Models"


---
# SHZ_TLS_REF

Source: https://sh4zam.com/api/cdefs/SHZ_TLS_REF/

```c
#define SHZ_TLS_REF(name) (&name)
```

References a TLS variable, with disabled model.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `name` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:315`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L315)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "TLS Utilities"


---
# SHZ_UNLIKELY

Source: https://sh4zam.com/api/cdefs/SHZ_UNLIKELY/

```c
#define SHZ_UNLIKELY(e) __builtin_expect(!!(e), 0)
```

Tells GCC that the expression is likely to be false (used for conditional and loop optimizations)

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:187`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L187)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Not in upstream reference"


---
# SHZ_WASM

Source: https://sh4zam.com/api/cdefs/SHZ_WASM/

```c
#define SHZ_WASM 8
```

Back-end for WebAssembly.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:36`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L36)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Back-Ends"


---
# SHZ_X86_64

Source: https://sh4zam.com/api/cdefs/SHZ_X86_64/

```c
#define SHZ_X86_64 5
```

Back-end for x86_64 architectures.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_cdefs.h:34`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_cdefs.h#L34)
- **Module:** [Compiler Definitions](https://sh4zam.com/api/cdefs/), section "Back-Ends"


---
# Complex API

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

> API for representing and operating on complex numbers, plus an SH4-optimized FFT

The complex number API serves as a replacement for C and C++'s `<complex.h>`, offering fast, accelerated approximations for each routine. The API is mostly modeled after C99's `<complex.h>`, although it also supports being used from C++ via `shz::complex`. The API also features `shz_fft()`, an SH4 optimized fast-fourier transform.

- **C header:** `#include <sh4zam/shz_complex.h>`
- **C++ header:** `#include <sh4zam/shz_complex.hpp>`
- **C++ types:** [`shz::complex`](https://sh4zam.com/api/cpp/complex/)
- **Symbols:** 52

## Suffixes

Suffixes used in this module. The full list is in [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/).

- `_fsrra`: Uses `FSRRA` (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise.

## Preprocessor

Macros and preprocessor constants.

| Symbol | Description |
| --- | --- |
| [`SHZ_CMPLXF`](https://sh4zam.com/api/complex/SHZ_CMPLXF/) | Initializes a complex number. |
| [`SHZ_CMPLXF32`](https://sh4zam.com/api/complex/SHZ_CMPLXF32/) | Initializes a complex number. |
| [`SHZ_I`](https://sh4zam.com/api/complex/SHZ_I/) | Unit imaginary constant, 'I'. |

## Basic

Basic operations on complex numbers.

| Symbol | Description |
| --- | --- |
| [`shz_cinitf`](https://sh4zam.com/api/complex/shz_cinitf/) | Returns a complex number which has been initialized to contain the given component values. |
| [`shz_cpolarf`](https://sh4zam.com/api/complex/shz_cpolarf/) | Returns a complex number with a magnitude of `r`, and a phase angle of `theta` (in radians). |
| [`shz_cequalf`](https://sh4zam.com/api/complex/shz_cequalf/) | Checks for equality between two complex numbers with either an absolute or relative tolerance. |
| [`shz_crealf`](https://sh4zam.com/api/complex/shz_crealf/) | Returns the real component of a complex number. |
| [`shz_cimagf`](https://sh4zam.com/api/complex/shz_cimagf/) | Returns the imaginary component of a complex number. |

## Arithmetic

Arithmetic operations on complex numbers.

| Symbol | Description |
| --- | --- |
| [`shz_caddf`](https://sh4zam.com/api/complex/shz_caddf/) | Adds two complex numbers together and returns the result. |
| [`shz_csubf`](https://sh4zam.com/api/complex/shz_csubf/) | Subtracts `rhs` from `lhs` and returns the complex result. |
| [`shz_cmulf`](https://sh4zam.com/api/complex/shz_cmulf/) | Multiplies two complex numbers together, returning the complex result. |
| [`shz_cdivf`](https://sh4zam.com/api/complex/shz_cdivf/) | Divides `lhs` by `rhs`, returning the complex result. |
| [`shz_cscalef`](https://sh4zam.com/api/complex/shz_cscalef/) | Scales both componets of the complex number, `c`, by the value, `v`, returning the result. |
| [`shz_crecipf`](https://sh4zam.com/api/complex/shz_crecipf/) | Returns the multiplicative inverse or reciprocal of the complex number, `c`. |

## Manipulation

Extract or modify complex components.

| Symbol | Description |
| --- | --- |
| [`shz_cabsf`](https://sh4zam.com/api/complex/shz_cabsf/) | Returns the absolute value (or magnitude) of the complex number, `c`. |
| [`shz_inv_cabsf`](https://sh4zam.com/api/complex/shz_inv_cabsf/) | Returns the inverse of the absolute value (or inverse of the magnitude) of the complex number, `c`. |
| [`shz_cnormf`](https://sh4zam.com/api/complex/shz_cnormf/) | Returns the squared magnitude of the complex number, `c`. |
| [`shz_cargf`](https://sh4zam.com/api/complex/shz_cargf/) | Returns the phase angle of the complex number, `c`. |
| [`shz_conjf`](https://sh4zam.com/api/complex/shz_conjf/) | Returns the complex conjugate of `c`. |
| [`shz_cprojf`](https://sh4zam.com/api/complex/shz_cprojf/) | Calculates the projection of the complex number, `c`, onto the Riemann sphere. |

## Transcendental

Complex transcendental functions.

| Symbol | Description |
| --- | --- |
| [`shz_csqrtf`](https://sh4zam.com/api/complex/shz_csqrtf/) | Computes and returns the complex square root of `c`. |
| [`shz_cpowf`](https://sh4zam.com/api/complex/shz_cpowf/) | Raises the complex `base` to the complex `exp` power, returning a complex result. |
| [`shz_cexpf`](https://sh4zam.com/api/complex/shz_cexpf/) | Returns the complex base `e` exponential of `c`. |
| [`shz_clogf`](https://sh4zam.com/api/complex/shz_clogf/) | Computes and returns the complex natural logarithm of `c`. |
| [`shz_clog10f`](https://sh4zam.com/api/complex/shz_clog10f/) | Computes and returns the complex base 10 logarithm of `c`. |

## Spherical Trigonometry

Complex spherical trigonometric functions.

| Symbol | Description |
| --- | --- |
| [`shz_csinf`](https://sh4zam.com/api/complex/shz_csinf/) | Calculates and returns the complex sine of `c`. |
| [`shz_ccosf`](https://sh4zam.com/api/complex/shz_ccosf/) | Calculates and returns the complex cosine of `c`. |
| [`shz_ctanf`](https://sh4zam.com/api/complex/shz_ctanf/) | Calculates and returns the complex tangent of `c`. |
| [`shz_ccscf`](https://sh4zam.com/api/complex/shz_ccscf/) | Calculates and returns the complex cosecant of `c`. |
| [`shz_csecf`](https://sh4zam.com/api/complex/shz_csecf/) | Calculates and returns the complex secant of `c`. |
| [`shz_ccotf`](https://sh4zam.com/api/complex/shz_ccotf/) | Calculates and returns the complex cotangent of `c`. |
| [`shz_casinf`](https://sh4zam.com/api/complex/shz_casinf/) | Calculates and returns the complex arcsine of `c`. |
| [`shz_cacosf`](https://sh4zam.com/api/complex/shz_cacosf/) | Calculates and returns the complex arccosine of `c`. |
| [`shz_catanf`](https://sh4zam.com/api/complex/shz_catanf/) | Calculates and returns the complex arctangent of `c`. |
| [`shz_cacscf`](https://sh4zam.com/api/complex/shz_cacscf/) | Calculates and returns the complex arccosecant of `c`. |
| [`shz_casecf`](https://sh4zam.com/api/complex/shz_casecf/) | Calculates and returns the complex arcsecant of `c`. |
| [`shz_cacotf`](https://sh4zam.com/api/complex/shz_cacotf/) | Calculates and returns the complex arccotangent of `c`. |

## Hyperbolic Trigonometry

Complex hyperbolic trigonometric functions.

| Symbol | Description |
| --- | --- |
| [`shz_csinhf`](https://sh4zam.com/api/complex/shz_csinhf/) | Calculates and returns the complex hyperbolic sine of `c`. |
| [`shz_ccoshf`](https://sh4zam.com/api/complex/shz_ccoshf/) | Calculates and returns the complex hyperbolic cosine of `c`. |
| [`shz_ctanhf`](https://sh4zam.com/api/complex/shz_ctanhf/) | Calculates and returns the complex hyperbolic tangent of `c`. |
| [`shz_ccschf`](https://sh4zam.com/api/complex/shz_ccschf/) | Calculates and returns the complex hyperbolic cosecant of `c`. |
| [`shz_csechf`](https://sh4zam.com/api/complex/shz_csechf/) | Calculates and returns the complex hyperbolic secant of `c`. |
| [`shz_ccothf`](https://sh4zam.com/api/complex/shz_ccothf/) | Calculates and returns the complex hyperbolic cotangent of `c`. |
| [`shz_casinhf`](https://sh4zam.com/api/complex/shz_casinhf/) | Calculates and returns the complex hyperbolic arcsine of `c`. |
| [`shz_cacoshf`](https://sh4zam.com/api/complex/shz_cacoshf/) | Calculates and returns the complex hyperbolic arccosine of `c`. |
| [`shz_catanhf`](https://sh4zam.com/api/complex/shz_catanhf/) | Calculates and returns the complex hyperbolic arctangent of `c`. |
| [`shz_cacschf`](https://sh4zam.com/api/complex/shz_cacschf/) | Calculates and returns the complex hyperbolic arccosecant of `c`. |
| [`shz_casechf`](https://sh4zam.com/api/complex/shz_casechf/) | Calculates and returns the complex hyperbolic arcsecant of `c`. |
| [`shz_cacothf`](https://sh4zam.com/api/complex/shz_cacothf/) | Calculates and returns the complex hyperbolic arccotangent of `c`. |

## Signal Processing

Functions for processing complex signals.

| Symbol | Description |
| --- | --- |
| [`shz_fft`](https://sh4zam.com/api/complex/shz_fft/) | Fast Fourier Transform. |

## Types

| Symbol | Description |
| --- | --- |
| [`shz_complex_t`](https://sh4zam.com/api/complex/shz_complex_t/) | Represents a floating-point complex number real/imaginary pair. |
| [`shz_complex`](https://sh4zam.com/api/complex/shz_complex/) | [`shz_complex_t`](https://sh4zam.com/api/complex/shz_complex_t/) alias for those who don't like POSIX-style. |


---
# shz_cabsf

Source: https://sh4zam.com/api/complex/shz_cabsf/

> Returns the absolute value (or magnitude) of the complex number, c

```c
SHZ_INLINE float shz_cabsf(shz_complex_t c) SHZ_NOEXCEPT;
```

Returns the absolute value (or magnitude) of the complex number, `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::cabsf`](https://sh4zam.com/api/cpp/#shzcabsf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:108`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L108)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Manipulation"


---
# shz_cacosf

Source: https://sh4zam.com/api/complex/shz_cacosf/

> Calculates and returns the complex arccosine of c

```c
SHZ_INLINE shz_complex_t shz_cacosf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex arccosine of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cacosf`](https://sh4zam.com/api/cpp/#shzcacosf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:176`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L176)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_cacoshf

Source: https://sh4zam.com/api/complex/shz_cacoshf/

> Calculates and returns the complex hyperbolic arccosine of c

```c
SHZ_INLINE shz_complex_t shz_cacoshf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic arccosine of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cacoshf`](https://sh4zam.com/api/cpp/#shzcacoshf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:219`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L219)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_cacotf

Source: https://sh4zam.com/api/complex/shz_cacotf/

> Calculates and returns the complex arccotangent of c

```c
SHZ_INLINE shz_complex_t shz_cacotf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex arccotangent of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cacotf`](https://sh4zam.com/api/cpp/#shzcacotf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:188`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L188)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_cacothf

Source: https://sh4zam.com/api/complex/shz_cacothf/

> Calculates and returns the complex hyperbolic arccotangent of c

```c
SHZ_INLINE shz_complex_t shz_cacothf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic arccotangent of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cacothf`](https://sh4zam.com/api/cpp/#shzcacothf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:231`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L231)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_cacscf

Source: https://sh4zam.com/api/complex/shz_cacscf/

> Calculates and returns the complex arccosecant of c

```c
SHZ_INLINE shz_complex_t shz_cacscf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex arccosecant of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cacscf`](https://sh4zam.com/api/cpp/#shzcacscf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:182`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L182)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_cacschf

Source: https://sh4zam.com/api/complex/shz_cacschf/

> Calculates and returns the complex hyperbolic arccosecant of c

```c
SHZ_INLINE shz_complex_t shz_cacschf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic arccosecant of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cacschf`](https://sh4zam.com/api/cpp/#shzcacschf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:225`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L225)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_caddf

Source: https://sh4zam.com/api/complex/shz_caddf/

```c
SHZ_INLINE shz_complex_t shz_caddf(shz_complex_t lhs, shz_complex_t rhs) SHZ_NOEXCEPT;
```

Adds two complex numbers together and returns the result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `lhs` | `shz_complex_t` |  |
| `rhs` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::caddf`](https://sh4zam.com/api/cpp/#shzcaddf), [`shz::complex::operator+=`](https://sh4zam.com/api/cpp/complex/), [`shz::operator+`](https://sh4zam.com/api/cpp/#shzoperator+)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:83`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L83)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Arithmetic"


---
# shz_cargf

Source: https://sh4zam.com/api/complex/shz_cargf/

> Returns the phase angle of the complex number, c

```c
SHZ_INLINE float shz_cargf(shz_complex_t c) SHZ_NOEXCEPT;
```

Returns the phase angle of the complex number, `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::cargf`](https://sh4zam.com/api/cpp/#shzcargf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:117`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L117)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Manipulation"


---
# shz_casecf

Source: https://sh4zam.com/api/complex/shz_casecf/

> Calculates and returns the complex arcsecant of c

```c
SHZ_INLINE shz_complex_t shz_casecf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex arcsecant of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::casecf`](https://sh4zam.com/api/cpp/#shzcasecf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:185`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L185)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_casechf

Source: https://sh4zam.com/api/complex/shz_casechf/

> Calculates and returns the complex hyperbolic arcsecant of c

```c
SHZ_INLINE shz_complex_t shz_casechf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic arcsecant of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::casechf`](https://sh4zam.com/api/cpp/#shzcasechf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:228`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L228)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_casinf

Source: https://sh4zam.com/api/complex/shz_casinf/

> Calculates and returns the complex arcsine of c

```c
SHZ_INLINE shz_complex_t shz_casinf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex arcsine of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::casinf`](https://sh4zam.com/api/cpp/#shzcasinf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:173`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L173)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_casinhf

Source: https://sh4zam.com/api/complex/shz_casinhf/

> Calculates and returns the complex hyperbolic arcsine of c

```c
SHZ_INLINE shz_complex_t shz_casinhf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic arcsine of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::casinhf`](https://sh4zam.com/api/cpp/#shzcasinhf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:216`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L216)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_catanf

Source: https://sh4zam.com/api/complex/shz_catanf/

> Calculates and returns the complex arctangent of c

```c
SHZ_INLINE shz_complex_t shz_catanf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex arctangent of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::catanf`](https://sh4zam.com/api/cpp/#shzcatanf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:179`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L179)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_catanhf

Source: https://sh4zam.com/api/complex/shz_catanhf/

> Calculates and returns the complex hyperbolic arctangent of c

```c
SHZ_INLINE shz_complex_t shz_catanhf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic arctangent of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::catanhf`](https://sh4zam.com/api/cpp/#shzcatanhf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:222`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L222)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_ccosf

Source: https://sh4zam.com/api/complex/shz_ccosf/

> Calculates and returns the complex cosine of c

```c
SHZ_INLINE shz_complex_t shz_ccosf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex cosine of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::ccosf`](https://sh4zam.com/api/cpp/#shzccosf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:158`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L158)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_ccoshf

Source: https://sh4zam.com/api/complex/shz_ccoshf/

> Calculates and returns the complex hyperbolic cosine of c

```c
SHZ_INLINE shz_complex_t shz_ccoshf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic cosine of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::ccoshf`](https://sh4zam.com/api/cpp/#shzccoshf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:201`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L201)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_ccotf

Source: https://sh4zam.com/api/complex/shz_ccotf/

> Calculates and returns the complex cotangent of c

```c
SHZ_INLINE shz_complex_t shz_ccotf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex cotangent of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::ccotf`](https://sh4zam.com/api/cpp/#shzccotf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:170`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L170)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_ccothf

Source: https://sh4zam.com/api/complex/shz_ccothf/

> Calculates and returns the complex hyperbolic cotangent of c

```c
SHZ_INLINE shz_complex_t shz_ccothf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic cotangent of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::ccothf`](https://sh4zam.com/api/cpp/#shzccothf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:213`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L213)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_ccscf

Source: https://sh4zam.com/api/complex/shz_ccscf/

> Calculates and returns the complex cosecant of c

```c
SHZ_INLINE shz_complex_t shz_ccscf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex cosecant of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::ccscf`](https://sh4zam.com/api/cpp/#shzccscf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:164`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L164)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_ccschf

Source: https://sh4zam.com/api/complex/shz_ccschf/

> Calculates and returns the complex hyperbolic cosecant of c

```c
SHZ_INLINE shz_complex_t shz_ccschf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic cosecant of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::ccschf`](https://sh4zam.com/api/cpp/#shzccschf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:207`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L207)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_cdivf

Source: https://sh4zam.com/api/complex/shz_cdivf/

> Divides lhs by rhs, returning the complex result

```c
SHZ_INLINE shz_complex_t shz_cdivf(shz_complex_t lhs, shz_complex_t rhs) SHZ_NOEXCEPT;
```

Divides `lhs` by `rhs`, returning the complex result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `lhs` | `shz_complex_t` |  |
| `rhs` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cdivf`](https://sh4zam.com/api/cpp/#shzcdivf), [`shz::complex::operator/=`](https://sh4zam.com/api/cpp/complex/), [`shz::operator/`](https://sh4zam.com/api/cpp/#shzoperator/)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:92`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L92)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Arithmetic"


---
# shz_cequalf

Source: https://sh4zam.com/api/complex/shz_cequalf/

```c
SHZ_INLINE bool shz_cequalf(shz_complex_t lhs, shz_complex_t rhs) SHZ_NOEXCEPT;
```

Checks for equality between two complex numbers with either an absolute or relative tolerance.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `lhs` | `shz_complex_t` |  |
| `rhs` | `shz_complex_t` |  |

## Returns

`bool`

## Availability

- **C++ equivalent:** [`shz::cequalf`](https://sh4zam.com/api/cpp/#shzcequalf), [`shz::operator==`](https://sh4zam.com/api/cpp/#shzoperator==)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:67`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L67)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Basic"


---
# shz_cexpf

Source: https://sh4zam.com/api/complex/shz_cexpf/

> Returns the complex base e exponential of c

```c
SHZ_INLINE shz_complex_t shz_cexpf(shz_complex_t c) SHZ_NOEXCEPT;
```

Returns the complex base `e` exponential of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cexpf`](https://sh4zam.com/api/cpp/#shzcexpf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:139`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L139)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Transcendental"


---
# shz_cimagf

Source: https://sh4zam.com/api/complex/shz_cimagf/

```c
SHZ_INLINE float shz_cimagf(shz_complex_t c) SHZ_NOEXCEPT;
```

Returns the imaginary component of a complex number.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::cimagf`](https://sh4zam.com/api/cpp/#shzcimagf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:73`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L73)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Basic"


---
# shz_cinitf

Source: https://sh4zam.com/api/complex/shz_cinitf/

```c
SHZ_INLINE shz_complex_t shz_cinitf(float real, float imag) SHZ_NOEXCEPT;
```

Returns a complex number which has been initialized to contain the given component values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `real` | `float` |  |
| `imag` | `float` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cinitf`](https://sh4zam.com/api/cpp/#shzcinitf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:61`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L61)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Basic"


---
# shz_clog10f

Source: https://sh4zam.com/api/complex/shz_clog10f/

> Computes and returns the complex base 10 logarithm of c

```c
SHZ_INLINE shz_complex_t shz_clog10f(shz_complex_t c) SHZ_NOEXCEPT;
```

Computes and returns the complex base 10 logarithm of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::clog10f`](https://sh4zam.com/api/cpp/#shzclog10f)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:145`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L145)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Transcendental"


---
# shz_clogf

Source: https://sh4zam.com/api/complex/shz_clogf/

> Computes and returns the complex natural logarithm of c

```c
SHZ_INLINE shz_complex_t shz_clogf(shz_complex_t c) SHZ_NOEXCEPT;
```

Computes and returns the complex natural logarithm of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::clogf`](https://sh4zam.com/api/cpp/#shzclogf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:142`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L142)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Transcendental"


---
# SHZ_CMPLXF

Source: https://sh4zam.com/api/complex/SHZ_CMPLXF/

```c
#define SHZ_CMPLXF(x, y) shz_cinitf(x, y)
```

Initializes a complex number.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` |  |  |
| `y` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_complex.h:38`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L38)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Preprocessor"


---
# SHZ_CMPLXF32

Source: https://sh4zam.com/api/complex/SHZ_CMPLXF32/

```c
#define SHZ_CMPLXF32(x, y) SHZ_CMPLXF(x, y)
```

Initializes a complex number.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` |  |  |
| `y` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_complex.h:39`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L39)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Preprocessor"


---
# shz_cmulf

Source: https://sh4zam.com/api/complex/shz_cmulf/

```c
SHZ_INLINE shz_complex_t shz_cmulf(shz_complex_t lhs, shz_complex_t rhs) SHZ_NOEXCEPT;
```

Multiplies two complex numbers together, returning the complex result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `lhs` | `shz_complex_t` |  |
| `rhs` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cmulf`](https://sh4zam.com/api/cpp/#shzcmulf), [`shz::operator*`](https://sh4zam.com/api/cpp/#shzoperator*)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:89`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L89)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Arithmetic"


---
# shz_cnormf

Source: https://sh4zam.com/api/complex/shz_cnormf/

> Returns the squared magnitude of the complex number, c

```c
SHZ_INLINE float shz_cnormf(shz_complex_t c) SHZ_NOEXCEPT;
```

Returns the squared magnitude of the complex number, `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::cnormf`](https://sh4zam.com/api/cpp/#shzcnormf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:114`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L114)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Manipulation"


---
# shz_complex_t

Source: https://sh4zam.com/api/complex/shz_complex_t/

```c
typedef struct shz_complex {
    float real;     //!< The real portion of the complex number.
    float imag;     //!< The imaginary portion of the complex number.
} shz_complex_t;
```

Represents a floating-point complex number real/imaginary pair.

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `real` | `float` | The real portion of the complex number. |
| `imag` | `float` | The imaginary portion of the complex number. |

## Availability

- **C++ equivalent:** [`shz::complex`](https://sh4zam.com/api/cpp/complex/)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_complex.h:47`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L47)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Types"


---
# shz_complex

Source: https://sh4zam.com/api/complex/shz_complex/

> shz_complex_t alias for those who don't like POSIX-style

```c
typedef shz_complex_t shz_complex;
```

[`shz_complex_t`](https://sh4zam.com/api/complex/shz_complex_t/) alias for those who don't like POSIX-style.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_complex.h:53`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L53)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Types"


---
# shz_conjf

Source: https://sh4zam.com/api/complex/shz_conjf/

> Returns the complex conjugate of c

```c
SHZ_INLINE shz_complex_t shz_conjf(shz_complex_t c) SHZ_NOEXCEPT;
```

Returns the complex conjugate of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::conjf`](https://sh4zam.com/api/cpp/#shzconjf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:120`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L120)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Manipulation"


---
# shz_cpolarf

Source: https://sh4zam.com/api/complex/shz_cpolarf/

> Returns a complex number with a magnitude of r, and a phase angle of theta (in radians)

```c
SHZ_INLINE shz_complex_t shz_cpolarf(float r, float theta) SHZ_NOEXCEPT;
```

Returns a complex number with a magnitude of `r`, and a phase angle of `theta` (in radians).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `r` | `float` |  |
| `theta` | `float` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cpolarf`](https://sh4zam.com/api/cpp/#shzcpolarf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:64`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L64)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Basic"


---
# shz_cpowf

Source: https://sh4zam.com/api/complex/shz_cpowf/

> Raises the complex base to the complex exp power, returning a complex result

```c
SHZ_INLINE shz_complex_t shz_cpowf(shz_complex_t base, shz_complex_t exp) SHZ_NOEXCEPT;
```

Raises the complex `base` to the complex `exp` power, returning a complex result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `base` | `shz_complex_t` |  |
| `exp` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cpowf`](https://sh4zam.com/api/cpp/#shzcpowf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:136`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L136)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Transcendental"


---
# shz_cprojf

Source: https://sh4zam.com/api/complex/shz_cprojf/

> Calculates the projection of the complex number, c, onto the Riemann sphere

```c
SHZ_INLINE shz_complex_t shz_cprojf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates the projection of the complex number, `c`, onto the Riemann sphere.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cprojf`](https://sh4zam.com/api/cpp/#shzcprojf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:123`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L123)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Manipulation"


---
# shz_crealf

Source: https://sh4zam.com/api/complex/shz_crealf/

```c
SHZ_INLINE float shz_crealf(shz_complex_t c) SHZ_NOEXCEPT;
```

Returns the real component of a complex number.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::crealf`](https://sh4zam.com/api/cpp/#shzcrealf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:70`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L70)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Basic"


---
# shz_crecipf

Source: https://sh4zam.com/api/complex/shz_crecipf/

> Returns the multiplicative inverse or reciprocal of the complex number, c

```c
SHZ_INLINE shz_complex_t shz_crecipf(shz_complex_t c) SHZ_NOEXCEPT;
```

Returns the multiplicative inverse or reciprocal of the complex number, `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::crecipf`](https://sh4zam.com/api/cpp/#shzcrecipf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:98`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L98)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Arithmetic"


---
# shz_cscalef

Source: https://sh4zam.com/api/complex/shz_cscalef/

> Scales both componets of the complex number, c, by the value, v, returning the result

```c
SHZ_INLINE shz_complex_t shz_cscalef(shz_complex_t c, float v) SHZ_NOEXCEPT;
```

Scales both componets of the complex number, `c`, by the value, `v`, returning the result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |
| `v` | `float` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::cscalef`](https://sh4zam.com/api/cpp/#shzcscalef), [`shz::operator*`](https://sh4zam.com/api/cpp/#shzoperator*), [`shz::operator/`](https://sh4zam.com/api/cpp/#shzoperator/)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:95`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L95)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Arithmetic"


---
# shz_csecf

Source: https://sh4zam.com/api/complex/shz_csecf/

> Calculates and returns the complex secant of c

```c
SHZ_INLINE shz_complex_t shz_csecf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex secant of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::csecf`](https://sh4zam.com/api/cpp/#shzcsecf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:167`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L167)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_csechf

Source: https://sh4zam.com/api/complex/shz_csechf/

> Calculates and returns the complex hyperbolic secant of c

```c
SHZ_INLINE shz_complex_t shz_csechf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic secant of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::csechf`](https://sh4zam.com/api/cpp/#shzcsechf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:210`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L210)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_csinf

Source: https://sh4zam.com/api/complex/shz_csinf/

> Calculates and returns the complex sine of c

```c
SHZ_INLINE shz_complex_t shz_csinf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex sine of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::csinf`](https://sh4zam.com/api/cpp/#shzcsinf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:155`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L155)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_csinhf

Source: https://sh4zam.com/api/complex/shz_csinhf/

> Calculates and returns the complex hyperbolic sine of c

```c
SHZ_INLINE shz_complex_t shz_csinhf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic sine of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::csinhf`](https://sh4zam.com/api/cpp/#shzcsinhf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:198`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L198)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_csqrtf

Source: https://sh4zam.com/api/complex/shz_csqrtf/

> Computes and returns the complex square root of c

```c
SHZ_INLINE shz_complex_t shz_csqrtf(shz_complex_t c) SHZ_NOEXCEPT;
```

Computes and returns the complex square root of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::csqrtf`](https://sh4zam.com/api/cpp/#shzcsqrtf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:133`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L133)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Transcendental"


---
# shz_csubf

Source: https://sh4zam.com/api/complex/shz_csubf/

> Subtracts rhs from lhs and returns the complex result

```c
SHZ_INLINE shz_complex_t shz_csubf(shz_complex_t lhs, shz_complex_t rhs) SHZ_NOEXCEPT;
```

Subtracts `rhs` from `lhs` and returns the complex result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `lhs` | `shz_complex_t` |  |
| `rhs` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::complex::operator-=`](https://sh4zam.com/api/cpp/complex/), [`shz::csubf`](https://sh4zam.com/api/cpp/#shzcsubf), [`shz::operator-`](https://sh4zam.com/api/cpp/#shzoperator-)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:86`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L86)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Arithmetic"


---
# shz_ctanf

Source: https://sh4zam.com/api/complex/shz_ctanf/

> Calculates and returns the complex tangent of c

```c
SHZ_INLINE shz_complex_t shz_ctanf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex tangent of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::ctanf`](https://sh4zam.com/api/cpp/#shzctanf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:161`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L161)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Spherical Trigonometry"


---
# shz_ctanhf

Source: https://sh4zam.com/api/complex/shz_ctanhf/

> Calculates and returns the complex hyperbolic tangent of c

```c
SHZ_INLINE shz_complex_t shz_ctanhf(shz_complex_t c) SHZ_NOEXCEPT;
```

Calculates and returns the complex hyperbolic tangent of `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`shz_complex_t`

## Availability

- **C++ equivalent:** [`shz::ctanhf`](https://sh4zam.com/api/cpp/#shzctanhf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:204`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L204)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Hyperbolic Trigonometry"


---
# shz_fft

Source: https://sh4zam.com/api/complex/shz_fft/

```c
SHZ_INLINE void shz_fft(shz_complex_t* s, size_t size) SHZ_NOEXCEPT;
```

Fast Fourier Transform.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `s` | `shz_complex_t *` |  |
| `size` | `size_t` |  |

## Returns

Nothing (`void`).

## Details

Applies a fast fourier transform to convert the complex array of samples, `s`, of the given `size`, from the time to the frequency domain. The conversion is done in-place.

## Notes

- The underlying implementation uses the Radix2 variant of the Cooley-Tukey FFT algorithm, using an XMTRX-accelerated 2 point butterfly DIF.

## Warnings

- `size` must be a power-of-two!
- `s` must be aligned to 8-byte boundaries!
- This routine clobbers `XMTRX`!

## Availability

- **C++ equivalent:** [`shz::fft`](https://sh4zam.com/api/cpp/#shzfft)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:255`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L255)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Signal Processing"


---
# SHZ_I

Source: https://sh4zam.com/api/complex/SHZ_I/

```c
#define SHZ_I SHZ_CMPLXF32(0.0f, 1.0f)
```

Unit imaginary constant, 'I'.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_complex.h:40`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L40)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Preprocessor"


---
# shz_inv_cabsf

Source: https://sh4zam.com/api/complex/shz_inv_cabsf/

> Returns the inverse of the absolute value (or inverse of the magnitude) of the complex number, c

```c
SHZ_INLINE float shz_inv_cabsf(shz_complex_t c) SHZ_NOEXCEPT;
```

Returns the inverse of the absolute value (or inverse of the magnitude) of the complex number, `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c` | `shz_complex_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::inv_cabsf`](https://sh4zam.com/api/cpp/#shzinv_cabsf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_complex.h:111`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.h#L111)
- **Module:** [Complex](https://sh4zam.com/api/complex/), section "Manipulation"


---
# C++ API

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

> The SH4ZAM C++ API in namespace shz: classes, operators and aliases, mapped to the C functions they call

C++ code can still use the C API by design, and every C++ type is also compatible with its corresponding C types and C API, so you can mix and match.

Include `<sh4zam/shz_sh4zam.hpp>` (or a per-module `.hpp`). Vector, quaternion and matrix types derive from the C structs and add methods and operators; `shz::xmtrx` exposes the active matrix as static member functions; scalar and trig routines are `constexpr` aliases of the C functions with the `shz_` prefix dropped.

## Classes

| Class | C type | Header | Description |
| --- | --- | --- | --- |
| [`shz::vecN`](https://sh4zam.com/api/cpp/vecn/) | n/a | `sh4zam/shz_vector.hpp` | Common C++ base structure inherited by all vector types. |
| [`shz::vec2`](https://sh4zam.com/api/cpp/vec2/) | [`shz_vec2_t`](https://sh4zam.com/api/vector/shz_vec2_t/) | `sh4zam/shz_vector.hpp` | 2D Vector type |
| [`shz::vec3`](https://sh4zam.com/api/cpp/vec3/) | [`shz_vec3_t`](https://sh4zam.com/api/vector/shz_vec3_t/) | `sh4zam/shz_vector.hpp` | 3D Vector type |
| [`shz::vec4`](https://sh4zam.com/api/cpp/vec4/) | [`shz_vec4_t`](https://sh4zam.com/api/vector/shz_vec4_t/) | `sh4zam/shz_vector.hpp` | 4D Vector type |
| [`shz::quat`](https://sh4zam.com/api/cpp/quat/) | [`shz_quat_t`](https://sh4zam.com/api/quat/shz_quat_t/) | `sh4zam/shz_quat.hpp` | C++ structure representing a quaternion. |
| [`shz::mat4x4`](https://sh4zam.com/api/cpp/mat4x4/) | [`shz_mat4x4_t`](https://sh4zam.com/api/matrix/shz_mat4x4_t/) | `sh4zam/shz_matrix.hpp` |  |
| [`shz::xmtrx`](https://sh4zam.com/api/cpp/xmtrx/) | n/a | `sh4zam/shz_xmtrx.hpp` | Static structure around the 4x4 XMTRX FP register back-bank. |
| [`shz::sincos`](https://sh4zam.com/api/cpp/sincos/) | [`shz_sincos_t`](https://sh4zam.com/api/trig/shz_sincos_t/) | `sh4zam/shz_trig.hpp` | C++ sine/cosine approximation pairs. |
| [`shz::complex`](https://sh4zam.com/api/cpp/complex/) | [`shz_complex_t`](https://sh4zam.com/api/complex/shz_complex_t/) | `sh4zam/shz_complex.hpp` | C++ wrapper around a floating-point complex number, real/imaginary pair. |
| [`shz::version`](https://sh4zam.com/api/cpp/version/) | n/a | `sh4zam/shz_version.hpp` | Class representing a full SH4ZAM API version. |

## Scalar aliases

| C++ | C function | Description |
| --- | --- | --- |
| `shz::fminf` | [`shz_fminf`](https://sh4zam.com/api/scalar/shz_fminf/) | Returns the minimum value of two given floats. |
| `shz::fmaxf` | [`shz_fmaxf`](https://sh4zam.com/api/scalar/shz_fmaxf/) | Returns the maximum value of two given floats. |
| `shz::equalf` | [`shz_equalf`](https://sh4zam.com/api/scalar/shz_equalf/) | Checks for equality based on EITHER the absolute tolerance or relative tolerance, using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/). |
| `shz::equalf_abs` | [`shz_equalf_abs`](https://sh4zam.com/api/scalar/shz_equalf_abs/) | Checks for equality based on the absolute tolerance using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/). |
| `shz::equalf_rel` | [`shz_equalf_rel`](https://sh4zam.com/api/scalar/shz_equalf_rel/) | Checks for equality based on the relative tolerance using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/). |
| `shz::floorf` | [`shz_floorf`](https://sh4zam.com/api/scalar/shz_floorf/) | Replacement for the \<math.h> routine, floorf(). |
| `shz::ceilf` | [`shz_ceilf`](https://sh4zam.com/api/scalar/shz_ceilf/) | Replacement for the \<math.h> routine, ceilf(). |
| `shz::roundf` | [`shz_roundf`](https://sh4zam.com/api/scalar/shz_roundf/) | Replacement for the \<math.h> routine, roundf(). |
| `shz::truncf` | [`shz_truncf`](https://sh4zam.com/api/scalar/shz_truncf/) | Replacement for the \<math.h> routine, truncf(). |
| `shz::remainderf` | [`shz_remainderf`](https://sh4zam.com/api/scalar/shz_remainderf/) | Replacement for the \<math.h> routine, remainderf(). |
| `shz::fmodf` | [`shz_fmodf`](https://sh4zam.com/api/scalar/shz_fmodf/) | Replacement for the \<math.h> routine, fmodf(). |
| `shz::remquof` | [`shz_remquof`](https://sh4zam.com/api/scalar/shz_remquof/) | (Sorta) Replacement for the \<math.h> routine, remquof(). |
| `shz::clampf` | [`shz_clampf`](https://sh4zam.com/api/scalar/shz_clampf/) | Clamps a floating-point value by the given `min` and `max` values. |
| `shz::normalizef` | [`shz_normalizef`](https://sh4zam.com/api/scalar/shz_normalizef/) | Maps a value within the given range `from` to `to`, to be within the range of `0.0f += 1.0f`. |
| `shz::normalizef_fsrra` | [`shz_normalizef_fsrra`](https://sh4zam.com/api/scalar/shz_normalizef_fsrra/) | Maps a value within the given range `from` to `to`, to be within the range of `0.0f + 1.0f` more quickly, provided `to` - `from` is a positive difference. |
| `shz::remapf` | [`shz_remapf`](https://sh4zam.com/api/scalar/shz_remapf/) | Maps a value within the given range `inputStart` to `inputEnd`, to be within the range of `outputStart` to `outputEnd`. |
| `shz::remapf_fsrra` | [`shz_remapf_fsrra`](https://sh4zam.com/api/scalar/shz_remapf_fsrra/) | Maps a value within the given range `inputStart` to `inputEnd`, to be within the range of `outputStart` to `outputEnd` more quickly, provided the `outputEnd` - `outputStart` is a positive difference. |
| `shz::wrapf` | [`shz_wrapf`](https://sh4zam.com/api/scalar/shz_wrapf/) | Wraps the given `value` back to be within the range of `min` to `max`. |
| `shz::wrapf_fsrra` | [`shz_wrapf_fsrra`](https://sh4zam.com/api/scalar/shz_wrapf_fsrra/) | Wraps the given `value` back to be within the range of `min` to `max` more quickly, provided `max` - `min` is a positive difference. |
| `shz::fractf` | [`shz_fractf`](https://sh4zam.com/api/scalar/shz_fractf/) | Returns the fractional part of `x`, equivalent to GLSL `fract()`. |
| `shz::signf` | [`shz_signf`](https://sh4zam.com/api/scalar/shz_signf/) | Returns -1.0f if `x` \< 0, 0.0f if `x` == 0, or 1.0f if `x` > 0. |
| `shz::saturatef` | [`shz_saturatef`](https://sh4zam.com/api/scalar/shz_saturatef/) | Clamps `x` to the range \[0.0f, 1.0f\]. |
| `shz::fabsf` | [`shz_fabsf`](https://sh4zam.com/api/scalar/shz_fabsf/) | Replacement for the \<math.h> routine, fabsf(). |
| `shz::copysignf` | [`shz_copysignf`](https://sh4zam.com/api/scalar/shz_copysignf/) | Replacement for the \<math.h> routine, copysignf(). |
| `shz::fmaf` | [`shz_fmaf`](https://sh4zam.com/api/scalar/shz_fmaf/) | Replacement for the \<math.h> routine, fmaf(). |
| `shz::fdimf` | [`shz_fdimf`](https://sh4zam.com/api/scalar/shz_fdimf/) | Replacement for the \<math.h> routine, fdimf(),. |
| `shz::hypotf` | [`shz_hypotf`](https://sh4zam.com/api/scalar/shz_hypotf/) | Replacement for the \<math.h> routine, hypotf(). |
| `shz::lerpf` | [`shz_lerpf`](https://sh4zam.com/api/scalar/shz_lerpf/) | Returns a value that is linearly interpolated between `a` and `b` by the given ratio, `t`. |
| `shz::barycentric_lerpf` | [`shz_barycentric_lerpf`](https://sh4zam.com/api/scalar/shz_barycentric_lerpf/) | Returns a value that is barycentrically interpolated between `a`, `b`, and `c` using the given barycentric coordinates, `u` and `v`. |
| `shz::quadratic_roots` | [`shz_quadratic_roots`](https://sh4zam.com/api/scalar/shz_quadratic_roots/) | Uses the quadratic formula with the given coefficients to solve for the two roots, returning `true` if any real roots exist, and `false` if the roots are only imaginary. |
| `shz::randf` | [`shz_randf`](https://sh4zam.com/api/scalar/shz_randf/) | Returns a random floating-point number between `0.0f` and `1.0f`, using and updating the given seed. |
| `shz::randf_range` | [`shz_randf_range`](https://sh4zam.com/api/scalar/shz_randf_range/) | Returns a random floating-point number between `min` and `max`, using and updating the given seed. |
| `shz::stepf` | [`shz_stepf`](https://sh4zam.com/api/scalar/shz_stepf/) | returns 0.0f if x \< edge, otherwise 1.0f |
| `shz::smoothstepf` | [`shz_smoothstepf`](https://sh4zam.com/api/scalar/shz_smoothstepf/) | Returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. edge0 must be less than edge1 or result is undefined. |
| `shz::smoothstepf_safe` | [`shz_smoothstepf_safe`](https://sh4zam.com/api/scalar/shz_smoothstepf_safe/) | Returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. Accepts inverse edges. |
| `shz::cbrtf` | [`shz_cbrtf`](https://sh4zam.com/api/scalar/shz_cbrtf/) | Replacement for the \<math.h> routine, cbrtf(). |
| `shz::inv_sqrtf_fsrra` | [`shz_inv_sqrtf_fsrra`](https://sh4zam.com/api/scalar/shz_inv_sqrtf_fsrra/) | Calculates 1.0f/sqrtf( `x`), using a fast approximation. |
| `shz::inv_sqrtf` | [`shz_inv_sqrtf`](https://sh4zam.com/api/scalar/shz_inv_sqrtf/) | Calculates 1.0f/sqrtf( `x` ), using a fast approximation, while safely protecting against division-by-zero. |
| `shz::sqrtf_fsrra` | [`shz_sqrtf_fsrra`](https://sh4zam.com/api/scalar/shz_sqrtf_fsrra/) | Returns the fast approximate square root of the given value, `x`. |
| `shz::sqrtf` | [`shz_sqrtf`](https://sh4zam.com/api/scalar/shz_sqrtf/) | Returns the fast approximate square root of the given value, `x`, safely returning `0.0f` is `x` == `0.0f`. |
| `shz::invf_fsrra` | [`shz_invf_fsrra`](https://sh4zam.com/api/scalar/shz_invf_fsrra/) | Takes the inverse of `x` using a very fast approximation, returning a positive result. |
| `shz::invf` | [`shz_invf`](https://sh4zam.com/api/scalar/shz_invf/) | Takes the inverse of `x` using a slighty faster approximation than doing a full division, safely handling negative values. |
| `shz::divf_fsrra` | [`shz_divf_fsrra`](https://sh4zam.com/api/scalar/shz_divf_fsrra/) | Divides `num` by `denom` using a very fast approximation, which requires `denom` be a positive value. |
| `shz::divf` | [`shz_divf`](https://sh4zam.com/api/scalar/shz_divf/) | Divides `num` by `denom` using a slightly faster approximation, allowing `denom` to be negative. |
| `shz::dot6f` | [`shz_dot6f`](https://sh4zam.com/api/scalar/shz_dot6f/) | Takes two sets of 3D vectors as 3 floats and calculates their dot product using an approximation. |
| `shz::dot8f` | [`shz_dot8f`](https://sh4zam.com/api/scalar/shz_dot8f/) | Takes two sets of 4D vectors as 4 floats and calculates their dot product using an approximation. |
| `shz::mag_sqr3f` | [`shz_mag_sqr3f`](https://sh4zam.com/api/scalar/shz_mag_sqr3f/) | Takes a 3D vector as 3 floats and calculates its squared magnitude using a fast approximation. |
| `shz::mag_sqr4f` | [`shz_mag_sqr4f`](https://sh4zam.com/api/scalar/shz_mag_sqr4f/) | Takes a 4D vector as 4 floats and calculates its squared magnitude using a fast approximation. |
| `shz::pow2f` | [`shz_pow2f`](https://sh4zam.com/api/scalar/shz_pow2f/) | Fast approximation for raising 2 to a floating-point power. |
| `shz::powf` | [`shz_powf`](https://sh4zam.com/api/scalar/shz_powf/) | Fast approximation for C's powf(). |
| `shz::pow10f` | [`shz_pow10f`](https://sh4zam.com/api/scalar/shz_pow10f/) | Fast approximation of POSIX's pow10f(). |
| `shz::log2f` | [`shz_log2f`](https://sh4zam.com/api/scalar/shz_log2f/) | Fast approximation for C's log2f(). |
| `shz::logf` | [`shz_logf`](https://sh4zam.com/api/scalar/shz_logf/) | Fast approximation for C's logf(). |
| `shz::log10f` | [`shz_log10f`](https://sh4zam.com/api/scalar/shz_log10f/) | Fast approximation for C's log10f(). |
| `shz::expf` | [`shz_expf`](https://sh4zam.com/api/scalar/shz_expf/) | Fast approximation for C's expf(). |
| `shz::operator/` | [`shz_invf`](https://sh4zam.com/api/scalar/shz_invf/) | Takes the inverse of `x` using a slighty faster approximation than doing a full division, safely handling negative values. |
| `shz::operator/` | [`shz_invf`](https://sh4zam.com/api/scalar/shz_invf/) | Takes the inverse of `x` using a slighty faster approximation than doing a full division, safely handling negative values. |

## Trigonometry aliases

| C++ | C function | Description |
| --- | --- | --- |
| `shz::sincosu16` | [`shz_sincosu16`](https://sh4zam.com/api/trig/shz_sincosu16/) | Returns sinf()/cosf() pairs for the given unsigned 16-bit angle in radians. |
| `shz::sincosf` | [`shz_sincosf`](https://sh4zam.com/api/trig/shz_sincosf/) | Returns sinf()/cosf() pairs for the given floating-point angle in radians. |
| `shz::sincosf_deg` | [`shz_sincosf_deg`](https://sh4zam.com/api/trig/shz_sincosf_deg/) | Returns sinf/cosf() pairs for the given floating-point angle in degrees. |
| `shz::sincos_tanf` | [`shz_sincos_tanf`](https://sh4zam.com/api/trig/shz_sincos_tanf/) | Returns tanf() from the given pre-computed `sincos` pair. |
| `shz::sincos_secf` | [`shz_sincos_secf`](https://sh4zam.com/api/trig/shz_sincos_secf/) | Returns the floating-point secant (1.0f / cosf(x)) from the given pre-computed `sincos` pair. |
| `shz::sincos_cscf` | [`shz_sincos_cscf`](https://sh4zam.com/api/trig/shz_sincos_cscf/) | Returns the floating-point cosecant (1.0f / sinf(x)) from the given pre-computed `sincos` pair. |
| `shz::sincos_cotf` | [`shz_sincos_cotf`](https://sh4zam.com/api/trig/shz_sincos_cotf/) | Returns the floating-point cotangent (1.0f / tanf(x)) from the given pre-computed `sincos` pair. |
| `shz::sinf` | [`shz_sinf`](https://sh4zam.com/api/trig/shz_sinf/) | One-off routine for returning only sinf() from an angle in radians. |
| `shz::sinf_deg` | [`shz_sinf_deg`](https://sh4zam.com/api/trig/shz_sinf_deg/) | One-off routine for returning only sinf() from an angle in degrees. |
| `shz::cosf` | [`shz_cosf`](https://sh4zam.com/api/trig/shz_cosf/) | One-off routine for returning only cosf() from an angle in radians. |
| `shz::cosf_deg` | [`shz_cosf_deg`](https://sh4zam.com/api/trig/shz_cosf_deg/) | One-off routine for returning only cosf() from an angle in degrees. |
| `shz::tanf` | [`shz_tanf`](https://sh4zam.com/api/trig/shz_tanf/) | One-off routine for returning only tanf() from an angle in radians. |
| `shz::tanf_deg` | [`shz_tanf_deg`](https://sh4zam.com/api/trig/shz_tanf_deg/) | One-off routine for returning only tanf() from an angle in degrees. |
| `shz::secf` | [`shz_secf`](https://sh4zam.com/api/trig/shz_secf/) | One-off routine for returning only secant (1 / cos(x)) from an angle in radians. |
| `shz::secf_deg` | [`shz_secf_deg`](https://sh4zam.com/api/trig/shz_secf_deg/) | One-off routine for returning only secant (1 / cos(x)) from an angle in degrees. |
| `shz::cscf` | [`shz_cscf`](https://sh4zam.com/api/trig/shz_cscf/) | One-off routine for returning only cosecant (1 / sin(x)) from an angle in radians. |
| `shz::cscf_deg` | [`shz_cscf_deg`](https://sh4zam.com/api/trig/shz_cscf_deg/) | One-off routine for returning only cosecant (1 / sin(x)) from an angle in degrees. |
| `shz::cotf` | [`shz_cotf`](https://sh4zam.com/api/trig/shz_cotf/) | One-off routine for returning only cotangent (1 / tan(x)) from an angle in radians. |
| `shz::cotf_deg` | [`shz_cotf_deg`](https://sh4zam.com/api/trig/shz_cotf_deg/) | One-off routine for returning only cotangent (1 / cot(x)) from an angle in degrees. |
| `shz::atanf_unit` | [`shz_atanf_unit`](https://sh4zam.com/api/trig/shz_atanf_unit/) | Fast arctangent approximation for unit values between `0.0f` and `1.0f`. |
| `shz::atanf_q1` | [`shz_atanf_q1`](https://sh4zam.com/api/trig/shz_atanf_q1/) | Fast arctangent approximation for values lying within the first quadrant (`>= 0.0f`). |
| `shz::atanf` | [`shz_atanf`](https://sh4zam.com/api/trig/shz_atanf/) | Fast arctangent approximation; equvalent to C's atanf(). |
| `shz::atan2f` | [`shz_atan2f`](https://sh4zam.com/api/trig/shz_atan2f/) | Computes arctangent of `y / x`, using the signs of arguments to determine correct quadtrant. Equivalent to C's atan2f(). |
| `shz::asinf` | [`shz_asinf`](https://sh4zam.com/api/trig/shz_asinf/) | Fast arcsine approximation; equivalent to C's asinf(). |
| `shz::acosf` | [`shz_acosf`](https://sh4zam.com/api/trig/shz_acosf/) | Fast arccosine approximation; equivalent to C's acosf(). |
| `shz::asecf` | [`shz_asecf`](https://sh4zam.com/api/trig/shz_asecf/) | Fast arcsecant/inverse secant approximation, taking units in radians. |
| `shz::acscf` | [`shz_acscf`](https://sh4zam.com/api/trig/shz_acscf/) | Fast arccosecant/inverse cosecant approximation; taking units in radians. |
| `shz::acotf` | [`shz_acotf`](https://sh4zam.com/api/trig/shz_acotf/) | Fast arccotangent/inverse cotangent approximation; taking units in radians. |
| `shz::sinhf` | [`shz_sinhf`](https://sh4zam.com/api/trig/shz_sinhf/) | Fast hyperbolic sine function. |
| `shz::coshf` | [`shz_coshf`](https://sh4zam.com/api/trig/shz_coshf/) | Fast hyperbolic cosine function. |
| `shz::tanhf` | [`shz_tanhf`](https://sh4zam.com/api/trig/shz_tanhf/) | Fast hyperbolic tangent function. |
| `shz::cschf` | [`shz_cschf`](https://sh4zam.com/api/trig/shz_cschf/) | Fast hyperbolic cosecant function. |
| `shz::sechf` | [`shz_sechf`](https://sh4zam.com/api/trig/shz_sechf/) | Fast hyperbolic secant function. |
| `shz::cothf` | [`shz_cothf`](https://sh4zam.com/api/trig/shz_cothf/) | Fast hyperbolic cotangent function. |
| `shz::asinhf` | [`shz_asinhf`](https://sh4zam.com/api/trig/shz_asinhf/) | Fast hyperbolic arcsine function. |
| `shz::acoshf` | [`shz_acoshf`](https://sh4zam.com/api/trig/shz_acoshf/) | Fast hyperbolic arccosine function. |
| `shz::atanhf` | [`shz_atanhf`](https://sh4zam.com/api/trig/shz_atanhf/) | Fast hyperbolic arctangent function. |
| `shz::acschf` | [`shz_acschf`](https://sh4zam.com/api/trig/shz_acschf/) | Fast hyperbolic arccosecant function. |
| `shz::asechf` | [`shz_asechf`](https://sh4zam.com/api/trig/shz_asechf/) | Fast hyperbolic arcsecant function. |
| `shz::acothf` | [`shz_acothf`](https://sh4zam.com/api/trig/shz_acothf/) | Fast hyperbolic arccotangent function. |

## Vector aliases

| C++ | C function | Description |
| --- | --- | --- |
| `shz::operator+` | [`shz_vec_add`](https://sh4zam.com/api/vector/shz_vec_add/) | C type-generic vector addition. |
| `shz::operator-` | [`shz_vec_sub`](https://sh4zam.com/api/vector/shz_vec_sub/) | C type-generic vector subtraction. |
| `shz::operator*` | [`shz_vec_mul`](https://sh4zam.com/api/vector/shz_vec_mul/) | C type-generic vector multiplication. |
| `shz::operator/` | [`shz_vec_div`](https://sh4zam.com/api/vector/shz_vec_div/) | C type-generic vector division. |
| `shz::operator*` | [`shz_vec_scale`](https://sh4zam.com/api/vector/shz_vec_scale/) | C type-generic vector scaling. |
| `shz::operator*` | [`shz_vec_scale`](https://sh4zam.com/api/vector/shz_vec_scale/) | C type-generic vector scaling. |
| `shz::operator/` | [`shz_vec_scale`](https://sh4zam.com/api/vector/shz_vec_scale/) | C type-generic vector scaling. |
| `shz::operator/` | [`shz_vec_div`](https://sh4zam.com/api/vector/shz_vec_div/) | C type-generic vector division. |

## Complex aliases

| C++ | C function | Description |
| --- | --- | --- |
| `shz::csqrtf` | [`shz_csqrtf`](https://sh4zam.com/api/complex/shz_csqrtf/) | Computes and returns the complex square root of `c`. |
| `shz::cpowf` | [`shz_cpowf`](https://sh4zam.com/api/complex/shz_cpowf/) | Raises the complex `base` to the complex `exp` power, returning a complex result. |
| `shz::cexpf` | [`shz_cexpf`](https://sh4zam.com/api/complex/shz_cexpf/) | Returns the complex base `e` exponential of `c`. |
| `shz::clogf` | [`shz_clogf`](https://sh4zam.com/api/complex/shz_clogf/) | Computes and returns the complex natural logarithm of `c`. |
| `shz::clog10f` | [`shz_clog10f`](https://sh4zam.com/api/complex/shz_clog10f/) | Computes and returns the complex base 10 logarithm of `c`. |
| `shz::operator+` | [`shz_caddf`](https://sh4zam.com/api/complex/shz_caddf/) | Adds two complex numbers together and returns the result. |
| `shz::operator-` | [`shz_csubf`](https://sh4zam.com/api/complex/shz_csubf/) | Subtracts `rhs` from `lhs` and returns the complex result. |
| `shz::operator*` | [`shz_cmulf`](https://sh4zam.com/api/complex/shz_cmulf/) | Multiplies two complex numbers together, returning the complex result. |
| `shz::operator*` | [`shz_cscalef`](https://sh4zam.com/api/complex/shz_cscalef/) | Scales both componets of the complex number, `c`, by the value, `v`, returning the result. |
| `shz::operator/` | [`shz_cdivf`](https://sh4zam.com/api/complex/shz_cdivf/) | Divides `lhs` by `rhs`, returning the complex result. |
| `shz::operator/` | [`shz_cscalef`](https://sh4zam.com/api/complex/shz_cscalef/) | Scales both componets of the complex number, `c`, by the value, `v`, returning the result. |
| `shz::operator==` | [`shz_cequalf`](https://sh4zam.com/api/complex/shz_cequalf/) | Checks for equality between two complex numbers with either an absolute or relative tolerance. |
| `shz::cinitf` | [`shz_cinitf`](https://sh4zam.com/api/complex/shz_cinitf/) | Returns a complex number which has been initialized to contain the given component values. |
| `shz::cpolarf` | [`shz_cpolarf`](https://sh4zam.com/api/complex/shz_cpolarf/) | Returns a complex number with a magnitude of `r`, and a phase angle of `theta` (in radians). |
| `shz::cequalf` | [`shz_cequalf`](https://sh4zam.com/api/complex/shz_cequalf/) | Checks for equality between two complex numbers with either an absolute or relative tolerance. |
| `shz::crealf` | [`shz_crealf`](https://sh4zam.com/api/complex/shz_crealf/) | Returns the real component of a complex number. |
| `shz::cimagf` | [`shz_cimagf`](https://sh4zam.com/api/complex/shz_cimagf/) | Returns the imaginary component of a complex number. |
| `shz::caddf` | [`shz_caddf`](https://sh4zam.com/api/complex/shz_caddf/) | Adds two complex numbers together and returns the result. |
| `shz::csubf` | [`shz_csubf`](https://sh4zam.com/api/complex/shz_csubf/) | Subtracts `rhs` from `lhs` and returns the complex result. |
| `shz::cmulf` | [`shz_cmulf`](https://sh4zam.com/api/complex/shz_cmulf/) | Multiplies two complex numbers together, returning the complex result. |
| `shz::cdivf` | [`shz_cdivf`](https://sh4zam.com/api/complex/shz_cdivf/) | Divides `lhs` by `rhs`, returning the complex result. |
| `shz::cscalef` | [`shz_cscalef`](https://sh4zam.com/api/complex/shz_cscalef/) | Scales both componets of the complex number, `c`, by the value, `v`, returning the result. |
| `shz::crecipf` | [`shz_crecipf`](https://sh4zam.com/api/complex/shz_crecipf/) | Returns the multiplicative inverse or reciprocal of the complex number, `c`. |
| `shz::cabsf` | [`shz_cabsf`](https://sh4zam.com/api/complex/shz_cabsf/) | Returns the absolute value (or magnitude) of the complex number, `c`. |
| `shz::inv_cabsf` | [`shz_inv_cabsf`](https://sh4zam.com/api/complex/shz_inv_cabsf/) | Returns the inverse of the absolute value (or inverse of the magnitude) of the complex number, `c`. |
| `shz::cnormf` | [`shz_cnormf`](https://sh4zam.com/api/complex/shz_cnormf/) | Returns the squared magnitude of the complex number, `c`. |
| `shz::cargf` | [`shz_cargf`](https://sh4zam.com/api/complex/shz_cargf/) | Returns the phase angle of the complex number, `c`. |
| `shz::conjf` | [`shz_conjf`](https://sh4zam.com/api/complex/shz_conjf/) | Returns the complex conjugate of `c`. |
| `shz::cprojf` | [`shz_cprojf`](https://sh4zam.com/api/complex/shz_cprojf/) | Calculates the projection of the complex number, `c`, onto the Riemann sphere. |
| `shz::csinf` | [`shz_csinf`](https://sh4zam.com/api/complex/shz_csinf/) | Calculates and returns the complex sine of `c`. |
| `shz::ccosf` | [`shz_ccosf`](https://sh4zam.com/api/complex/shz_ccosf/) | Calculates and returns the complex cosine of `c`. |
| `shz::ctanf` | [`shz_ctanf`](https://sh4zam.com/api/complex/shz_ctanf/) | Calculates and returns the complex tangent of `c`. |
| `shz::ccscf` | [`shz_ccscf`](https://sh4zam.com/api/complex/shz_ccscf/) | Calculates and returns the complex cosecant of `c`. |
| `shz::csecf` | [`shz_csecf`](https://sh4zam.com/api/complex/shz_csecf/) | Calculates and returns the complex secant of `c`. |
| `shz::ccotf` | [`shz_ccotf`](https://sh4zam.com/api/complex/shz_ccotf/) | Calculates and returns the complex cotangent of `c`. |
| `shz::casinf` | [`shz_casinf`](https://sh4zam.com/api/complex/shz_casinf/) | Calculates and returns the complex arcsine of `c`. |
| `shz::cacosf` | [`shz_cacosf`](https://sh4zam.com/api/complex/shz_cacosf/) | Calculates and returns the complex arccosine of `c`. |
| `shz::catanf` | [`shz_catanf`](https://sh4zam.com/api/complex/shz_catanf/) | Calculates and returns the complex arctangent of `c`. |
| `shz::cacscf` | [`shz_cacscf`](https://sh4zam.com/api/complex/shz_cacscf/) | Calculates and returns the complex arccosecant of `c`. |
| `shz::casecf` | [`shz_casecf`](https://sh4zam.com/api/complex/shz_casecf/) | Calculates and returns the complex arcsecant of `c`. |
| `shz::cacotf` | [`shz_cacotf`](https://sh4zam.com/api/complex/shz_cacotf/) | Calculates and returns the complex arccotangent of `c`. |
| `shz::csinhf` | [`shz_csinhf`](https://sh4zam.com/api/complex/shz_csinhf/) | Calculates and returns the complex hyperbolic sine of `c`. |
| `shz::ccoshf` | [`shz_ccoshf`](https://sh4zam.com/api/complex/shz_ccoshf/) | Calculates and returns the complex hyperbolic cosine of `c`. |
| `shz::ctanhf` | [`shz_ctanhf`](https://sh4zam.com/api/complex/shz_ctanhf/) | Calculates and returns the complex hyperbolic tangent of `c`. |
| `shz::ccschf` | [`shz_ccschf`](https://sh4zam.com/api/complex/shz_ccschf/) | Calculates and returns the complex hyperbolic cosecant of `c`. |
| `shz::csechf` | [`shz_csechf`](https://sh4zam.com/api/complex/shz_csechf/) | Calculates and returns the complex hyperbolic secant of `c`. |
| `shz::ccothf` | [`shz_ccothf`](https://sh4zam.com/api/complex/shz_ccothf/) | Calculates and returns the complex hyperbolic cotangent of `c`. |
| `shz::casinhf` | [`shz_casinhf`](https://sh4zam.com/api/complex/shz_casinhf/) | Calculates and returns the complex hyperbolic arcsine of `c`. |
| `shz::cacoshf` | [`shz_cacoshf`](https://sh4zam.com/api/complex/shz_cacoshf/) | Calculates and returns the complex hyperbolic arccosine of `c`. |
| `shz::catanhf` | [`shz_catanhf`](https://sh4zam.com/api/complex/shz_catanhf/) | Calculates and returns the complex hyperbolic arctangent of `c`. |
| `shz::cacschf` | [`shz_cacschf`](https://sh4zam.com/api/complex/shz_cacschf/) | Calculates and returns the complex hyperbolic arccosecant of `c`. |
| `shz::casechf` | [`shz_casechf`](https://sh4zam.com/api/complex/shz_casechf/) | Calculates and returns the complex hyperbolic arcsecant of `c`. |
| `shz::cacothf` | [`shz_cacothf`](https://sh4zam.com/api/complex/shz_cacothf/) | Calculates and returns the complex hyperbolic arccotangent of `c`. |
| `shz::fft` | [`shz_fft`](https://sh4zam.com/api/complex/shz_fft/) | Fast Fourier Transform. |

## Memory aliases

| C++ | C function | Description |
| --- | --- | --- |
| `shz::dcache_alloc_line` | [`shz_dcache_alloc_line`](https://sh4zam.com/api/memory/shz_dcache_alloc_line/) | Intrinsic around the SH4 `MOVCA.L` instruction. |
| `shz::memcpy` | [`shz_memcpy`](https://sh4zam.com/api/memory/shz_memcpy/) | Generic drop-in fast memcpy() replacement. |
| `shz::memcpy1` | [`shz_memcpy1`](https://sh4zam.com/api/memory/shz_memcpy1/) | Copies an unaligned buffer to another one byte at a time. |
| `shz::memcpy2` | [`shz_memcpy2`](https://sh4zam.com/api/memory/shz_memcpy2/) | Copies from one 2-byte aligned buffer to another two bytes at a time. |
| `shz::memcpy4` | [`shz_memcpy4`](https://sh4zam.com/api/memory/shz_memcpy4/) | Copies a from one 4-byte aligned buffer to another 4 bytes at a time. |
| `shz::memcpy8` | [`shz_memcpy8`](https://sh4zam.com/api/memory/shz_memcpy8/) | Copies a from one 8-byte aligned buffer to another 8 bytes at a time. |
| `shz::memset8` | [`shz_memset8`](https://sh4zam.com/api/memory/shz_memset8/) | Assigns the given 8-byte `value` to the `bytes` in `dst`. |
| `shz::memcpy32` | [`shz_memcpy32`](https://sh4zam.com/api/memory/shz_memcpy32/) | Copies `bytes` from the `src` to the `dst` buffer in 32-byte chunks. |
| `shz::memcpy64` | [`shz_memcpy64`](https://sh4zam.com/api/memory/shz_memcpy64/) | Specialized memcpy() variant for copying multiples of 64-bytes. |
| `shz::memcpy2_8` | [`shz_memcpy2_8`](https://sh4zam.com/api/memory/shz_memcpy2_8/) | Copies 8 shorts from `src` to `dst`. |
| `shz::memcpy2_16` | [`shz_memcpy2_16`](https://sh4zam.com/api/memory/shz_memcpy2_16/) | Copies 16 shorts from `src` to `dst`. |
| `shz::memset2_16` | [`shz_memset2_16`](https://sh4zam.com/api/memory/shz_memset2_16/) | Sets the values of the 16 shorts pointed to by `dst` to the given `value`. |
| `shz::memcpy4_16` | [`shz_memcpy4_16`](https://sh4zam.com/api/memory/shz_memcpy4_16/) | Copies 16 4-byte, long values from `src` to `dst`. |
| `shz::memswap32_1` | [`shz_memswap32_1`](https://sh4zam.com/api/memory/shz_memswap32_1/) | Swaps the values within the given 32-byte buffers. |
| `shz::memswap32_1_xmtrx` | [`shz_memswap32_1_xmtrx`](https://sh4zam.com/api/memory/shz_memswap32_1_xmtrx/) | Swaps the values within the given 32-byte buffers, using XMTRX. |
| `shz::sq_memcpy32` | [`shz_sq_memcpy32`](https://sh4zam.com/api/memory/shz_sq_memcpy32/) | Copies `bytes` from `src` to `dst` in 32-byte chunks, using the Store Queues. |
| `shz::sq_memcpy32_xmtrx` | [`shz_sq_memcpy32_xmtrx`](https://sh4zam.com/api/memory/shz_sq_memcpy32_xmtrx/) | Copies `bytes` from `src` to `dst` in 32-byte chunks, using the Store Queues and XMTRX. |
| `shz::sq_memcpy32_1` | [`shz_sq_memcpy32_1`](https://sh4zam.com/api/memory/shz_sq_memcpy32_1/) | Copies `src` to `dst` in a single 32-byte transaction using the Store Queues. |
| `shz::sq_memcpy32_1_xmtrx` | [`shz_sq_memcpy32_1_xmtrx`](https://sh4zam.com/api/memory/shz_sq_memcpy32_1_xmtrx/) | Copies `src` to `dst` in a single 32-byte transaction using the Store Queues and XMTRX. |
| `shz::memmove` | [`shz_memmove`](https://sh4zam.com/api/memory/shz_memmove/) | Generic drop-in fast memmove() replacement. |
| `shz::memcpy128` | [`shz_memcpy128`](https://sh4zam.com/api/memory/shz_memcpy128/) | Specialized memcpy() variant for copying multiples of 128 bytes. |

## Constants

| C++ | Definition | Description |
| --- | --- | --- |
| `shz::fipr_max_error` | `constexpr float fipr_max_error = 0.1f;` |  |
| `shz::pi_f` | `constexpr float pi_f = SHZ_F_PI;` | Floating-point constant approximation for Pi. |
| `shz::tau_f` | `constexpr float tau_f = SHZ_F_TAU;` | Floating-point constant approximation for Pi\*2. |
| `shz::pi_f_2` | `constexpr float pi_f_2 = SHZ_F_PI_2;` | Floating-point constant approximation for Pi/2. |
| `shz::pi_f_4` | `constexpr float pi_f_4 = SHZ_F_PI_4;` | Floating-point constant approximation for Pi/4. |
| `shz::fsca_rad_factor` | `constexpr float fsca_rad_factor = SHZ_FSCA_RAD_FACTOR;` | Scaling factor used to scale the input to FSCA from radians. |
| `shz::fsca_deg_factor` | `constexpr float fsca_deg_factor = SHZ_FSCA_DEG_FACTOR;` | Scaling factor used to scale the input to FSCA from degrees. |


---
# shz::complex

Source: https://sh4zam.com/api/cpp/complex/

C++ wrapper around a floating-point complex number, real/imaginary pair.

- **Header:** `#include <sh4zam/shz_complex.hpp>` ([source](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_complex.hpp#L30))
- **C type:** [`shz_complex_t`](https://sh4zam.com/api/complex/shz_complex_t/) (layout-compatible; the C API accepts it directly)
- **Bases:** `shz_complex_t`

## Members

### complex

```cpp
complex() noexcept=default
complex(const complex &rhs) noexcept=default
complex(float re, float im=0.0f) noexcept
complex(const shz_complex_t &cplx) noexcept
complex(const volatile shz_complex_t &cplx) noexcept
```

Default constructor.

### operator+=

```cpp
complex & operator+=(const complex &rhs) noexcept
```

Adds and accumulates `rhs` onto the given complex number.

Calls: [`shz_caddf()`](https://sh4zam.com/api/complex/shz_caddf/)

### operator-=

```cpp
complex & operator-=(const complex &rhs) noexcept
```

Subtracts `rhs` from the given complex number, assigning it to the result.

Calls: [`shz_csubf()`](https://sh4zam.com/api/complex/shz_csubf/)

### operator*=

```cpp
complex & operator*=(const complex &rhs) noexcept
complex & operator*=(float scale) noexcept
```

Multiplies and accumulates `rhs` by the given complex number.

Calls: [`shz_cmulf()`](https://sh4zam.com/api/complex/shz_cmulf/), [`shz_cscalef()`](https://sh4zam.com/api/complex/shz_cscalef/)

### operator/=

```cpp
complex & operator/=(const complex &rhs) noexcept
```

Divides the given complex number by `rhs`, assigning it to the result.

Calls: [`shz_cdivf()`](https://sh4zam.com/api/complex/shz_cdivf/)

### imag

```cpp
float shz_complex_t::imag
```

The imaginary portion of the complex number.

Inherited from `shz::vecN`.

### real

```cpp
float shz_complex_t::real
```

The real portion of the complex number.

Inherited from `shz::vecN`.


---
# shz::mat4x4

Source: https://sh4zam.com/api/cpp/mat4x4/

> C++ class shz::mat4x4

C++ type `shz::mat4x4`.

- **Header:** `#include <sh4zam/shz_matrix.hpp>` ([source](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.hpp#L27))
- **C type:** [`shz_mat4x4_t`](https://sh4zam.com/api/matrix/shz_mat4x4_t/) (layout-compatible; the C API accepts it directly)
- **Bases:** `shz_mat4x4_t`

## Static functions

### copy

```cpp
static void copy(shz_mat4x4_t *lhs, const shz_mat4x4_t &rhs) noexcept
static void copy(shz_mat4x4_t *lhs, const float rhs[16]) noexcept
```

Calls: [`shz_mat4x4_copy()`](https://sh4zam.com/api/matrix/shz_mat4x4_copy/), [`shz_mat4x4_copy_unaligned()`](https://sh4zam.com/api/matrix/shz_mat4x4_copy_unaligned/)

### mult

```cpp
static void mult(shz_mat4x4_t *dst, const shz_mat4x4_t &lhs, const shz_mat4x4_t &rhs) noexcept
static void mult(shz_mat4x4_t *dst, const shz_mat4x4_t &lhs, const float rhs[16]) noexcept
```

Calls: [`shz_mat4x4_mult()`](https://sh4zam.com/api/matrix/shz_mat4x4_mult/), [`shz_mat4x4_mult_unaligned()`](https://sh4zam.com/api/matrix/shz_mat4x4_mult_unaligned/)

### mult_transpose

```cpp
static void mult_transpose(shz_mat4x4_t *dst, const shz_mat4x4_t &lhs, const shz_mat4x4_t &rhs) noexcept
static void mult_transpose(shz_mat4x4_t *dst, const shz_mat4x4_t &lhs, const float rhs[16]) noexcept
```

Calls: [`shz_mat4x4_mult_transpose()`](https://sh4zam.com/api/matrix/shz_mat4x4_mult_transpose/), [`shz_mat4x4_mult_transpose_unaligned()`](https://sh4zam.com/api/matrix/shz_mat4x4_mult_transpose_unaligned/)

## Members

### init_identity

```cpp
void init_identity() noexcept
```

Calls: [`shz_mat4x4_init_identity()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_identity/)

### init_identity_safe

```cpp
void init_identity_safe() noexcept
```

Calls: [`shz_mat4x4_init_identity()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_identity/)

### init_zero

```cpp
void init_zero() noexcept
```

Calls: [`shz_mat4x4_init_zero()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_zero/)

### init_one

```cpp
void init_one() noexcept
```

Calls: [`shz_mat4x4_init_one()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_one/)

### init_fill

```cpp
void init_fill(float value) noexcept
```

Calls: [`shz_mat4x4_init_fill()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_fill/)

### init_translation

```cpp
void init_translation(float x, float y, float z) noexcept
void init_translation(const vec3 &v) noexcept
```

Calls: [`shz_mat4x4_init_translation()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_translation/)

### init_scale

```cpp
void init_scale(float x, float y, float z) noexcept
void init_scale(const vec3 &v) noexcept
```

Calls: [`shz_mat4x4_init_scale()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_scale/)

### init_rotation_x

```cpp
void init_rotation_x(float angle) noexcept
```

Calls: [`shz_mat4x4_init_rotation_x()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_x/)

### init_rotation_y

```cpp
void init_rotation_y(float angle) noexcept
```

Calls: [`shz_mat4x4_init_rotation_y()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_y/)

### init_rotation_z

```cpp
void init_rotation_z(float angle) noexcept
```

Calls: [`shz_mat4x4_init_rotation_z()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_z/)

### init_rotation_xyz

```cpp
void init_rotation_xyz(float xAngle, float yAngle, float zAngle) noexcept
```

Calls: [`shz_mat4x4_init_rotation_xyz()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_xyz/)

### init_rotation_zyx

```cpp
void init_rotation_zyx(float zAngle, float yAngle, float xAngle) noexcept
```

Calls: [`shz_mat4x4_init_rotation_zyx()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_zyx/)

### init_rotation_zxy

```cpp
void init_rotation_zxy(float zAngle, float xAngle, float yAngle) noexcept
```

Calls: [`shz_mat4x4_init_rotation_zxy()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_zxy/)

### init_rotation_yxz

```cpp
void init_rotation_yxz(float yAngle, float xAngle, float zAngle) noexcept
```

Calls: [`shz_mat4x4_init_rotation_yxz()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_yxz/)

### init_rotation

```cpp
void init_rotation(float angle, float x, float y, float z) noexcept
void init_rotation(float angle, const vec3 &axis) noexcept
void init_rotation(const quat &q) noexcept
```

Calls: [`shz_mat4x4_init_rotation()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation/), [`shz_mat4x4_init_rotation_quat()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_quat/)

### init_rotation_dir

```cpp
void init_rotation_dir(float angle, float x, float y, float z) noexcept
void init_rotation_dir(float angle, const vec3 &dir) noexcept
```

Calls: [`shz_mat4x4_init_rotation_dir()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_dir/)

### init_diagonal

```cpp
void init_diagonal(float x, float y, float z, float w) noexcept
void init_diagonal(const vec4 &v) noexcept
```

Calls: [`shz_mat4x4_init_diagonal()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_diagonal/)

### init_upper_triangular

```cpp
void init_upper_triangular(float col1, const vec2 &col2, const vec3 &col3, const vec4 &col4) noexcept
```

Calls: [`shz_mat4x4_init_upper_triangular()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_upper_triangular/)

### init_lower_triangular

```cpp
void init_lower_triangular(const vec4 &col1, const vec3 &col2, const vec2 &col3, float col4) noexcept
```

Calls: [`shz_mat4x4_init_lower_triangular()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_lower_triangular/)

### init_symmetric_skew

```cpp
void init_symmetric_skew(float x, float y, float z) noexcept
void init_symmetric_skew(const vec3 &v) noexcept
```

Calls: [`shz_mat4x4_init_symmetric_skew()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_symmetric_skew/)

### init_outer_product

```cpp
void init_outer_product(const vec4 &v1, const vec4 &v2) noexcept
```

Calls: [`shz_mat4x4_init_outer_product()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_outer_product/)

### init_permutation_wxyz

```cpp
void init_permutation_wxyz() noexcept
```

Calls: [`shz_mat4x4_init_permutation_wxyz()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_permutation_wxyz/)

### init_permutation_yzwx

```cpp
void init_permutation_yzwx() noexcept
```

Calls: [`shz_mat4x4_init_permutation_yzwx()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_permutation_yzwx/)

### init_screen

```cpp
void init_screen(float width, float height) noexcept
```

Calls: [`shz_mat4x4_init_screen()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_screen/)

### init_lookat

```cpp
void init_lookat(const vec3 &eye, const vec3 &center, const vec3 &up) noexcept
```

Calls: [`shz_mat4x4_init_lookat()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_lookat/)

### init_ortho

```cpp
void init_ortho(float left, float right, float bottom, float top, float znear, float zfar) noexcept
```

Calls: [`shz_mat4x4_init_ortho()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_ortho/)

### init_frustum

```cpp
void init_frustum(float left, float right, float bottom, float top, float znear, float zfar) noexcept
```

Calls: [`shz_mat4x4_init_frustum()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_frustum/)

### init_perspective

```cpp
void init_perspective(float fov, float aspect, float znear) noexcept
```

Calls: [`shz_mat4x4_init_perspective()`](https://sh4zam.com/api/matrix/shz_mat4x4_init_perspective/)

### row

```cpp
vec4 row(size_t index) const noexcept
```

C++ wrapper for `shz_mat4x4_row()`.

Calls: [`shz_mat4x4_row()`](https://sh4zam.com/api/matrix/shz_mat4x4_row/)

### col

```cpp
vec4 col(size_t index) const noexcept
```

C++ wrapper for `shz_mat4x4_col()`.

Calls: [`shz_mat4x4_col()`](https://sh4zam.com/api/matrix/shz_mat4x4_col/)

### get_translation

```cpp
vec3 get_translation() const noexcept
```

Calls: [`shz_mat4x4_get_translation()`](https://sh4zam.com/api/matrix/shz_mat4x4_get_translation/)

### get_scale

```cpp
vec3 get_scale() const noexcept
```

Returns the scaling components from the inner 3x3 matrix of XMTRX, as a 3D vector.

Calls: [`shz_mat4x4_get_scale()`](https://sh4zam.com/api/matrix/shz_mat4x4_get_scale/)

### set_row

```cpp
void set_row(size_t index, vec4 values) noexcept
```

Calls: [`shz_mat4x4_set_row()`](https://sh4zam.com/api/matrix/shz_mat4x4_set_row/)

### set_col

```cpp
void set_col(size_t index, vec4 values) noexcept
```

Calls: [`shz_mat4x4_set_col()`](https://sh4zam.com/api/matrix/shz_mat4x4_set_col/)

### swap_rows

```cpp
void swap_rows(size_t row1, size_t row2) noexcept
```

Calls: [`shz_mat4x4_swap_rows()`](https://sh4zam.com/api/matrix/shz_mat4x4_swap_rows/)

### swap_cols

```cpp
void swap_cols(size_t col1, size_t col2) noexcept
```

Calls: [`shz_mat4x4_swap_cols()`](https://sh4zam.com/api/matrix/shz_mat4x4_swap_cols/)

### set_translation

```cpp
void set_translation(float x, float y, float z) noexcept
void set_translation(const vec3 &v) noexcept
```

Calls: [`shz_mat4x4_set_translation()`](https://sh4zam.com/api/matrix/shz_mat4x4_set_translation/)

### set_scale

```cpp
void set_scale(float x, float y, float z) noexcept
void set_scale(const vec3 &v) noexcept
```

Calls: [`shz_mat4x4_set_scale()`](https://sh4zam.com/api/matrix/shz_mat4x4_set_scale/)

### set_rotation

```cpp
void set_rotation(const quat &rot) noexcept
```

Calls: [`shz_mat4x4_set_rotation_quat()`](https://sh4zam.com/api/matrix/shz_mat4x4_set_rotation_quat/)

### set_diagonal

```cpp
void set_diagonal(float x, float y, float z, float w) noexcept
void set_diagonal(const vec4 &v) noexcept
```

Calls: [`shz_mat4x4_set_diagonal()`](https://sh4zam.com/api/matrix/shz_mat4x4_set_diagonal/)

### apply

```cpp
void apply(const shz_mat4x4_t &mat) noexcept
void apply(const float mat[16]) noexcept
```

Calls: [`shz_mat4x4_apply()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply/), [`shz_mat4x4_apply_unaligned()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_unaligned/)

### apply_transpose

```cpp
void apply_transpose(const shz_mat4x4_t &mat) noexcept
void apply_transpose(const float mat[16]) noexcept
```

Calls: [`shz_mat4x4_apply_transpose()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_transpose/), [`shz_mat4x4_apply_transpose_unaligned()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_transpose_unaligned/)

### apply_scale

```cpp
void apply_scale(float x, float y, float z) noexcept
void apply_scale(const vec3 &v) noexcept
```

Calls: [`shz_mat4x4_apply_scale()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_scale/)

### apply_translation

```cpp
void apply_translation(float x, float y, float z) noexcept
void apply_translation(const vec3 &v) noexcept
```

Calls: [`shz_mat4x4_apply_translation()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_translation/)

### apply_rotation_x

```cpp
void apply_rotation_x(float angle) noexcept
```

Calls: [`shz_mat4x4_apply_rotation_x()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_x/)

### apply_rotation_y

```cpp
void apply_rotation_y(float angle) noexcept
```

Calls: [`shz_mat4x4_apply_rotation_y()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_y/)

### apply_rotation_z

```cpp
void apply_rotation_z(float angle) noexcept
```

Calls: [`shz_mat4x4_apply_rotation_z()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_z/)

### apply_rotation_xyz

```cpp
void apply_rotation_xyz(float xAngle, float yAngle, float zAngle) noexcept
```

Calls: [`shz_mat4x4_apply_rotation_xyz()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_xyz/)

### apply_rotation_zyx

```cpp
void apply_rotation_zyx(float zAngle, float yAngle, float xAngle) noexcept
```

Calls: [`shz_mat4x4_apply_rotation_zyx()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_zyx/)

### apply_rotation_zxy

```cpp
void apply_rotation_zxy(float zAngle, float xAngle, float yAngle) noexcept
```

Calls: [`shz_mat4x4_apply_rotation_zxy()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_zxy/)

### apply_rotation_yxz

```cpp
void apply_rotation_yxz(float yAngle, float xAngle, float zAngle) noexcept
```

Calls: [`shz_mat4x4_apply_rotation_yxz()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_yxz/)

### apply_rotation

```cpp
void apply_rotation(float angle, float x, float y, float z) noexcept
void apply_rotation(float angle, vec3 axis) noexcept
void apply_rotation(const quat &q) noexcept
```

Calls: [`shz_mat4x4_apply_rotation()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation/), [`shz_mat4x4_apply_rotation_quat()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_quat/)

### apply_lookat

```cpp
void apply_lookat(vec3 pos, vec3 target, vec3 up) noexcept
```

Calls: [`shz_mat4x4_apply_lookat()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_lookat/)

### apply_ortho

```cpp
void apply_ortho(float left, float right, float bottom, float top, float znear, float zfar) noexcept
```

Calls: [`shz_mat4x4_apply_ortho()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_ortho/)

### apply_frustum

```cpp
void apply_frustum(float left, float right, float bottom, float top, float znear, float zfar) noexcept
```

Calls: [`shz_mat4x4_apply_frustum()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_frustum/)

### apply_perspective

```cpp
void apply_perspective(float fov, float aspect, float znear) noexcept
```

Calls: [`shz_mat4x4_apply_perspective()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_perspective/)

### apply_screen

```cpp
void apply_screen(float width, float height) noexcept
```

Calls: [`shz_mat4x4_apply_screen()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_screen/)

### apply_symmetric_skew

```cpp
void apply_symmetric_skew(float x, float y, float z) noexcept
```

Calls: [`shz_mat4x4_apply_symmetric_skew()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_symmetric_skew/)

### apply_permutation_wxyz

```cpp
void apply_permutation_wxyz() noexcept
```

Calls: [`shz_mat4x4_apply_permutation_wxyz()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_permutation_wxyz/)

### apply_permutation_yzwx

```cpp
void apply_permutation_yzwx() noexcept
```

Calls: [`shz_mat4x4_apply_permutation_yzwx()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_permutation_yzwx/)

### apply_self

```cpp
void apply_self() noexcept
```

Calls: [`shz_mat4x4_apply_self()`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_self/)

### translate

```cpp
void translate(float x, float y, float z) noexcept
void translate(vec3 v) noexcept
```

Calls: [`shz_mat4x4_translate()`](https://sh4zam.com/api/matrix/shz_mat4x4_translate/)

### scale

```cpp
void scale(float x, float y, float z) noexcept
void scale(vec3 v) noexcept
```

Calls: [`shz_mat4x4_scale()`](https://sh4zam.com/api/matrix/shz_mat4x4_scale/)

### rotate_x

```cpp
void rotate_x(float radians) noexcept
```

Calls: [`shz_mat4x4_rotate_x()`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_x/)

### rotate_y

```cpp
void rotate_y(float radians) noexcept
```

Calls: [`shz_mat4x4_rotate_y()`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_y/)

### rotate_z

```cpp
void rotate_z(float radians) noexcept
```

Calls: [`shz_mat4x4_rotate_z()`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_z/)

### rotate_xyz

```cpp
void rotate_xyz(float xRadians, float yRadians, float zRadians) noexcept
```

Calls: [`shz_mat4x4_rotate_xyz()`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_xyz/)

### rotate_zyx

```cpp
void rotate_zyx(float zRadians, float yRadians, float xRadians) noexcept
```

Calls: [`shz_mat4x4_rotate_zyx()`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_zyx/)

### rotate_zxy

```cpp
void rotate_zxy(float zRadians, float xRadians, float yRadians) noexcept
```

Calls: [`shz_mat4x4_rotate_zxy()`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_zxy/)

### rotate_yxz

```cpp
void rotate_yxz(float yRadians, float xRadians, float zRadians) noexcept
```

Calls: [`shz_mat4x4_rotate_yxz()`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_yxz/)

### rotate

```cpp
void rotate(float radians, float xAxis, float yAxis, float zAxis) noexcept
void rotate(float radians, vec3 axis) noexcept
```

Calls: [`shz_mat4x4_rotate()`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate/)

### translate_reverse

```cpp
void translate_reverse(float x, float y, float z) noexcept
void translate_reverse(const shz::vec3 &pos) noexcept
```

Pre-multiplies and accumulates the given matrix onto the 3D translation matrix with the given components.

Calls: [`shz_mat4x4_translate_reverse()`](https://sh4zam.com/api/matrix/shz_mat4x4_translate_reverse/)

### scale_reverse

```cpp
void scale_reverse(float x, float y, float z) noexcept
void scale_reverse(const shz::vec3 &size) noexcept
```

Pre-multiplies and accumulates the given matrix onto the 3D scaling matrix with the given components.

Calls: [`shz_mat4x4_scale_reverse()`](https://sh4zam.com/api/matrix/shz_mat4x4_scale_reverse/)

### transform

```cpp
vec2 transform(const vec2 &in) const noexcept
vec3 transform(const vec3 &in) const noexcept
vec4 transform(const vec4 &in) const noexcept
```

Calls: [`shz_mat4x4_transform_vec2()`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec2/), [`shz_mat4x4_transform_vec3()`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec3/), [`shz_mat4x4_transform_vec4()`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec4/)

### transform_point

```cpp
vec2 transform_point(const vec2 &pt) const noexcept
vec3 transform_point(const vec3 &pt) const noexcept
```

Calls: [`shz_mat4x4_transform_point2()`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_point2/), [`shz_mat4x4_transform_point3()`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_point3/)

### transform_transpose

```cpp
vec2 transform_transpose(const vec2 &in) const noexcept
vec3 transform_transpose(const vec3 &in) const noexcept
vec4 transform_transpose(const vec4 &in) const noexcept
```

Calls: [`shz_mat4x4_transform_vec2_transpose()`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec2_transpose/), [`shz_mat4x4_transform_vec3_transpose()`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec3_transpose/), [`shz_mat4x4_transform_vec4_transpose()`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec4_transpose/)

### transform_point_transpose

```cpp
vec2 transform_point_transpose(const vec2 &pt) const noexcept
vec3 transform_point_transpose(const vec3 &pt) const noexcept
```

Calls: [`shz_mat4x4_transform_point2_transpose()`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_point2_transpose/), [`shz_mat4x4_transform_point3_transpose()`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_point3_transpose/)

### to_quat

```cpp
quat to_quat() const noexcept
```

Calls: [`shz_mat4x4_to_quat()`](https://sh4zam.com/api/matrix/shz_mat4x4_to_quat/)

### determinant

```cpp
float determinant() const noexcept
```

Calls: [`shz_mat4x4_determinant()`](https://sh4zam.com/api/matrix/shz_mat4x4_determinant/)

### trace

```cpp
float trace() const noexcept
```

Calls: [`shz_mat4x4_trace()`](https://sh4zam.com/api/matrix/shz_mat4x4_trace/)

### inverse

```cpp
void inverse(mat4x4 *out) const noexcept
```

Calls: [`shz_mat4x4_inverse()`](https://sh4zam.com/api/matrix/shz_mat4x4_inverse/)

### inverse_block_triangular

```cpp
void inverse_block_triangular(mat4x4 *out) const noexcept
```

Calls: [`shz_mat4x4_inverse_block_triangular()`](https://sh4zam.com/api/matrix/shz_mat4x4_inverse_block_triangular/)

### decompose

```cpp
void decompose(vec3 *translation, quat *rotation, vec3 *scale) const noexcept
```

Calls: [`shz_mat4x4_decompose()`](https://sh4zam.com/api/matrix/shz_mat4x4_decompose/)

### blend

```cpp
void blend(const shz_mat4x4_t &matrix, float weight) noexcept
```

Adds and accumulates a scaled 4x4 matrix into the given matrix.

Calls: [`shz_mat4x4_blend()`](https://sh4zam.com/api/matrix/shz_mat4x4_blend/)

### swap

```cpp
void swap(shz_mat4x4_t &matA, shz_mat4x4_t &matB) noexcept
```

### mat4x4

```cpp
mat4x4() noexcept=default
mat4x4(const mat4x4 &other) noexcept
mat4x4(const shz_mat4x4_t &other) noexcept
```

Calls: [`shz_mat4x4_copy()`](https://sh4zam.com/api/matrix/shz_mat4x4_copy/)

### operator=

```cpp
mat4x4 & operator=(const shz_mat4x4_t &other) noexcept
```

Calls: [`shz_mat4x4_copy()`](https://sh4zam.com/api/matrix/shz_mat4x4_copy/)

### operator==

```cpp
bool operator==(const mat4x4 &lhs, const mat4x4 &rhs) noexcept
```

Overloaded equality operator, for comparing vectors.


---
# shz::quat

Source: https://sh4zam.com/api/cpp/quat/

C++ structure representing a quaternion.

A quaternion represents a rotation about an arbitrary axis in 3D space.

- **Header:** `#include <sh4zam/shz_quat.hpp>` ([source](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.hpp#L38))
- **C type:** [`shz_quat_t`](https://sh4zam.com/api/quat/shz_quat_t/) (layout-compatible; the C API accepts it directly)
- **Bases:** `shz_quat_t`

## Static functions

### identity

```cpp
static quat identity() noexcept
```

Returns an identity quaternion.

Calls: [`shz_quat_identity()`](https://sh4zam.com/api/quat/shz_quat_identity/)

### from_angles_xyz

```cpp
static quat from_angles_xyz(float x, float y, float z) noexcept
```

C++ convenience wrapper for `shz_quat_from_angles_xyz()`.

Calls: [`shz_quat_from_angles_xyz()`](https://sh4zam.com/api/quat/shz_quat_from_angles_xyz/)

### from_rotation_xyz

```cpp
static quat from_rotation_xyz(float x, float y, float z) noexcept
```

C++ convenience wrapper for `shz_quat_from_rotation_xyz()`.

Calls: [`shz_quat_from_rotation_xyz()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz/)

### from_rotation_zyx

```cpp
static quat from_rotation_zyx(float z, float y, float x) noexcept
```

C++ convenience wrapper for `shz_quat_from_rotation_zyx()`.

Calls: [`shz_quat_from_rotation_zyx()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx/)

### from_rotation_zxy

```cpp
static quat from_rotation_zxy(float z, float x, float y) noexcept
```

C++ convenience wrapper for `shz_quat_from_rotation_zxy()`.

Calls: [`shz_quat_from_rotation_zxy()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy/)

### from_rotation_yxz

```cpp
static quat from_rotation_yxz(float y, float x, float z) noexcept
```

C++ convenience wrapper for `shz_quat_from_rotation_yxz()`.

Calls: [`shz_quat_from_rotation_yxz()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz/)

### from_rotation_xyz_u16

```cpp
static quat from_rotation_xyz_u16(uint16_t x, uint16_t y, uint16_t z) noexcept
```

C++ convenience wrapper for `shz_quat_from_rotation_xyz_u16()`.

Calls: [`shz_quat_from_rotation_xyz_u16()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz_u16/)

### from_rotation_zyx_u16

```cpp
static quat from_rotation_zyx_u16(uint16_t z, uint16_t y, uint16_t x) noexcept
```

C++ convenience wrapper for `shz_quat_from_rotation_zyx_u16()`.

Calls: [`shz_quat_from_rotation_zyx_u16()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx_u16/)

### from_rotation_zxy_u16

```cpp
static quat from_rotation_zxy_u16(uint16_t z, uint16_t x, uint16_t y) noexcept
```

C++ convenience wrapper for `shz_quat_from_rotation_zxy_u16()`.

Calls: [`shz_quat_from_rotation_zxy_u16()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy_u16/)

### from_rotation_yxz_u16

```cpp
static quat from_rotation_yxz_u16(uint16_t y, uint16_t x, uint16_t z) noexcept
```

C++ convenience wrapper for `shz_quat_from_rotation_yxz_u16()`.

Calls: [`shz_quat_from_rotation_yxz_u16()`](https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz_u16/)

### from_axis_angle

```cpp
static quat from_axis_angle(const vec3 &axis, float angle) noexcept
```

Initializes a quaternion which is a rotation in `angle` radians about the given `axis`.

Calls: [`shz_quat_from_axis_angle()`](https://sh4zam.com/api/quat/shz_quat_from_axis_angle/)

### from_look_axis

```cpp
static quat from_look_axis(const vec3 &forward, const vec3 &up) noexcept
```

Creates a quaternion looking in the given direction with the given reference direction.

Calls: [`shz_quat_from_look_axis()`](https://sh4zam.com/api/quat/shz_quat_from_look_axis/)

### from_rotated_axis

```cpp
static quat from_rotated_axis(const vec3 &start, const vec3 &end) noexcept
```

Returns the quaternion representing the rotation from the `start` to the `end` axes.

Calls: [`shz_quat_from_rotated_axis()`](https://sh4zam.com/api/quat/shz_quat_from_rotated_axis/)

### lerp

```cpp
static quat lerp(const quat &q, const quat &p, float t) noexcept
```

Returns the quaternion that is linearly interpolating `q` to `p`, by a t factor of `0.0f-1.0f`.

Calls: [`shz_quat_lerp()`](https://sh4zam.com/api/quat/shz_quat_lerp/)

### nlerp

```cpp
static quat nlerp(const quat &q, const quat &p, float t) noexcept
```

Equivalent to `lerp()`, except that the resulting quaternion is normalized.

Calls: [`shz_quat_nlerp()`](https://sh4zam.com/api/quat/shz_quat_nlerp/)

### slerp

```cpp
static quat slerp(const quat &q, const quat &p, float t) noexcept
```

Returns the quaternion that is spherically linearly interpolating `q` to `p`, by a `t` factor of `0.0f-1.0f`.

Calls: [`shz_quat_slerp()`](https://sh4zam.com/api/quat/shz_quat_slerp/)

### squad

```cpp
static quat squad(const quat &q1, const quat &q2, const quat &s1, const quat &s2, float t) noexcept
```

Evaluates the smooth cubic spherical interpolation (SQUAD) at parameter `t`.

Calls: [`shz_quat_squad()`](https://sh4zam.com/api/quat/shz_quat_squad/)

## Members

### quat

```cpp
quat() noexcept=default
quat(const quat &other) noexcept=default
quat(float w, float x, float y, float z) noexcept
quat(const shz_quat_t &q) noexcept
quat(const volatile shz_quat_t &other) noexcept
```

Default constructor: does nothing.

### angle

```cpp
float angle() const noexcept
```

Returns the angle of rotation represented by the given quaternion.

Calls: [`shz_quat_angle()`](https://sh4zam.com/api/quat/shz_quat_angle/)

### axis

```cpp
vec3 axis() const noexcept
```

Returns the axis of rotation represented by the given quaternion.

Calls: [`shz_quat_axis()`](https://sh4zam.com/api/quat/shz_quat_axis/)

### angle_x

```cpp
float angle_x() const noexcept
```

Returns the angle of rotation about the X axis represented by the given quaternion.

Calls: [`shz_quat_angle_x()`](https://sh4zam.com/api/quat/shz_quat_angle_x/)

### angle_y

```cpp
float angle_y() const noexcept
```

Returns the angle of rotation about the Y axis represented by the given quaternion.

Calls: [`shz_quat_angle_y()`](https://sh4zam.com/api/quat/shz_quat_angle_y/)

### angle_z

```cpp
float angle_z() const noexcept
```

Returns the angle of rotation about the Z axis represented by the given quaternion.

Calls: [`shz_quat_angle_z()`](https://sh4zam.com/api/quat/shz_quat_angle_z/)

### magnitude_sqr

```cpp
float magnitude_sqr() const noexcept
```

Returns the magnitude of the quaternion squared.

Calls: [`shz_quat_magnitude_sqr()`](https://sh4zam.com/api/quat/shz_quat_magnitude_sqr/)

### magnitude

```cpp
float magnitude() const noexcept
```

Returns the magnitude of the quaternion.

Calls: [`shz_quat_magnitude()`](https://sh4zam.com/api/quat/shz_quat_magnitude/)

### magnitude_inv

```cpp
float magnitude_inv() const noexcept
```

Returns the inverse of the magnitude of the quaternion.

Calls: [`shz_quat_magnitude_inv()`](https://sh4zam.com/api/quat/shz_quat_magnitude_inv/)

### to_angles_xyz

```cpp
vec3 to_angles_xyz() const noexcept
```

Returns the tait-bryan rotation angles about the X, Y, then Z axes which are represented by the given quaternion.

Calls: [`shz_quat_to_angles_xyz()`](https://sh4zam.com/api/quat/shz_quat_to_angles_xyz/)

### to_axis_angle

```cpp
void to_axis_angle(shz_vec3_t *axis, float *angle) const noexcept
std::pair< vec3, float > to_axis_angle() const noexcept
```

Returns both the axis and angle of rotation through the pointer arguments.

Calls: [`shz_quat_to_axis_angle()`](https://sh4zam.com/api/quat/shz_quat_to_axis_angle/)

### normalized

```cpp
quat normalized() const noexcept
```

Returns the given quaternion as a unit quaternion.

Calls: [`shz_quat_normalize()`](https://sh4zam.com/api/quat/shz_quat_normalize/)

### normalize

```cpp
void normalize() noexcept
```

Normalizes the given quaternion.

### normalized_safe

```cpp
quat normalized_safe() const noexcept
```

Returns a safely normalized quaternion from the given quaternion, protecting against division-by-zero.

Calls: [`shz_quat_normalize_safe()`](https://sh4zam.com/api/quat/shz_quat_normalize_safe/)

### normalize_safe

```cpp
void normalize_safe() noexcept
```

Safely normalizes the given quaternion by protecting against division-by-zero.

### conjugated

```cpp
quat conjugated() const noexcept
```

Returns a quaternion that is the conjugate of the given quaternion.

Calls: [`shz_quat_conjugate()`](https://sh4zam.com/api/quat/shz_quat_conjugate/)

### conjugate

```cpp
void conjugate() noexcept
```

Conjugates the given quaternion.

### inverse

```cpp
quat inverse() const noexcept
```

Returns the inverse of the given quaternion.

Calls: [`shz_quat_inv()`](https://sh4zam.com/api/quat/shz_quat_inv/)

### invert

```cpp
void invert() noexcept
```

Inverts the given quaternion.

### negated

```cpp
quat negated() const noexcept
```

Returns a new quaternion whose components are the negated values of the given quaternion.

Calls: [`shz_quat_neg()`](https://sh4zam.com/api/quat/shz_quat_neg/)

### negate

```cpp
void negate() noexcept
```

Negates the components of the given quaternion.

### add

```cpp
quat add(const quat &rhs) const noexcept
```

Returns a new quaternion from adding the given quaterion to `rhs`.

Calls: [`shz_quat_add()`](https://sh4zam.com/api/quat/shz_quat_add/)

### sub

```cpp
quat sub(const quat &rhs) const noexcept
```

Returns a new quaternion from adding `rhs` from the given quaternion.

Calls: [`shz_quat_sub()`](https://sh4zam.com/api/quat/shz_quat_sub/)

### scaled

```cpp
quat scaled(float s) const noexcept
```

Returns a new quaternion from scaling the given quaterion by `s`.

Calls: [`shz_quat_scale()`](https://sh4zam.com/api/quat/shz_quat_scale/)

### scale

```cpp
void scale(float s) noexcept
```

Multiplies each component of the given quaternion by `s`.

### dot

```cpp
float dot(const quat &other) const noexcept
vec2 dot(const quat &q1, const quat &q2) const noexcept
vec3 dot(const quat &q1, const quat &q2, const quat &q3) const noexcept
```

Returns the dot product between the given quaternion and another.

Calls: [`shz_quat_dot()`](https://sh4zam.com/api/quat/shz_quat_dot/), [`shz_quat_dot2()`](https://sh4zam.com/api/quat/shz_quat_dot2/), [`shz_quat_dot3()`](https://sh4zam.com/api/quat/shz_quat_dot3/)

### mult

```cpp
quat mult(const quat &rhs) const noexcept
```

Returns a new quaterion from multiplying the given quaternion by another.

Calls: [`shz_quat_mult()`](https://sh4zam.com/api/quat/shz_quat_mult/)

### div

```cpp
quat div(const quat &rhs) const noexcept
```

Returns a new quaterion from dividing the given quaternion by another (or multiplying the given quaternion by the inverse of another).

Calls: [`shz_quat_div()`](https://sh4zam.com/api/quat/shz_quat_div/)

### angle_between

```cpp
float angle_between(const quat &p) const noexcept
```

Returns the angle in radians between the rotations represented by quaternions `q` and `p`.

Calls: [`shz_quat_angle_between()`](https://sh4zam.com/api/quat/shz_quat_angle_between/)

### rotate_towards

```cpp
quat rotate_towards(const quat &to, float max_angle) const noexcept
```

Rotates quaternion `from` towards quaternion `to` by at most `max_angle` radians.

Calls: [`shz_quat_rotate_towards()`](https://sh4zam.com/api/quat/shz_quat_rotate_towards/)

### transform

```cpp
vec3 transform(const vec3 &in) const noexcept
```

Returns a new `shz::vec3` from transforming `in` by the given quaternion.

Calls: [`shz_quat_transform_vec3()`](https://sh4zam.com/api/quat/shz_quat_transform_vec3/)

### operator-

```cpp
quat operator-() const noexcept
```

Overloaded unary negation operator, returns the negation of the given quaternion.

### operator+=

```cpp
quat operator+=(const quat &rhs) noexcept
```

Adds and accumulates `rhs` onto the given quaternion.

### operator-=

```cpp
quat operator-=(const quat &rhs) noexcept
```

Subtracts `rhs` from the given quaternion.

### operator*=

```cpp
quat operator*=(const quat &rhs) noexcept
quat operator*=(float rhs) noexcept
```

Multiplies and accumulates `rhs` into the given quaternion.

### operator/=

```cpp
quat operator/=(const quat &rhs) noexcept
quat operator/=(float rhs) noexcept
```

Divides the given quaternion by `rhs`.

Calls: [`shz_invf()`](https://sh4zam.com/api/scalar/shz_invf/)

### operator==

```cpp
bool operator==(const quat &lhs, const quat &rhs) noexcept
```

Overloaded comparison operator, checks for quaternion equality.


---
# shz::sincos

Source: https://sh4zam.com/api/cpp/sincos/

C++ sine/cosine approximation pairs.

This structure contains the precomputed values for both sine and cosine of an angle.

- **Header:** `#include <sh4zam/shz_trig.hpp>` ([source](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.hpp#L44))
- **C type:** [`shz_sincos_t`](https://sh4zam.com/api/trig/shz_sincos_t/) (layout-compatible; the C API accepts it directly)
- **Bases:** `shz_sincos_t`

## Static functions

### from_radians

```cpp
static sincos from_radians(float rad) noexcept
static sincos from_radians(uint16_t rad) noexcept
```

Returns a new sin/cos pair from the given angle in radians.

Calls: [`shz_sincosf()`](https://sh4zam.com/api/trig/shz_sincosf/), [`shz_sincosu16()`](https://sh4zam.com/api/trig/shz_sincosu16/)

### from_degrees

```cpp
static sincos from_degrees(float deg) noexcept
```

Returns a new sin/cos pair from the given angle in degrees.

Calls: [`shz_sincosf_deg()`](https://sh4zam.com/api/trig/shz_sincosf_deg/)

## Members

### sincos

```cpp
sincos(const shz_sincos_t &val) noexcept
```

Converting constructor from C struct.

### sinf

```cpp
float sinf() const noexcept
```

Returns the sine component from the pair.

### cosf

```cpp
float cosf() const noexcept
```

Returns the cosine component from the pair.

### tanf

```cpp
float tanf() const noexcept
```

Calculates the tangent from the given pair.

Calls: [`shz_sincos_tanf()`](https://sh4zam.com/api/trig/shz_sincos_tanf/)

### secf

```cpp
float secf() const noexcept
```

Calculates the secant from the given pair.

Calls: [`shz_sincos_secf()`](https://sh4zam.com/api/trig/shz_sincos_secf/)

### cscf

```cpp
float cscf() const noexcept
```

Calculates the cosecant from the given pair.

Calls: [`shz_sincos_cscf()`](https://sh4zam.com/api/trig/shz_sincos_cscf/)

### cotf

```cpp
float cotf() const noexcept
```

Calculates the cotangent from the given pair.

Calls: [`shz_sincos_cotf()`](https://sh4zam.com/api/trig/shz_sincos_cotf/)

### operator std::pair< float, float >

```cpp
operator std::pair< float, float >() const noexcept
```

### cos

```cpp
float shz_sincos_t::cos
```

cosf() approximation for the angle

Inherited from `shz::vecN`.

### sin

```cpp
float shz_sincos_t::sin
```

sinf() approximation for the angle

Inherited from `shz::vecN`.


---
# shz::vec2

Source: https://sh4zam.com/api/cpp/vec2/

2D Vector type

C++ structure for representing a 2-dimensional vector.

- **Header:** `#include <sh4zam/shz_vector.hpp>` ([source](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.hpp#L420))
- **C type:** [`shz_vec2_t`](https://sh4zam.com/api/vector/shz_vec2_t/) (layout-compatible; the C API accepts it directly)
- **Bases:** `shz::vecN< vec2, shz_vec2_t, 2 >`

## Static functions

### from_angle

```cpp
static vec2 from_angle(float rads) noexcept
```

Constructs a `vec2` from the given angle of rotation from the +X axis, in radians.

Calls: [`shz_vec2_from_angle()`](https://sh4zam.com/api/vector/shz_vec2_from_angle/)

### from_angle_deg

```cpp
static vec2 from_angle_deg(float deg) noexcept
```

Constructs a `vec2` from the given angle of rotation from the +X axis, in degrees.

Calls: [`shz_vec2_from_angle_deg()`](https://sh4zam.com/api/vector/shz_vec2_from_angle_deg/)

### from

```cpp
static CppType shz::vecN< CRTP, C, R >::from(const auto &raw) noexcept
```

Conversion operator for going from a layout-compatible vector type to a SH4ZAM vector type.

Inherited from `shz::vecN`.

### lerp

```cpp
static CppType shz::vecN< CRTP, C, R >::lerp(const CppType &start, const CppType &end, float t) noexcept
```

Returns the vector that is linearly interpolated between the two given vectors by the `0.0f-1.0f` factor, `t`.

Calls: [`shz_vec2_lerp()`](https://sh4zam.com/api/vector/shz_vec2_lerp/) (inherited from `shz::vecN`)

### smoothstep

```cpp
static CppType shz::vecN< CRTP, C, R >::smoothstep(const CppType &vec, T &&edge0, T &&edge1) noexcept
```

Returns a vector where each component is smoothly interpolated from 0 to 1 between edge0 and edge1.

Calls: [`shz_vec2_smoothstep()`](https://sh4zam.com/api/vector/shz_vec2_smoothstep/) (inherited from `shz::vecN`)

### smoothstep_safe

```cpp
static CppType shz::vecN< CRTP, C, R >::smoothstep_safe(const CppType &vec, T &&edge0, T &&edge1) noexcept
```

Returns a vector where each component is smoothly interpolated from 0 to 1 between edge0 and edge1.

Calls: [`shz_vec2_smoothstep_safe()`](https://sh4zam.com/api/vector/shz_vec2_smoothstep_safe/) (inherited from `shz::vecN`)

### step

```cpp
static CppType shz::vecN< CRTP, C, R >::step(const CppType &vec, T &&edge) noexcept
```

Compares each component of the vector to the edge. 0 returned in that component if x\[i\] \< edge. Otherwise the component is 1.

Calls: [`shz_vec2_step()`](https://sh4zam.com/api/vector/shz_vec2_step/) (inherited from `shz::vecN`)

## Members

### vec2

```cpp
vec2()=default
vec2(float v) noexcept
vec2(float x, float y) noexcept
vec2(const sincos &pair) noexcept
```

Default constructor: does nothing.

### cross

```cpp
float cross(const vec2 &other) const noexcept
```

C++ wrapper for `shz_vec2_cross()`.

Calls: [`shz_vec2_cross()`](https://sh4zam.com/api/vector/shz_vec2_cross/)

### rotate

```cpp
vec2 rotate(float radians) const noexcept
```

C++ wrapper for `shz_vec2_rotate()`.

Calls: [`shz_vec2_rotate()`](https://sh4zam.com/api/vector/shz_vec2_rotate/)

### vecN

```cpp
shz::vecN< CRTP, C, R >::vecN() noexcept=default
shz::vecN< CRTP, C, R >::vecN(const vecN &other) noexcept=default
shz::vecN< CRTP, C, R >::vecN(const CType &other) noexcept
shz::vecN< CRTP, C, R >::vecN(const volatile CType &other) noexcept
```

Default constructor, does nothing.

### dot

```cpp
float shz::vecN< CRTP, C, R >::dot(const CppType &other) const noexcept
vec2 shz::vecN< CRTP, C, R >::dot(const CppType &v1, const CppType &v2) const noexcept
vec3 shz::vecN< CRTP, C, R >::dot(const CppType &v1, const CppType &v2, const CppType &v3) const noexcept
```

Returns the dot product of the given vector and another.

### abs

```cpp
CppType shz::vecN< CRTP, C, R >::abs() const noexcept
```

Returns a new vector whose components are the absolute value of the given vector.

Calls: [`shz_vec2_abs()`](https://sh4zam.com/api/vector/shz_vec2_abs/) (inherited from `shz::vecN`)

### angle_between

```cpp
float shz::vecN< CRTP, C, R >::angle_between(const CppType &other) const noexcept
```

Returns the angle between the given vector and another, in radians.

Calls: [`shz_vec2_angle_between()`](https://sh4zam.com/api/vector/shz_vec2_angle_between/) (inherited from `shz::vecN`)

### angles

```cpp
auto shz::vecN< CRTP, C, R >::angles() const noexcept
```

Returns the angle(s) created between the given vector axis and the +X axis, in radians.

Calls: [`shz_vec2_angle()`](https://sh4zam.com/api/vector/shz_vec2_angle/) (inherited from `shz::vecN`)

### ceil

```cpp
CppType shz::vecN< CRTP, C, R >::ceil() const noexcept
```

Returns a new vector with the component-wise ceil of the given vector.

Calls: [`shz_vec2_ceil()`](https://sh4zam.com/api/vector/shz_vec2_ceil/) (inherited from `shz::vecN`)

### clamp

```cpp
CppType shz::vecN< CRTP, C, R >::clamp(float min, float max) const noexcept
```

Returns a new vector whose values are the clamped components of the given vector.

Calls: [`shz_vec2_clamp()`](https://sh4zam.com/api/vector/shz_vec2_clamp/) (inherited from `shz::vecN`)

### deref

```cpp
CppType & shz::vecN< CRTP, C, R >::deref(const auto *raw) noexcept
```

Conversion operator for accessing an existing pointer type as though it were a refrence to a SH4ZAM type.

Inherited from `shz::vecN`.

### direction

```cpp
CppType shz::vecN< CRTP, C, R >::direction() const noexcept
```

Returns the direction vector resulting from normalizing the given vector.

Calls: [`shz_vec2_normalize()`](https://sh4zam.com/api/vector/shz_vec2_normalize/) (inherited from `shz::vecN`)

### direction_safe

```cpp
CppType shz::vecN< CRTP, C, R >::direction_safe() const noexcept
```

Returns the direction vector of a given vector, safely protecting against division-by-zero.

Calls: [`shz_vec2_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec2_normalize_safe/) (inherited from `shz::vecN`)

### distance

```cpp
float shz::vecN< CRTP, C, R >::distance(const CppType &other) const noexcept
```

Returns the magnitude of the difference between two vectors as their distance.

Calls: [`shz_vec2_distance()`](https://sh4zam.com/api/vector/shz_vec2_distance/) (inherited from `shz::vecN`)

### distance_sqr

```cpp
float shz::vecN< CRTP, C, R >::distance_sqr(const CppType &other) const noexcept
```

Returns the value of the distance between two vectors squared (faster than actual distance).

Calls: [`shz_vec2_distance_sqr()`](https://sh4zam.com/api/vector/shz_vec2_distance_sqr/) (inherited from `shz::vecN`)

### floor

```cpp
CppType shz::vecN< CRTP, C, R >::floor() const noexcept
```

Returns a new vector with the component-wise floor of the given vector.

Calls: [`shz_vec2_floor()`](https://sh4zam.com/api/vector/shz_vec2_floor/) (inherited from `shz::vecN`)

### fract

```cpp
CppType shz::vecN< CRTP, C, R >::fract() const noexcept
```

Returns a new vector with the fractional part of each component.

Calls: [`shz_vec2_fract()`](https://sh4zam.com/api/vector/shz_vec2_fract/) (inherited from `shz::vecN`)

### inv

```cpp
CppType shz::vecN< CRTP, C, R >::inv() const noexcept
```

Returns a new vector whose components are the reciprocal values of the given vector.

Calls: [`shz_vec2_inv()`](https://sh4zam.com/api/vector/shz_vec2_inv/) (inherited from `shz::vecN`)

### inv_sqrtf

```cpp
CppType shz::vecN< CRTP, C, R >::inv_sqrtf() const noexcept
```

Returns a new vector whose components are the inverse square root of the given vector.

Calls: [`shz_vec2_inv_sqrtf()`](https://sh4zam.com/api/vector/shz_vec2_inv_sqrtf/) (inherited from `shz::vecN`)

### magnitude

```cpp
float shz::vecN< CRTP, C, R >::magnitude() const noexcept
```

Returns the magnitude of the given vector.

Calls: [`shz_vec2_magnitude()`](https://sh4zam.com/api/vector/shz_vec2_magnitude/) (inherited from `shz::vecN`)

### magnitude_inv

```cpp
float shz::vecN< CRTP, C, R >::magnitude_inv() const noexcept
```

Returns the inverse magnitude of the given vector.

Calls: [`shz_vec2_magnitude_inv()`](https://sh4zam.com/api/vector/shz_vec2_magnitude_inv/) (inherited from `shz::vecN`)

### magnitude_sqr

```cpp
float shz::vecN< CRTP, C, R >::magnitude_sqr() const noexcept
```

Returns the squared magnitude of the given vector.

Calls: [`shz_vec2_magnitude_sqr()`](https://sh4zam.com/api/vector/shz_vec2_magnitude_sqr/) (inherited from `shz::vecN`)

### max

```cpp
float shz::vecN< CRTP, C, R >::max() const noexcept
```

Returns the maximum value of every element within the vector.

Calls: [`shz_vec2_max()`](https://sh4zam.com/api/vector/shz_vec2_max/) (inherited from `shz::vecN`)

### maxv

```cpp
CppType shz::vecN< CRTP, C, R >::maxv(const CppType &other) const noexcept
```

Returns a new vector with the component-wise maximum of two vectors.

Calls: [`shz_vec2_maxv()`](https://sh4zam.com/api/vector/shz_vec2_maxv/) (inherited from `shz::vecN`)

### min

```cpp
float shz::vecN< CRTP, C, R >::min() const noexcept
```

Returns the minimum value of every element within the vector.

Calls: [`shz_vec2_min()`](https://sh4zam.com/api/vector/shz_vec2_min/) (inherited from `shz::vecN`)

### minv

```cpp
CppType shz::vecN< CRTP, C, R >::minv(const CppType &other) const noexcept
```

Returns a new vector with the component-wise minimum of two vectors.

Calls: [`shz_vec2_minv()`](https://sh4zam.com/api/vector/shz_vec2_minv/) (inherited from `shz::vecN`)

### move

```cpp
CppType shz::vecN< CRTP, C, R >::move(const CppType &target, float maxdist) const noexcept
```

Moves the given vector towards the target by the given `maxdist`.

Calls: [`shz_vec2_move()`](https://sh4zam.com/api/vector/shz_vec2_move/) (inherited from `shz::vecN`)

### neg

```cpp
CppType shz::vecN< CRTP, C, R >::neg() const noexcept
```

Returns a new vector whose components are the negative values of the given vector.

Calls: [`shz_vec2_neg()`](https://sh4zam.com/api/vector/shz_vec2_neg/) (inherited from `shz::vecN`)

### normalize

```cpp
void shz::vecN< CRTP, C, R >::normalize() noexcept
```

Normalizes the given vector.

Calls: [`shz_vec2_normalize()`](https://sh4zam.com/api/vector/shz_vec2_normalize/) (inherited from `shz::vecN`)

### normalize_safe

```cpp
void shz::vecN< CRTP, C, R >::normalize_safe() noexcept
```

Normalizes the given vector, safely protecting against division-by-zero.

Calls: [`shz_vec2_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec2_normalize_safe/) (inherited from `shz::vecN`)

### normalized

```cpp
CppType shz::vecN< CRTP, C, R >::normalized() const noexcept
```

Return the normalized vector.

Calls: [`shz_vec2_normalize()`](https://sh4zam.com/api/vector/shz_vec2_normalize/) (inherited from `shz::vecN`)

### normalized_safe

```cpp
CppType shz::vecN< CRTP, C, R >::normalized_safe() const noexcept
```

Return the normalized vector, safely protecting against division-by-zero.

Calls: [`shz_vec2_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec2_normalize_safe/) (inherited from `shz::vecN`)

### operator*=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator*=(const CppType &other) noexcept
```

Overloaded multiplication assignment operator, multiplies and accumulates a vector onto the left-hand vector.

Inherited from `shz::vecN`.

### operator+=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator+=(const CppType &other) noexcept
```

Overloaded operator for adding and accumulating a vector onto another.

Inherited from `shz::vecN`.

### operator-=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator-=(const CppType &other) noexcept
```

Overloaded subtraction assignment operator, subtracts a vector from the left-hand vector.

Inherited from `shz::vecN`.

### operator/=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator/=(const CppType &other) noexcept
```

Overloaded division assignment operator, divides the left vector by the right, assigning the left to the result.

Inherited from `shz::vecN`.

### project

```cpp
CppType shz::vecN< CRTP, C, R >::project(const CppType &onto) const noexcept
```

Returns the vector created from projecting the given vector onto another.

Calls: [`shz_vec2_project()`](https://sh4zam.com/api/vector/shz_vec2_project/) (inherited from `shz::vecN`)

### project_safe

```cpp
CppType shz::vecN< CRTP, C, R >::project_safe(const CppType &onto) const noexcept
```

Returns the vector created from projecting the given vector onto another, safely protecting against division-by-zero.

Calls: [`shz_vec2_project_safe()`](https://sh4zam.com/api/vector/shz_vec2_project_safe/) (inherited from `shz::vecN`)

### reflect

```cpp
CppType shz::vecN< CRTP, C, R >::reflect(const CppType &normal) const noexcept
```

Returns the vector created from reflecting the given vector over the normal of a surface.

Calls: [`shz_vec2_reflect()`](https://sh4zam.com/api/vector/shz_vec2_reflect/) (inherited from `shz::vecN`)

### refract

```cpp
CppType shz::vecN< CRTP, C, R >::refract(const CppType &normal, float eta) const noexcept
```

Returns the vector create from refracting the given incidence vector over the normal of a surface, using the given refraction ratio index.

Calls: [`shz_vec2_refract()`](https://sh4zam.com/api/vector/shz_vec2_refract/) (inherited from `shz::vecN`)

### round

```cpp
CppType shz::vecN< CRTP, C, R >::round() const noexcept
```

Returns a new vector with the component-wise rounding of the given vector.

Calls: [`shz_vec2_round()`](https://sh4zam.com/api/vector/shz_vec2_round/) (inherited from `shz::vecN`)

### saturate

```cpp
CppType shz::vecN< CRTP, C, R >::saturate() const noexcept
```

Returns a new vector with each component clamped to \[0, 1\].

Calls: [`shz_vec2_saturate()`](https://sh4zam.com/api/vector/shz_vec2_saturate/) (inherited from `shz::vecN`)

### sign

```cpp
CppType shz::vecN< CRTP, C, R >::sign() const noexcept
```

Returns a new vector with the sign of each component (-1, 0, or 1).

Calls: [`shz_vec2_sign()`](https://sh4zam.com/api/vector/shz_vec2_sign/) (inherited from `shz::vecN`)

### sqrtf

```cpp
CppType shz::vecN< CRTP, C, R >::sqrtf() const noexcept
```

Returns a new vector whose components are the square root of the given vector.

Calls: [`shz_vec2_sqrtf()`](https://sh4zam.com/api/vector/shz_vec2_sqrtf/) (inherited from `shz::vecN`)

### swizzle

```cpp
CppType shz::vecN< CRTP, C, R >::swizzle() const noexcept
```

Swizzle oeprator which takes a compile-time list of indices as non-type template arguments for the index each element should use as its new value.

Calls: [`shz_vec2_swizzle()`](https://sh4zam.com/api/vector/shz_vec2_swizzle/) (inherited from `shz::vecN`)

### to

```cpp
T shz::vecN< CRTP, C, R >::to() const noexcept
```

Conversion operator for going from a SH4ZAM vector type to another layout-compatible type.

Inherited from `shz::vecN`.


---
# shz::vec3

Source: https://sh4zam.com/api/cpp/vec3/

3D Vector type

C++ structure for representing a 3-dimensional vector.

- **Header:** `#include <sh4zam/shz_vector.hpp>` ([source](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.hpp#L475))
- **C type:** [`shz_vec3_t`](https://sh4zam.com/api/vector/shz_vec3_t/) (layout-compatible; the C API accepts it directly)
- **Bases:** `shz::vecN< vec3, shz_vec3_t, 3 >`

## Static functions

### orthonormalize

```cpp
static auto orthonormalize(const vec3 &in1, const vec3 &in2) noexcept
static void orthonormalize(const vec3 &in1, const vec3 &in2, vec3 *out1, vec3 *out2) noexcept
```

Returns 2 3D vectors which are normalized and orthogonal to the two input vectors as a std::pair\<>.

Calls: [`shz_vec3_orthonormalize()`](https://sh4zam.com/api/vector/shz_vec3_orthonormalize/)

### cubic_hermite

```cpp
static vec3 cubic_hermite(const vec3 &v1, const vec3 &tangent1, const vec3 &v2, const vec3 &tangent2, float amount) noexcept
```

Calculates the cubic hermite interpolation between two vectors and their tangents.

Calls: [`shz_vec3_cubic_hermite()`](https://sh4zam.com/api/vector/shz_vec3_cubic_hermite/)

### from_angles

```cpp
static vec3 from_angles(float azimuth_rads, float elevation_rads) noexcept
```

Returns a 3D vector which forms the given angles with the +X axis, in radians.

Calls: [`shz_vec3_from_angles()`](https://sh4zam.com/api/vector/shz_vec3_from_angles/)

### from_angles_deg

```cpp
static vec3 from_angles_deg(float azimuth_deg, float elevation_deg) noexcept
```

Returns a 3D vector which forms the given angles with the +X axis, in degrees.

Calls: [`shz_vec3_from_angles_deg()`](https://sh4zam.com/api/vector/shz_vec3_from_angles_deg/)

### from

```cpp
static CppType shz::vecN< CRTP, C, R >::from(const auto &raw) noexcept
```

Conversion operator for going from a layout-compatible vector type to a SH4ZAM vector type.

Inherited from `shz::vecN`.

### lerp

```cpp
static CppType shz::vecN< CRTP, C, R >::lerp(const CppType &start, const CppType &end, float t) noexcept
```

Returns the vector that is linearly interpolated between the two given vectors by the `0.0f-1.0f` factor, `t`.

Calls: [`shz_vec3_lerp()`](https://sh4zam.com/api/vector/shz_vec3_lerp/) (inherited from `shz::vecN`)

### smoothstep

```cpp
static CppType shz::vecN< CRTP, C, R >::smoothstep(const CppType &vec, T &&edge0, T &&edge1) noexcept
```

Returns a vector where each component is smoothly interpolated from 0 to 1 between edge0 and edge1.

Calls: [`shz_vec3_smoothstep()`](https://sh4zam.com/api/vector/shz_vec3_smoothstep/) (inherited from `shz::vecN`)

### smoothstep_safe

```cpp
static CppType shz::vecN< CRTP, C, R >::smoothstep_safe(const CppType &vec, T &&edge0, T &&edge1) noexcept
```

Returns a vector where each component is smoothly interpolated from 0 to 1 between edge0 and edge1.

Calls: [`shz_vec3_smoothstep_safe()`](https://sh4zam.com/api/vector/shz_vec3_smoothstep_safe/) (inherited from `shz::vecN`)

### step

```cpp
static CppType shz::vecN< CRTP, C, R >::step(const CppType &vec, T &&edge) noexcept
```

Compares each component of the vector to the edge. 0 returned in that component if x\[i\] \< edge. Otherwise the component is 1.

Calls: [`shz_vec3_step()`](https://sh4zam.com/api/vector/shz_vec3_step/) (inherited from `shz::vecN`)

## Members

### rotate_x

```cpp
vec3 rotate_x(float angle) const noexcept
```

Rotates a 3D vector about the X axis by the given number of radians.

Calls: [`shz_vec3_rotate_x()`](https://sh4zam.com/api/vector/shz_vec3_rotate_x/)

### rotate_y

```cpp
vec3 rotate_y(float angle) const noexcept
```

Rotates a 3D vector about the Y axis by the given number of radians.

Calls: [`shz_vec3_rotate_y()`](https://sh4zam.com/api/vector/shz_vec3_rotate_y/)

### rotate_z

```cpp
vec3 rotate_z(float angle) const noexcept
```

Rotates a 3D vector about the Z axis by the given number of radians.

Calls: [`shz_vec3_rotate_z()`](https://sh4zam.com/api/vector/shz_vec3_rotate_z/)

### vec3

```cpp
vec3()=default
vec3(const shz_vec3_t &other) noexcept
vec3(float v) noexcept
vec3(float x, float y, float z) noexcept
vec3(const shz::vec2 &xy, float z) noexcept
vec3(float x, const shz::vec2 &yz) noexcept
vec3(const sincos &azimuth, const sincos &elevation) noexcept
```

Default constructor: does nothing.

### xy

```cpp
vec2 xy() const noexcept
```

### cross

```cpp
vec3 cross(const vec3 &other) const noexcept
```

Returns a 3D vector which forms the given angles with the +X axis.

Calls: [`shz_vec3_cross()`](https://sh4zam.com/api/vector/shz_vec3_cross/)

### triple

```cpp
float triple(const vec3 &b, const vec3 &c) const noexcept
```

Returns the 3D vector "triple product" between the given vector and vectors `a` and `b`.

Calls: [`shz_vec3_triple()`](https://sh4zam.com/api/vector/shz_vec3_triple/)

### perp

```cpp
vec3 perp() const noexcept
```

Returns a 3D vector which is perpendicular to this vector.

Calls: [`shz_vec3_perp()`](https://sh4zam.com/api/vector/shz_vec3_perp/)

### reject

```cpp
vec3 reject(const vec3 &onto) const noexcept
```

Returns the 3D reject vector of the given vector and another.

Calls: [`shz_vec3_reject()`](https://sh4zam.com/api/vector/shz_vec3_reject/)

### barycenter

```cpp
vec3 barycenter(const vec3 &a, const vec3 &b, const vec3 &c) const noexcept
```

Computes the barycentric coordinates `<u, v, w>` for the given 3D vector, within the plane of the triangle formed by the given vertices, `a`, `b`, and `c`.

Calls: [`shz_vec3_barycenter()`](https://sh4zam.com/api/vector/shz_vec3_barycenter/)

### vecN

```cpp
shz::vecN< CRTP, C, R >::vecN() noexcept=default
shz::vecN< CRTP, C, R >::vecN(const vecN &other) noexcept=default
shz::vecN< CRTP, C, R >::vecN(const CType &other) noexcept
shz::vecN< CRTP, C, R >::vecN(const volatile CType &other) noexcept
```

Default constructor, does nothing.

### dot

```cpp
float shz::vecN< CRTP, C, R >::dot(const CppType &other) const noexcept
vec2 shz::vecN< CRTP, C, R >::dot(const CppType &v1, const CppType &v2) const noexcept
vec3 shz::vecN< CRTP, C, R >::dot(const CppType &v1, const CppType &v2, const CppType &v3) const noexcept
```

Returns the dot product of the given vector and another.

### abs

```cpp
CppType shz::vecN< CRTP, C, R >::abs() const noexcept
```

Returns a new vector whose components are the absolute value of the given vector.

Calls: [`shz_vec3_abs()`](https://sh4zam.com/api/vector/shz_vec3_abs/) (inherited from `shz::vecN`)

### angle_between

```cpp
float shz::vecN< CRTP, C, R >::angle_between(const CppType &other) const noexcept
```

Returns the angle between the given vector and another, in radians.

Calls: [`shz_vec3_angle_between()`](https://sh4zam.com/api/vector/shz_vec3_angle_between/) (inherited from `shz::vecN`)

### angles

```cpp
auto shz::vecN< CRTP, C, R >::angles() const noexcept
```

Returns the angle(s) created between the given vector axis and the +X axis, in radians.

Calls: [`shz_vec3_angles()`](https://sh4zam.com/api/vector/shz_vec3_angles/) (inherited from `shz::vecN`)

### ceil

```cpp
CppType shz::vecN< CRTP, C, R >::ceil() const noexcept
```

Returns a new vector with the component-wise ceil of the given vector.

Calls: [`shz_vec3_ceil()`](https://sh4zam.com/api/vector/shz_vec3_ceil/) (inherited from `shz::vecN`)

### clamp

```cpp
CppType shz::vecN< CRTP, C, R >::clamp(float min, float max) const noexcept
```

Returns a new vector whose values are the clamped components of the given vector.

Calls: [`shz_vec3_clamp()`](https://sh4zam.com/api/vector/shz_vec3_clamp/) (inherited from `shz::vecN`)

### deref

```cpp
CppType & shz::vecN< CRTP, C, R >::deref(const auto *raw) noexcept
```

Conversion operator for accessing an existing pointer type as though it were a refrence to a SH4ZAM type.

Inherited from `shz::vecN`.

### direction

```cpp
CppType shz::vecN< CRTP, C, R >::direction() const noexcept
```

Returns the direction vector resulting from normalizing the given vector.

Calls: [`shz_vec3_normalize()`](https://sh4zam.com/api/vector/shz_vec3_normalize/) (inherited from `shz::vecN`)

### direction_safe

```cpp
CppType shz::vecN< CRTP, C, R >::direction_safe() const noexcept
```

Returns the direction vector of a given vector, safely protecting against division-by-zero.

Calls: [`shz_vec3_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec3_normalize_safe/) (inherited from `shz::vecN`)

### distance

```cpp
float shz::vecN< CRTP, C, R >::distance(const CppType &other) const noexcept
```

Returns the magnitude of the difference between two vectors as their distance.

Calls: [`shz_vec3_distance()`](https://sh4zam.com/api/vector/shz_vec3_distance/) (inherited from `shz::vecN`)

### distance_sqr

```cpp
float shz::vecN< CRTP, C, R >::distance_sqr(const CppType &other) const noexcept
```

Returns the value of the distance between two vectors squared (faster than actual distance).

Calls: [`shz_vec3_distance_sqr()`](https://sh4zam.com/api/vector/shz_vec3_distance_sqr/) (inherited from `shz::vecN`)

### floor

```cpp
CppType shz::vecN< CRTP, C, R >::floor() const noexcept
```

Returns a new vector with the component-wise floor of the given vector.

Calls: [`shz_vec3_floor()`](https://sh4zam.com/api/vector/shz_vec3_floor/) (inherited from `shz::vecN`)

### fract

```cpp
CppType shz::vecN< CRTP, C, R >::fract() const noexcept
```

Returns a new vector with the fractional part of each component.

Calls: [`shz_vec3_fract()`](https://sh4zam.com/api/vector/shz_vec3_fract/) (inherited from `shz::vecN`)

### inv

```cpp
CppType shz::vecN< CRTP, C, R >::inv() const noexcept
```

Returns a new vector whose components are the reciprocal values of the given vector.

Calls: [`shz_vec3_inv()`](https://sh4zam.com/api/vector/shz_vec3_inv/) (inherited from `shz::vecN`)

### inv_sqrtf

```cpp
CppType shz::vecN< CRTP, C, R >::inv_sqrtf() const noexcept
```

Returns a new vector whose components are the inverse square root of the given vector.

Calls: [`shz_vec3_inv_sqrtf()`](https://sh4zam.com/api/vector/shz_vec3_inv_sqrtf/) (inherited from `shz::vecN`)

### magnitude

```cpp
float shz::vecN< CRTP, C, R >::magnitude() const noexcept
```

Returns the magnitude of the given vector.

Calls: [`shz_vec3_magnitude()`](https://sh4zam.com/api/vector/shz_vec3_magnitude/) (inherited from `shz::vecN`)

### magnitude_inv

```cpp
float shz::vecN< CRTP, C, R >::magnitude_inv() const noexcept
```

Returns the inverse magnitude of the given vector.

Calls: [`shz_vec3_magnitude_inv()`](https://sh4zam.com/api/vector/shz_vec3_magnitude_inv/) (inherited from `shz::vecN`)

### magnitude_sqr

```cpp
float shz::vecN< CRTP, C, R >::magnitude_sqr() const noexcept
```

Returns the squared magnitude of the given vector.

Calls: [`shz_vec3_magnitude_sqr()`](https://sh4zam.com/api/vector/shz_vec3_magnitude_sqr/) (inherited from `shz::vecN`)

### max

```cpp
float shz::vecN< CRTP, C, R >::max() const noexcept
```

Returns the maximum value of every element within the vector.

Calls: [`shz_vec3_max()`](https://sh4zam.com/api/vector/shz_vec3_max/) (inherited from `shz::vecN`)

### maxv

```cpp
CppType shz::vecN< CRTP, C, R >::maxv(const CppType &other) const noexcept
```

Returns a new vector with the component-wise maximum of two vectors.

Calls: [`shz_vec3_maxv()`](https://sh4zam.com/api/vector/shz_vec3_maxv/) (inherited from `shz::vecN`)

### min

```cpp
float shz::vecN< CRTP, C, R >::min() const noexcept
```

Returns the minimum value of every element within the vector.

Calls: [`shz_vec3_min()`](https://sh4zam.com/api/vector/shz_vec3_min/) (inherited from `shz::vecN`)

### minv

```cpp
CppType shz::vecN< CRTP, C, R >::minv(const CppType &other) const noexcept
```

Returns a new vector with the component-wise minimum of two vectors.

Calls: [`shz_vec3_minv()`](https://sh4zam.com/api/vector/shz_vec3_minv/) (inherited from `shz::vecN`)

### move

```cpp
CppType shz::vecN< CRTP, C, R >::move(const CppType &target, float maxdist) const noexcept
```

Moves the given vector towards the target by the given `maxdist`.

Calls: [`shz_vec3_move()`](https://sh4zam.com/api/vector/shz_vec3_move/) (inherited from `shz::vecN`)

### neg

```cpp
CppType shz::vecN< CRTP, C, R >::neg() const noexcept
```

Returns a new vector whose components are the negative values of the given vector.

Calls: [`shz_vec3_neg()`](https://sh4zam.com/api/vector/shz_vec3_neg/) (inherited from `shz::vecN`)

### normalize

```cpp
void shz::vecN< CRTP, C, R >::normalize() noexcept
```

Normalizes the given vector.

Calls: [`shz_vec3_normalize()`](https://sh4zam.com/api/vector/shz_vec3_normalize/) (inherited from `shz::vecN`)

### normalize_safe

```cpp
void shz::vecN< CRTP, C, R >::normalize_safe() noexcept
```

Normalizes the given vector, safely protecting against division-by-zero.

Calls: [`shz_vec3_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec3_normalize_safe/) (inherited from `shz::vecN`)

### normalized

```cpp
CppType shz::vecN< CRTP, C, R >::normalized() const noexcept
```

Return the normalized vector.

Calls: [`shz_vec3_normalize()`](https://sh4zam.com/api/vector/shz_vec3_normalize/) (inherited from `shz::vecN`)

### normalized_safe

```cpp
CppType shz::vecN< CRTP, C, R >::normalized_safe() const noexcept
```

Return the normalized vector, safely protecting against division-by-zero.

Calls: [`shz_vec3_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec3_normalize_safe/) (inherited from `shz::vecN`)

### operator*=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator*=(const CppType &other) noexcept
```

Overloaded multiplication assignment operator, multiplies and accumulates a vector onto the left-hand vector.

Inherited from `shz::vecN`.

### operator+=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator+=(const CppType &other) noexcept
```

Overloaded operator for adding and accumulating a vector onto another.

Inherited from `shz::vecN`.

### operator-=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator-=(const CppType &other) noexcept
```

Overloaded subtraction assignment operator, subtracts a vector from the left-hand vector.

Inherited from `shz::vecN`.

### operator/=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator/=(const CppType &other) noexcept
```

Overloaded division assignment operator, divides the left vector by the right, assigning the left to the result.

Inherited from `shz::vecN`.

### project

```cpp
CppType shz::vecN< CRTP, C, R >::project(const CppType &onto) const noexcept
```

Returns the vector created from projecting the given vector onto another.

Calls: [`shz_vec3_project()`](https://sh4zam.com/api/vector/shz_vec3_project/) (inherited from `shz::vecN`)

### project_safe

```cpp
CppType shz::vecN< CRTP, C, R >::project_safe(const CppType &onto) const noexcept
```

Returns the vector created from projecting the given vector onto another, safely protecting against division-by-zero.

Calls: [`shz_vec3_project_safe()`](https://sh4zam.com/api/vector/shz_vec3_project_safe/) (inherited from `shz::vecN`)

### reflect

```cpp
CppType shz::vecN< CRTP, C, R >::reflect(const CppType &normal) const noexcept
```

Returns the vector created from reflecting the given vector over the normal of a surface.

Calls: [`shz_vec3_reflect()`](https://sh4zam.com/api/vector/shz_vec3_reflect/) (inherited from `shz::vecN`)

### refract

```cpp
CppType shz::vecN< CRTP, C, R >::refract(const CppType &normal, float eta) const noexcept
```

Returns the vector create from refracting the given incidence vector over the normal of a surface, using the given refraction ratio index.

Calls: [`shz_vec3_refract()`](https://sh4zam.com/api/vector/shz_vec3_refract/) (inherited from `shz::vecN`)

### round

```cpp
CppType shz::vecN< CRTP, C, R >::round() const noexcept
```

Returns a new vector with the component-wise rounding of the given vector.

Calls: [`shz_vec3_round()`](https://sh4zam.com/api/vector/shz_vec3_round/) (inherited from `shz::vecN`)

### saturate

```cpp
CppType shz::vecN< CRTP, C, R >::saturate() const noexcept
```

Returns a new vector with each component clamped to \[0, 1\].

Calls: [`shz_vec3_saturate()`](https://sh4zam.com/api/vector/shz_vec3_saturate/) (inherited from `shz::vecN`)

### sign

```cpp
CppType shz::vecN< CRTP, C, R >::sign() const noexcept
```

Returns a new vector with the sign of each component (-1, 0, or 1).

Calls: [`shz_vec3_sign()`](https://sh4zam.com/api/vector/shz_vec3_sign/) (inherited from `shz::vecN`)

### sqrtf

```cpp
CppType shz::vecN< CRTP, C, R >::sqrtf() const noexcept
```

Returns a new vector whose components are the square root of the given vector.

Calls: [`shz_vec3_sqrtf()`](https://sh4zam.com/api/vector/shz_vec3_sqrtf/) (inherited from `shz::vecN`)

### swizzle

```cpp
CppType shz::vecN< CRTP, C, R >::swizzle() const noexcept
```

Swizzle oeprator which takes a compile-time list of indices as non-type template arguments for the index each element should use as its new value.

Calls: [`shz_vec3_swizzle()`](https://sh4zam.com/api/vector/shz_vec3_swizzle/) (inherited from `shz::vecN`)

### to

```cpp
T shz::vecN< CRTP, C, R >::to() const noexcept
```

Conversion operator for going from a SH4ZAM vector type to another layout-compatible type.

Inherited from `shz::vecN`.


---
# shz::vec4

Source: https://sh4zam.com/api/cpp/vec4/

4D Vector type

C++ structure for representing a 4-dimensional vector.

- **Header:** `#include <sh4zam/shz_vector.hpp>` ([source](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.hpp#L613))
- **C type:** [`shz_vec4_t`](https://sh4zam.com/api/vector/shz_vec4_t/) (layout-compatible; the C API accepts it directly)
- **Bases:** `shz::vecN< vec4, shz_vec4_t, 4 >`

## Static functions

### from

```cpp
static CppType shz::vecN< CRTP, C, R >::from(const auto &raw) noexcept
```

Conversion operator for going from a layout-compatible vector type to a SH4ZAM vector type.

Inherited from `shz::vecN`.

### lerp

```cpp
static CppType shz::vecN< CRTP, C, R >::lerp(const CppType &start, const CppType &end, float t) noexcept
```

Returns the vector that is linearly interpolated between the two given vectors by the `0.0f-1.0f` factor, `t`.

Calls: [`shz_vec4_lerp()`](https://sh4zam.com/api/vector/shz_vec4_lerp/) (inherited from `shz::vecN`)

### smoothstep

```cpp
static CppType shz::vecN< CRTP, C, R >::smoothstep(const CppType &vec, T &&edge0, T &&edge1) noexcept
```

Returns a vector where each component is smoothly interpolated from 0 to 1 between edge0 and edge1.

Calls: [`shz_vec4_smoothstep()`](https://sh4zam.com/api/vector/shz_vec4_smoothstep/) (inherited from `shz::vecN`)

### smoothstep_safe

```cpp
static CppType shz::vecN< CRTP, C, R >::smoothstep_safe(const CppType &vec, T &&edge0, T &&edge1) noexcept
```

Returns a vector where each component is smoothly interpolated from 0 to 1 between edge0 and edge1.

Calls: [`shz_vec4_smoothstep_safe()`](https://sh4zam.com/api/vector/shz_vec4_smoothstep_safe/) (inherited from `shz::vecN`)

### step

```cpp
static CppType shz::vecN< CRTP, C, R >::step(const CppType &vec, T &&edge) noexcept
```

Compares each component of the vector to the edge. 0 returned in that component if x\[i\] \< edge. Otherwise the component is 1.

Calls: [`shz_vec4_step()`](https://sh4zam.com/api/vector/shz_vec4_step/) (inherited from `shz::vecN`)

## Members

### vec4

```cpp
vec4()=default
vec4(const shz_vec4_t &other) noexcept
vec4(float v) noexcept
vec4(float x, float y, float z, float w) noexcept
vec4(const shz::vec2 &xy, float z, float w) noexcept
vec4(float x, const shz::vec2 &yz, float w) noexcept
vec4(float x, float y, const shz::vec2 &zw) noexcept
vec4(const shz::vec2 &xy, const shz::vec2 &zw) noexcept
vec4(const shz::vec3 &xyz, float w) noexcept
vec4(float x, const shz::vec3 &yzw) noexcept
```

Default constructor: does nothing.

### xy

```cpp
vec2 xy() const noexcept
```

### zw

```cpp
vec2 zw() const noexcept
```

### xyz

```cpp
vec3 xyz() const noexcept
```

### vecN

```cpp
shz::vecN< CRTP, C, R >::vecN() noexcept=default
shz::vecN< CRTP, C, R >::vecN(const vecN &other) noexcept=default
shz::vecN< CRTP, C, R >::vecN(const CType &other) noexcept
shz::vecN< CRTP, C, R >::vecN(const volatile CType &other) noexcept
```

Default constructor, does nothing.

### dot

```cpp
float shz::vecN< CRTP, C, R >::dot(const CppType &other) const noexcept
vec2 shz::vecN< CRTP, C, R >::dot(const CppType &v1, const CppType &v2) const noexcept
vec3 shz::vecN< CRTP, C, R >::dot(const CppType &v1, const CppType &v2, const CppType &v3) const noexcept
```

Returns the dot product of the given vector and another.

### abs

```cpp
CppType shz::vecN< CRTP, C, R >::abs() const noexcept
```

Returns a new vector whose components are the absolute value of the given vector.

Calls: [`shz_vec4_abs()`](https://sh4zam.com/api/vector/shz_vec4_abs/) (inherited from `shz::vecN`)

### angle_between

```cpp
float shz::vecN< CRTP, C, R >::angle_between(const CppType &other) const noexcept
```

Returns the angle between the given vector and another, in radians.

Calls: [`shz_vec_angle_between()`](https://sh4zam.com/api/vector/shz_vec_angle_between/) (inherited from `shz::vecN`)

### angles

```cpp
auto shz::vecN< CRTP, C, R >::angles() const noexcept
```

Returns the angle(s) created between the given vector axis and the +X axis, in radians.

Calls: [`shz_vec_angles()`](https://sh4zam.com/api/vector/shz_vec_angles/) (inherited from `shz::vecN`)

### ceil

```cpp
CppType shz::vecN< CRTP, C, R >::ceil() const noexcept
```

Returns a new vector with the component-wise ceil of the given vector.

Calls: [`shz_vec4_ceil()`](https://sh4zam.com/api/vector/shz_vec4_ceil/) (inherited from `shz::vecN`)

### clamp

```cpp
CppType shz::vecN< CRTP, C, R >::clamp(float min, float max) const noexcept
```

Returns a new vector whose values are the clamped components of the given vector.

Calls: [`shz_vec4_clamp()`](https://sh4zam.com/api/vector/shz_vec4_clamp/) (inherited from `shz::vecN`)

### deref

```cpp
CppType & shz::vecN< CRTP, C, R >::deref(const auto *raw) noexcept
```

Conversion operator for accessing an existing pointer type as though it were a refrence to a SH4ZAM type.

Inherited from `shz::vecN`.

### direction

```cpp
CppType shz::vecN< CRTP, C, R >::direction() const noexcept
```

Returns the direction vector resulting from normalizing the given vector.

Calls: [`shz_vec4_normalize()`](https://sh4zam.com/api/vector/shz_vec4_normalize/) (inherited from `shz::vecN`)

### direction_safe

```cpp
CppType shz::vecN< CRTP, C, R >::direction_safe() const noexcept
```

Returns the direction vector of a given vector, safely protecting against division-by-zero.

Calls: [`shz_vec4_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec4_normalize_safe/) (inherited from `shz::vecN`)

### distance

```cpp
float shz::vecN< CRTP, C, R >::distance(const CppType &other) const noexcept
```

Returns the magnitude of the difference between two vectors as their distance.

Calls: [`shz_vec4_distance()`](https://sh4zam.com/api/vector/shz_vec4_distance/) (inherited from `shz::vecN`)

### distance_sqr

```cpp
float shz::vecN< CRTP, C, R >::distance_sqr(const CppType &other) const noexcept
```

Returns the value of the distance between two vectors squared (faster than actual distance).

Calls: [`shz_vec4_distance_sqr()`](https://sh4zam.com/api/vector/shz_vec4_distance_sqr/) (inherited from `shz::vecN`)

### floor

```cpp
CppType shz::vecN< CRTP, C, R >::floor() const noexcept
```

Returns a new vector with the component-wise floor of the given vector.

Calls: [`shz_vec4_floor()`](https://sh4zam.com/api/vector/shz_vec4_floor/) (inherited from `shz::vecN`)

### fract

```cpp
CppType shz::vecN< CRTP, C, R >::fract() const noexcept
```

Returns a new vector with the fractional part of each component.

Calls: [`shz_vec4_fract()`](https://sh4zam.com/api/vector/shz_vec4_fract/) (inherited from `shz::vecN`)

### inv

```cpp
CppType shz::vecN< CRTP, C, R >::inv() const noexcept
```

Returns a new vector whose components are the reciprocal values of the given vector.

Calls: [`shz_vec4_inv()`](https://sh4zam.com/api/vector/shz_vec4_inv/) (inherited from `shz::vecN`)

### inv_sqrtf

```cpp
CppType shz::vecN< CRTP, C, R >::inv_sqrtf() const noexcept
```

Returns a new vector whose components are the inverse square root of the given vector.

Calls: [`shz_vec4_inv_sqrtf()`](https://sh4zam.com/api/vector/shz_vec4_inv_sqrtf/) (inherited from `shz::vecN`)

### magnitude

```cpp
float shz::vecN< CRTP, C, R >::magnitude() const noexcept
```

Returns the magnitude of the given vector.

Calls: [`shz_vec4_magnitude()`](https://sh4zam.com/api/vector/shz_vec4_magnitude/) (inherited from `shz::vecN`)

### magnitude_inv

```cpp
float shz::vecN< CRTP, C, R >::magnitude_inv() const noexcept
```

Returns the inverse magnitude of the given vector.

Calls: [`shz_vec4_magnitude_inv()`](https://sh4zam.com/api/vector/shz_vec4_magnitude_inv/) (inherited from `shz::vecN`)

### magnitude_sqr

```cpp
float shz::vecN< CRTP, C, R >::magnitude_sqr() const noexcept
```

Returns the squared magnitude of the given vector.

Calls: [`shz_vec4_magnitude_sqr()`](https://sh4zam.com/api/vector/shz_vec4_magnitude_sqr/) (inherited from `shz::vecN`)

### max

```cpp
float shz::vecN< CRTP, C, R >::max() const noexcept
```

Returns the maximum value of every element within the vector.

Calls: [`shz_vec4_max()`](https://sh4zam.com/api/vector/shz_vec4_max/) (inherited from `shz::vecN`)

### maxv

```cpp
CppType shz::vecN< CRTP, C, R >::maxv(const CppType &other) const noexcept
```

Returns a new vector with the component-wise maximum of two vectors.

Calls: [`shz_vec4_maxv()`](https://sh4zam.com/api/vector/shz_vec4_maxv/) (inherited from `shz::vecN`)

### min

```cpp
float shz::vecN< CRTP, C, R >::min() const noexcept
```

Returns the minimum value of every element within the vector.

Calls: [`shz_vec4_min()`](https://sh4zam.com/api/vector/shz_vec4_min/) (inherited from `shz::vecN`)

### minv

```cpp
CppType shz::vecN< CRTP, C, R >::minv(const CppType &other) const noexcept
```

Returns a new vector with the component-wise minimum of two vectors.

Calls: [`shz_vec4_minv()`](https://sh4zam.com/api/vector/shz_vec4_minv/) (inherited from `shz::vecN`)

### move

```cpp
CppType shz::vecN< CRTP, C, R >::move(const CppType &target, float maxdist) const noexcept
```

Moves the given vector towards the target by the given `maxdist`.

Calls: [`shz_vec4_move()`](https://sh4zam.com/api/vector/shz_vec4_move/) (inherited from `shz::vecN`)

### neg

```cpp
CppType shz::vecN< CRTP, C, R >::neg() const noexcept
```

Returns a new vector whose components are the negative values of the given vector.

Calls: [`shz_vec4_neg()`](https://sh4zam.com/api/vector/shz_vec4_neg/) (inherited from `shz::vecN`)

### normalize

```cpp
void shz::vecN< CRTP, C, R >::normalize() noexcept
```

Normalizes the given vector.

Calls: [`shz_vec4_normalize()`](https://sh4zam.com/api/vector/shz_vec4_normalize/) (inherited from `shz::vecN`)

### normalize_safe

```cpp
void shz::vecN< CRTP, C, R >::normalize_safe() noexcept
```

Normalizes the given vector, safely protecting against division-by-zero.

Calls: [`shz_vec4_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec4_normalize_safe/) (inherited from `shz::vecN`)

### normalized

```cpp
CppType shz::vecN< CRTP, C, R >::normalized() const noexcept
```

Return the normalized vector.

Calls: [`shz_vec4_normalize()`](https://sh4zam.com/api/vector/shz_vec4_normalize/) (inherited from `shz::vecN`)

### normalized_safe

```cpp
CppType shz::vecN< CRTP, C, R >::normalized_safe() const noexcept
```

Return the normalized vector, safely protecting against division-by-zero.

Calls: [`shz_vec4_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec4_normalize_safe/) (inherited from `shz::vecN`)

### operator*=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator*=(const CppType &other) noexcept
```

Overloaded multiplication assignment operator, multiplies and accumulates a vector onto the left-hand vector.

Inherited from `shz::vecN`.

### operator+=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator+=(const CppType &other) noexcept
```

Overloaded operator for adding and accumulating a vector onto another.

Inherited from `shz::vecN`.

### operator-=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator-=(const CppType &other) noexcept
```

Overloaded subtraction assignment operator, subtracts a vector from the left-hand vector.

Inherited from `shz::vecN`.

### operator/=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator/=(const CppType &other) noexcept
```

Overloaded division assignment operator, divides the left vector by the right, assigning the left to the result.

Inherited from `shz::vecN`.

### project

```cpp
CppType shz::vecN< CRTP, C, R >::project(const CppType &onto) const noexcept
```

Returns the vector created from projecting the given vector onto another.

Calls: [`shz_vec4_project()`](https://sh4zam.com/api/vector/shz_vec4_project/) (inherited from `shz::vecN`)

### project_safe

```cpp
CppType shz::vecN< CRTP, C, R >::project_safe(const CppType &onto) const noexcept
```

Returns the vector created from projecting the given vector onto another, safely protecting against division-by-zero.

Calls: [`shz_vec4_project_safe()`](https://sh4zam.com/api/vector/shz_vec4_project_safe/) (inherited from `shz::vecN`)

### reflect

```cpp
CppType shz::vecN< CRTP, C, R >::reflect(const CppType &normal) const noexcept
```

Returns the vector created from reflecting the given vector over the normal of a surface.

Calls: [`shz_vec4_reflect()`](https://sh4zam.com/api/vector/shz_vec4_reflect/) (inherited from `shz::vecN`)

### refract

```cpp
CppType shz::vecN< CRTP, C, R >::refract(const CppType &normal, float eta) const noexcept
```

Returns the vector create from refracting the given incidence vector over the normal of a surface, using the given refraction ratio index.

Calls: [`shz_vec4_refract()`](https://sh4zam.com/api/vector/shz_vec4_refract/) (inherited from `shz::vecN`)

### round

```cpp
CppType shz::vecN< CRTP, C, R >::round() const noexcept
```

Returns a new vector with the component-wise rounding of the given vector.

Calls: [`shz_vec4_round()`](https://sh4zam.com/api/vector/shz_vec4_round/) (inherited from `shz::vecN`)

### saturate

```cpp
CppType shz::vecN< CRTP, C, R >::saturate() const noexcept
```

Returns a new vector with each component clamped to \[0, 1\].

Calls: [`shz_vec4_saturate()`](https://sh4zam.com/api/vector/shz_vec4_saturate/) (inherited from `shz::vecN`)

### sign

```cpp
CppType shz::vecN< CRTP, C, R >::sign() const noexcept
```

Returns a new vector with the sign of each component (-1, 0, or 1).

Calls: [`shz_vec4_sign()`](https://sh4zam.com/api/vector/shz_vec4_sign/) (inherited from `shz::vecN`)

### sqrtf

```cpp
CppType shz::vecN< CRTP, C, R >::sqrtf() const noexcept
```

Returns a new vector whose components are the square root of the given vector.

Calls: [`shz_vec4_sqrtf()`](https://sh4zam.com/api/vector/shz_vec4_sqrtf/) (inherited from `shz::vecN`)

### swizzle

```cpp
CppType shz::vecN< CRTP, C, R >::swizzle() const noexcept
```

Swizzle oeprator which takes a compile-time list of indices as non-type template arguments for the index each element should use as its new value.

Calls: [`shz_vec4_swizzle()`](https://sh4zam.com/api/vector/shz_vec4_swizzle/) (inherited from `shz::vecN`)

### to

```cpp
T shz::vecN< CRTP, C, R >::to() const noexcept
```

Conversion operator for going from a SH4ZAM vector type to another layout-compatible type.

Inherited from `shz::vecN`.


---
# shz::vecN

Source: https://sh4zam.com/api/cpp/vecn/

Common C++ base structure inherited by all vector types.

This struct template serves as the base class for all concrete vector types, providing:

- Common API routines
- Adaptor between C and C++ types
- Convenience overloaded operators and STL iterators.

- **Header:** `#include <sh4zam/shz_vector.hpp>` ([source](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.hpp#L43))
- **Bases:** `C`

## Static functions

### from

```cpp
static CppType shz::vecN< CRTP, C, R >::from(const auto &raw) noexcept
```

Conversion operator for going from a layout-compatible vector type to a SH4ZAM vector type.

### lerp

```cpp
static CppType shz::vecN< CRTP, C, R >::lerp(const CppType &start, const CppType &end, float t) noexcept
```

Returns the vector that is linearly interpolated between the two given vectors by the `0.0f-1.0f` factor, `t`.

Calls: [`shz_vec_lerp()`](https://sh4zam.com/api/vector/shz_vec_lerp/)

### step

```cpp
static CppType shz::vecN< CRTP, C, R >::step(const CppType &vec, T &&edge) noexcept
```

Compares each component of the vector to the edge. 0 returned in that component if x\[i\] \< edge. Otherwise the component is 1.

Calls: [`shz_vec_step()`](https://sh4zam.com/api/vector/shz_vec_step/)

### smoothstep

```cpp
static CppType shz::vecN< CRTP, C, R >::smoothstep(const CppType &vec, T &&edge0, T &&edge1) noexcept
```

Returns a vector where each component is smoothly interpolated from 0 to 1 between edge0 and edge1.

Calls: [`shz_vec_smoothstep()`](https://sh4zam.com/api/vector/shz_vec_smoothstep/)

### smoothstep_safe

```cpp
static CppType shz::vecN< CRTP, C, R >::smoothstep_safe(const CppType &vec, T &&edge0, T &&edge1) noexcept
```

Returns a vector where each component is smoothly interpolated from 0 to 1 between edge0 and edge1.

Calls: [`shz_vec_smoothstep_safe()`](https://sh4zam.com/api/vector/shz_vec_smoothstep_safe/)

## Members

### vecN

```cpp
shz::vecN< CRTP, C, R >::vecN() noexcept=default
shz::vecN< CRTP, C, R >::vecN(const vecN &other) noexcept=default
shz::vecN< CRTP, C, R >::vecN(const CType &other) noexcept
shz::vecN< CRTP, C, R >::vecN(const volatile CType &other) noexcept
```

Default constructor, does nothing.

### to

```cpp
T shz::vecN< CRTP, C, R >::to() const noexcept
```

Conversion operator for going from a SH4ZAM vector type to another layout-compatible type.

### deref

```cpp
CppType & shz::vecN< CRTP, C, R >::deref(const auto *raw) noexcept
```

Conversion operator for accessing an existing pointer type as though it were a refrence to a SH4ZAM type.

### operator+=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator+=(const CppType &other) noexcept
```

Overloaded operator for adding and accumulating a vector onto another.

### operator-=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator-=(const CppType &other) noexcept
```

Overloaded subtraction assignment operator, subtracts a vector from the left-hand vector.

### operator*=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator*=(const CppType &other) noexcept
CppType & shz::vecN< CRTP, C, R >::operator*=(float other) noexcept
```

Overloaded multiplication assignment operator, multiplies and accumulates a vector onto the left-hand vector.

### operator/=

```cpp
CppType & shz::vecN< CRTP, C, R >::operator/=(const CppType &other) noexcept
CppType & shz::vecN< CRTP, C, R >::operator/=(float other) noexcept
```

Overloaded division assignment operator, divides the left vector by the right, assigning the left to the result.

### swizzle

```cpp
CppType shz::vecN< CRTP, C, R >::swizzle() const noexcept
```

Swizzle oeprator which takes a compile-time list of indices as non-type template arguments for the index each element should use as its new value.

Calls: [`shz_vec_swizzle()`](https://sh4zam.com/api/vector/shz_vec_swizzle/)

### abs

```cpp
CppType shz::vecN< CRTP, C, R >::abs() const noexcept
```

Returns a new vector whose components are the absolute value of the given vector.

Calls: [`shz_vec_abs()`](https://sh4zam.com/api/vector/shz_vec_abs/)

### neg

```cpp
CppType shz::vecN< CRTP, C, R >::neg() const noexcept
```

Returns a new vector whose components are the negative values of the given vector.

Calls: [`shz_vec_neg()`](https://sh4zam.com/api/vector/shz_vec_neg/)

### inv

```cpp
CppType shz::vecN< CRTP, C, R >::inv() const noexcept
```

Returns a new vector whose components are the reciprocal values of the given vector.

Calls: [`shz_vec_inv()`](https://sh4zam.com/api/vector/shz_vec_inv/)

### max

```cpp
float shz::vecN< CRTP, C, R >::max() const noexcept
```

Returns the maximum value of every element within the vector.

Calls: [`shz_vec_max()`](https://sh4zam.com/api/vector/shz_vec_max/)

### min

```cpp
float shz::vecN< CRTP, C, R >::min() const noexcept
```

Returns the minimum value of every element within the vector.

Calls: [`shz_vec_min()`](https://sh4zam.com/api/vector/shz_vec_min/)

### clamp

```cpp
CppType shz::vecN< CRTP, C, R >::clamp(float min, float max) const noexcept
```

Returns a new vector whose values are the clamped components of the given vector.

Calls: [`shz_vec_clamp()`](https://sh4zam.com/api/vector/shz_vec_clamp/)

### floor

```cpp
CppType shz::vecN< CRTP, C, R >::floor() const noexcept
```

Returns a new vector with the component-wise floor of the given vector.

Calls: [`shz_vec_floor()`](https://sh4zam.com/api/vector/shz_vec_floor/)

### ceil

```cpp
CppType shz::vecN< CRTP, C, R >::ceil() const noexcept
```

Returns a new vector with the component-wise ceil of the given vector.

Calls: [`shz_vec_ceil()`](https://sh4zam.com/api/vector/shz_vec_ceil/)

### round

```cpp
CppType shz::vecN< CRTP, C, R >::round() const noexcept
```

Returns a new vector with the component-wise rounding of the given vector.

Calls: [`shz_vec_round()`](https://sh4zam.com/api/vector/shz_vec_round/)

### fract

```cpp
CppType shz::vecN< CRTP, C, R >::fract() const noexcept
```

Returns a new vector with the fractional part of each component.

Calls: [`shz_vec_fract()`](https://sh4zam.com/api/vector/shz_vec_fract/)

### sign

```cpp
CppType shz::vecN< CRTP, C, R >::sign() const noexcept
```

Returns a new vector with the sign of each component (-1, 0, or 1).

Calls: [`shz_vec_sign()`](https://sh4zam.com/api/vector/shz_vec_sign/)

### saturate

```cpp
CppType shz::vecN< CRTP, C, R >::saturate() const noexcept
```

Returns a new vector with each component clamped to \[0, 1\].

Calls: [`shz_vec_saturate()`](https://sh4zam.com/api/vector/shz_vec_saturate/)

### minv

```cpp
CppType shz::vecN< CRTP, C, R >::minv(const CppType &other) const noexcept
```

Returns a new vector with the component-wise minimum of two vectors.

Calls: [`shz_vec_minv()`](https://sh4zam.com/api/vector/shz_vec_minv/)

### maxv

```cpp
CppType shz::vecN< CRTP, C, R >::maxv(const CppType &other) const noexcept
```

Returns a new vector with the component-wise maximum of two vectors.

Calls: [`shz_vec_maxv()`](https://sh4zam.com/api/vector/shz_vec_maxv/)

### inv_sqrtf

```cpp
CppType shz::vecN< CRTP, C, R >::inv_sqrtf() const noexcept
```

Returns a new vector whose components are the inverse square root of the given vector.

Calls: [`shz_vec_inv_sqrtf()`](https://sh4zam.com/api/vector/shz_vec_inv_sqrtf/)

### sqrtf

```cpp
CppType shz::vecN< CRTP, C, R >::sqrtf() const noexcept
```

Returns a new vector whose components are the square root of the given vector.

Calls: [`shz_vec_sqrtf()`](https://sh4zam.com/api/vector/shz_vec_sqrtf/)

### dot

```cpp
float shz::vecN< CRTP, C, R >::dot(const CppType &other) const noexcept
vec2 shz::vecN< CRTP, C, R >::dot(const CppType &v1, const CppType &v2) const noexcept
vec3 shz::vecN< CRTP, C, R >::dot(const CppType &v1, const CppType &v2, const CppType &v3) const noexcept
```

Returns the dot product of the given vector and another.

Calls: [`shz_vec_dot()`](https://sh4zam.com/api/vector/shz_vec_dot/)

### magnitude

```cpp
float shz::vecN< CRTP, C, R >::magnitude() const noexcept
```

Returns the magnitude of the given vector.

Calls: [`shz_vec_magnitude()`](https://sh4zam.com/api/vector/shz_vec_magnitude/)

### magnitude_sqr

```cpp
float shz::vecN< CRTP, C, R >::magnitude_sqr() const noexcept
```

Returns the squared magnitude of the given vector.

Calls: [`shz_vec_magnitude_sqr()`](https://sh4zam.com/api/vector/shz_vec_magnitude_sqr/)

### magnitude_inv

```cpp
float shz::vecN< CRTP, C, R >::magnitude_inv() const noexcept
```

Returns the inverse magnitude of the given vector.

Calls: [`shz_vec_magnitude_inv()`](https://sh4zam.com/api/vector/shz_vec_magnitude_inv/)

### direction

```cpp
CppType shz::vecN< CRTP, C, R >::direction() const noexcept
```

Returns the direction vector resulting from normalizing the given vector.

Calls: [`shz_vec_normalize()`](https://sh4zam.com/api/vector/shz_vec_normalize/)

### direction_safe

```cpp
CppType shz::vecN< CRTP, C, R >::direction_safe() const noexcept
```

Returns the direction vector of a given vector, safely protecting against division-by-zero.

Calls: [`shz_vec_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec_normalize_safe/)

### normalize

```cpp
void shz::vecN< CRTP, C, R >::normalize() noexcept
```

Normalizes the given vector.

Calls: [`shz_vec_normalize()`](https://sh4zam.com/api/vector/shz_vec_normalize/)

### normalize_safe

```cpp
void shz::vecN< CRTP, C, R >::normalize_safe() noexcept
```

Normalizes the given vector, safely protecting against division-by-zero.

Calls: [`shz_vec_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec_normalize_safe/)

### normalized

```cpp
CppType shz::vecN< CRTP, C, R >::normalized() const noexcept
```

Return the normalized vector.

Calls: [`shz_vec_normalize()`](https://sh4zam.com/api/vector/shz_vec_normalize/)

### normalized_safe

```cpp
CppType shz::vecN< CRTP, C, R >::normalized_safe() const noexcept
```

Return the normalized vector, safely protecting against division-by-zero.

Calls: [`shz_vec_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec_normalize_safe/)

### distance

```cpp
float shz::vecN< CRTP, C, R >::distance(const CppType &other) const noexcept
```

Returns the magnitude of the difference between two vectors as their distance.

Calls: [`shz_vec_distance()`](https://sh4zam.com/api/vector/shz_vec_distance/)

### distance_sqr

```cpp
float shz::vecN< CRTP, C, R >::distance_sqr(const CppType &other) const noexcept
```

Returns the value of the distance between two vectors squared (faster than actual distance).

Calls: [`shz_vec_distance_sqr()`](https://sh4zam.com/api/vector/shz_vec_distance_sqr/)

### move

```cpp
CppType shz::vecN< CRTP, C, R >::move(const CppType &target, float maxdist) const noexcept
```

Moves the given vector towards the target by the given `maxdist`.

Calls: [`shz_vec_move()`](https://sh4zam.com/api/vector/shz_vec_move/)

### reflect

```cpp
CppType shz::vecN< CRTP, C, R >::reflect(const CppType &normal) const noexcept
```

Returns the vector created from reflecting the given vector over the normal of a surface.

Calls: [`shz_vec_reflect()`](https://sh4zam.com/api/vector/shz_vec_reflect/)

### refract

```cpp
CppType shz::vecN< CRTP, C, R >::refract(const CppType &normal, float eta) const noexcept
```

Returns the vector create from refracting the given incidence vector over the normal of a surface, using the given refraction ratio index.

Calls: [`shz_vec_refract()`](https://sh4zam.com/api/vector/shz_vec_refract/)

### project

```cpp
CppType shz::vecN< CRTP, C, R >::project(const CppType &onto) const noexcept
```

Returns the vector created from projecting the given vector onto another.

Calls: [`shz_vec_project()`](https://sh4zam.com/api/vector/shz_vec_project/)

### project_safe

```cpp
CppType shz::vecN< CRTP, C, R >::project_safe(const CppType &onto) const noexcept
```

Returns the vector created from projecting the given vector onto another, safely protecting against division-by-zero.

Calls: [`shz_vec_project_safe()`](https://sh4zam.com/api/vector/shz_vec_project_safe/)

### angle_between

```cpp
float shz::vecN< CRTP, C, R >::angle_between(const CppType &other) const noexcept
```

Returns the angle between the given vector and another, in radians.

Calls: [`shz_vec_angle_between()`](https://sh4zam.com/api/vector/shz_vec_angle_between/)

### angles

```cpp
auto shz::vecN< CRTP, C, R >::angles() const noexcept
```

Returns the angle(s) created between the given vector axis and the +X axis, in radians.

Calls: [`shz_vec_angles()`](https://sh4zam.com/api/vector/shz_vec_angles/)

### operator==

```cpp
bool operator==(const CppType &lhs, const CppType &rhs) noexcept
```

Overloaded equality operator, for comparing vectors.

### operator-

```cpp
CppType operator-(const CppType &vec) noexcept
```

Overloaded unary negation operator, returns the negated vector.


---
# shz::version

Source: https://sh4zam.com/api/cpp/version/

Class representing a full SH4ZAM API version.

- **Header:** `#include <sh4zam/shz_version.hpp>` ([source](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_version.hpp#L21))

## Static functions

### compiled

```cpp
static constexpr version compiled() noexcept
```

Compile-time version of SH4ZAM headers which are being included.

### linked

```cpp
static version linked() noexcept
```

Link-time version of SH4ZAM library which was linked against.

Calls: [`shz_version_linked()`](https://sh4zam.com/api/version/shz_version_linked/)

## Members

### value_

```cpp
shz_version_t value_
```

Private packed value member.

### version

```cpp
version(shz_version_t value) noexcept
version(uint8_t major, uint16_t minor, uint8_t patch) noexcept
```

Constructs a version from the given full value.

### operator shz_version_t

```cpp
operator shz_version_t() const noexcept
```

Implicit conversion operator to make this class automatically comparable to a `uint32_t`.

### operator=

```cpp
version operator=(uint32_t rhs) noexcept
```

Assignment operator for assigning a version to a full version ID value.

### major

```cpp
uint8_t major() const noexcept
```

Extracts the major component value from a full version.

### minor

```cpp
uint16_t minor() const noexcept
```

Extracts the minor component value from a full version.

### patch

```cpp
uint8_t patch() const noexcept
```

Extracts the patch component value from a full version.


---
# shz::xmtrx

Source: https://sh4zam.com/api/cpp/xmtrx/

Static structure around the 4x4 XMTRX FP register back-bank.

This structure provides the C++ bindings to the XMTRX API as a series of static member functions wrapping the C API.

- **Header:** `#include <sh4zam/shz_xmtrx.hpp>` ([source](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.hpp#L34))

## Static functions

### read

```cpp
static float read(reg xf) noexcept
```

C++ wrapper around `shz_xmtrx_read()`.

Calls: [`shz_xmtrx_read()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_read/), [`shz_xmtrx_reg()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_reg/)

### write

```cpp
static void write(reg xf, float value) noexcept
```

C++ wrapper around `shz_xmtrx_write()`.

Calls: [`shz_xmtrx_write()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_write/), [`shz_xmtrx_reg()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_reg/)

### read_row

```cpp
static vec4 read_row(unsigned int index) noexcept
```

C++ wrapper around `shz_xmtrx_read_row()`.

Calls: [`shz_xmtrx_read_row()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_read_row/)

### read_col

```cpp
static vec4 read_col(unsigned int index) noexcept
```

C++ wrapper around `shz_xmtrx_read_col()`.

Calls: [`shz_xmtrx_read_col()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_read_col/)

### write_row

```cpp
static void write_row(unsigned int index, const vec4 &vector) noexcept
```

C++ wrapper around `shz_xmtrx_write_row()`.

Calls: [`shz_xmtrx_write_row()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_write_row/)

### write_col

```cpp
static void write_col(unsigned int index, const vec4 &vector) noexcept
```

C++ wrapper around `shz_xmtrx_write_col()`.

Calls: [`shz_xmtrx_write_col()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_write_col/)

### swap_rows

```cpp
static void swap_rows(unsigned int index1, unsigned int index2) noexcept
```

C++ wrapper around `shz_xmtrx_swap_rows()`.

Calls: [`shz_xmtrx_swap_rows()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_swap_rows/)

### swap_cols

```cpp
static void swap_cols(unsigned int index1, unsigned int index2) noexcept
```

C++ wrapper around `shz_xmtrx_swap_cols()`.

Calls: [`shz_xmtrx_swap_cols()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_swap_cols/)

### load

```cpp
static void load(const shz_mat4x4_t &mat4) noexcept
static void load(const float cArray[16]) noexcept
static void load(const std::array< float, 16 > &array) noexcept
static void load(const shz_mat3x4_t &mat) noexcept
static void load(const shz_mat2x2_t &mat) noexcept
static void load(const shz_mat3x3_t &mat) noexcept
```

C++ wrapper around `shz_xmtrx_load_4x4()`.

Calls: [`shz_xmtrx_load_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_4x4/), [`shz_xmtrx_load_unaligned_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_unaligned_4x4/), [`shz_xmtrx_load_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x4/), [`shz_xmtrx_load_2x2()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_2x2/), [`shz_xmtrx_load_3x3()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x3/)

### load_transpose

```cpp
static void load_transpose(const shz_mat4x4_t &mat4) noexcept
static void load_transpose(const float cArray[16]) noexcept
static void load_transpose(const std::array< float, 16 > &array) noexcept
static void load_transpose(const shz_mat3x4_t &mat) noexcept
static void load_transpose(const shz_mat3x3_t &mat) noexcept
```

C++ wrapper around `shz_xmtrx_load_transpose_4x4()`.

Calls: [`shz_xmtrx_load_transpose_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_4x4/), [`shz_xmtrx_load_transpose_unaligned_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_unaligned_4x4/), [`shz_xmtrx_load_transpose_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_3x4/), [`shz_xmtrx_load_transpose_3x3()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_3x3/)

### load_wxyz

```cpp
static void load_wxyz(const shz_mat4x4_t &mat4) noexcept
```

C++ wrapper around `shz_xmtrx_load_wxyz_4x4()`.

Calls: [`shz_xmtrx_load_wxyz_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_wxyz_4x4/)

### load_cols

```cpp
static void load_cols(const shz_vec4_t &c1, const shz_vec4_t &c2, const shz_vec4_t &c3, const shz_vec4_t &c4) noexcept
static void load_cols(const shz_vec3_t &c1, const shz_vec3_t &c2, const shz_vec3_t &c3, const shz_vec3_t &c4) noexcept
```

C++ wrapper around `shz_xmtrx_load_cols_4x4()`.

Calls: [`shz_xmtrx_load_cols_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_cols_4x4/), [`shz_xmtrx_load_cols_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_cols_3x4/)

### load_rows

```cpp
static void load_rows(const shz_vec4_t &r1, const shz_vec4_t &r2, const shz_vec4_t &r3, const shz_vec4_t &r4) noexcept
static void load_rows(const shz_vec4_t &r1, const shz_vec4_t &r2, const shz_vec4_t &r3) noexcept
```

C++ wrapper around `shz_xmtrx_load_rows_4x4()`.

Calls: [`shz_xmtrx_load_rows_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_rows_4x4/), [`shz_xmtrx_load_rows_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_rows_3x4/)

### store

```cpp
static void store(shz_mat4x4_t *mat) noexcept
static void store(float cArray[16]) noexcept
static void store(shz_mat3x4_t *mat) noexcept
static void store(std::array< float, 16 > *array) noexcept
static void store(shz_mat2x2_t *mat) noexcept
static void store(shz_mat3x3_t *mat) noexcept
```

C++ wrapper around `shz_xmtrx_store_4x4()`.

Calls: [`shz_xmtrx_store_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_4x4/), [`shz_xmtrx_store_unaligned_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_unaligned_4x4/), [`shz_xmtrx_store_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_3x4/), [`shz_xmtrx_store_2x2()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_2x2/), [`shz_xmtrx_store_3x3()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_3x3/)

### store_transpose

```cpp
static void store_transpose(shz_mat4x4_t *mat) noexcept
static void store_transpose(float cArray[16]) noexcept
static void store_transpose(std::array< float, 16 > *array) noexcept
static void store_transpose(shz_mat3x4_t *mat) noexcept
static void store_transpose(shz_mat3x3_t *mat) noexcept
```

C++ wrapper around `shz_xmtrx_store_transpose_4x4()`.

Calls: [`shz_xmtrx_store_transpose_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_4x4/), [`shz_xmtrx_store_transpose_unaligned_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_unaligned_4x4/), [`shz_xmtrx_store_transpose_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_3x4/), [`shz_xmtrx_store_transpose_3x3()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_3x3/)

### init_identity

```cpp
static void init_identity() noexcept
```

C++ wrapper around `shz_xmtrx_init_identity()`.

Calls: [`shz_xmtrx_init_identity()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_identity/)

### init_identity_safe

```cpp
static void init_identity_safe() noexcept
```

C++ wrapper around `shz_xmtrx_init_identity_safe()`.

Calls: [`shz_xmtrx_init_identity()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_identity/)

### init_zero

```cpp
static void init_zero() noexcept
```

C++ wrapper around `shz_xmtrx_init_zero()`.

Calls: [`shz_xmtrx_init_zero()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_zero/)

### init_one

```cpp
static void init_one() noexcept
```

C++ wrapper around `shz_xmtrx_init_one()`.

Calls: [`shz_xmtrx_init_one()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_one/)

### init_fill

```cpp
static void init_fill(float value) noexcept
```

C++ wrapper around `shz_xmtrx_init_fill()`.

Calls: [`shz_xmtrx_init_fill()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_fill/)

### init_translation

```cpp
static void init_translation(float x, float y, float z) noexcept
static void init_translation(const vec3 &v) noexcept
```

C++ wrapper around `shz_xmtrx_init_translation()`.

Calls: [`shz_xmtrx_init_translation()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_translation/)

### init_scale

```cpp
static void init_scale(float x, float y, float z) noexcept
static void init_scale(const vec3 &v) noexcept
```

C++ wrapper around `shz_xmtrx_init_scale()`.

Calls: [`shz_xmtrx_init_scale()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_scale/)

### init_rotation_x

```cpp
static void init_rotation_x(float x) noexcept
```

C++ wrapper around `shz_xmtrx_init_rotation_x()`.

Calls: [`shz_xmtrx_init_rotation_x()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_x/)

### init_rotation_y

```cpp
static void init_rotation_y(float y) noexcept
```

C++ wrapper around `shz_xmtrx_init_rotation_y()`.

Calls: [`shz_xmtrx_init_rotation_y()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_y/)

### init_rotation_z

```cpp
static void init_rotation_z(float z) noexcept
```

C++ wrapper around `shz_xmtrx_init_rotation_z()`.

Calls: [`shz_xmtrx_init_rotation_z()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_z/)

### init_rotation_xyz

```cpp
static void init_rotation_xyz(float x, float y, float z) noexcept
```

C++ wrapper around `shz_xmtrx_init_rotation_xyz()`.

Calls: [`shz_xmtrx_init_rotation_xyz()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_xyz/)

### init_rotation_zyx

```cpp
static void init_rotation_zyx(float z, float y, float x) noexcept
```

C++ wrapper around `shz_xmtrx_init_rotation_zyx()`.

Calls: [`shz_xmtrx_init_rotation_zyx()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_zyx/)

### init_rotation_zxy

```cpp
static void init_rotation_zxy(float z, float x, float y) noexcept
```

C++ wrapper around `shz_xmtrx_init_rotation_zxy()`.

Calls: [`shz_xmtrx_init_rotation_zxy()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_zxy/)

### init_rotation_yxz

```cpp
static void init_rotation_yxz(float y, float x, float z) noexcept
```

C++ wrapper around `shz_xmtrx_init_rotation_yxz()`.

Calls: [`shz_xmtrx_init_rotation_yxz()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_yxz/)

### init_rotation

```cpp
static void init_rotation(float angle, float x, float y, float z) noexcept
static void init_rotation(float angle, const vec3 &axis) noexcept
```

C++ wrapper around `shz_xmtrx_init_rotation()`.

Calls: [`shz_xmtrx_init_rotation()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation/)

### init_rotation_dir

```cpp
static void init_rotation_dir(float angle, const vec3 &dir) noexcept
```

C++ wrapper around `shz_xmtrx_init_rotation_dir()`.

Calls: [`shz_xmtrx_init_rotation_dir()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_dir/)

### init_diagonal

```cpp
static void init_diagonal(float x, float y, float z, float w) noexcept
static void init_diagonal(const vec4 &v) noexcept
```

C++ wrapper around `shz_xmtrx_init_diagonal()`.

Calls: [`shz_xmtrx_init_diagonal()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_diagonal/)

### init_upper_triangular

```cpp
static void init_upper_triangular(float col1, const vec2 &col2, const vec3 &col3, const vec4 &col4) noexcept
```

C++ wrapper around `shz_xmtrx_init_upper_triangular()`.

Calls: [`shz_xmtrx_init_upper_triangular()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_upper_triangular/)

### init_lower_triangular

```cpp
static void init_lower_triangular(const vec4 &col1, const vec3 &col2, const vec2 &col3, float col4) noexcept
```

C++ wrapper around `shz_xmtrx_init_lower_triangular()`.

Calls: [`shz_xmtrx_init_lower_triangular()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_lower_triangular/)

### init_symmetric_skew

```cpp
static void init_symmetric_skew(float x, float y, float z) noexcept
```

C++ wrapper around `shz_xmtrx_init_symmetric_skew()`.

Calls: [`shz_xmtrx_init_symmetric_skew()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_symmetric_skew/)

### init_outer_product

```cpp
static void init_outer_product(const vec4 &a, const vec4 &b) noexcept
```

C++ wrapper around `shz_xmtrx_init_outer_product()`.

Calls: [`shz_xmtrx_init_outer_product()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_outer_product/)

### init_screen

```cpp
static void init_screen(float width, float height) noexcept
```

C++ wrapper around `shz_xmtrx_init_screen()`.

Calls: [`shz_xmtrx_init_screen()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_screen/)

### init_lookat

```cpp
static void init_lookat(const vec3 &eye, const vec3 &center, const vec3 &up) noexcept
```

C++ wrapper around `shz_xmtrx_init_lookat()`.

Calls: [`shz_xmtrx_init_lookat()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_lookat/)

### init_ortho

```cpp
static void init_ortho(float left, float right, float bottom, float top, float znear, float zfar) noexcept
```

C++ wrapper around `shz_xmtrx_init_ortho()`.

Calls: [`shz_xmtrx_init_ortho()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_ortho/)

### init_frustum

```cpp
static void init_frustum(float left, float right, float bottom, float top, float znear, float zfar) noexcept
```

C++ wrapper around `shz_xmtrx_init_frustum()`.

Calls: [`shz_xmtrx_init_frustum()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_frustum/)

### init_perspective

```cpp
static void init_perspective(float fov, float aspect, float znear) noexcept
```

C++ wrapper around `shz_xmtrx_init_perspective()`.

Calls: [`shz_xmtrx_init_perspective()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_perspective/)

### init_rotation_quat

```cpp
static void init_rotation_quat(const quat &q) noexcept
```

C++ wrapper around `shz_xmtrx_init_rotation_quat()`.

Calls: [`shz_xmtrx_init_rotation_quat()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_quat/)

### init_permutation_wxyz

```cpp
static void init_permutation_wxyz() noexcept
```

C++ wrapper around `shz_xmtrx_init_permutation_wxyz()`.

Calls: [`shz_xmtrx_init_permutation_wxyz()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_permutation_wxyz/)

### init_permutation_yzwx

```cpp
static void init_permutation_yzwx() noexcept
```

C++ wrapper around `shz_xmtrx_init_permutation_yzwx()`.

Calls: [`shz_xmtrx_init_permutation_yzwx()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_permutation_yzwx/)

### init_permutation_wzyx

```cpp
static void init_permutation_wzyx() noexcept
```

C++ wrapper around `shz_xmtrx_init_permutation_wzyx()`.

Calls: [`shz_xmtrx_init_permutation_wzyx()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_permutation_wzyx/)

### apply

```cpp
static void apply(const shz_mat4x4_t &mat4) noexcept
static void apply(const float cArray[16]) noexcept
static void apply(const std::array< float, 16 > &array) noexcept
static void apply(const shz_mat3x4_t &mat) noexcept
static void apply(const shz_mat3x3_t &mat) noexcept
```

C++ wrapper around `shz_xmtrx_apply_4x4()`.

Calls: [`shz_xmtrx_apply_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_4x4/), [`shz_xmtrx_apply_unaligned_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_unaligned_4x4/), [`shz_xmtrx_apply_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x4/), [`shz_xmtrx_apply_3x3()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x3/)

### apply_transpose

```cpp
static void apply_transpose(const shz_mat4x4_t &mat4) noexcept
static void apply_transpose(const float cArray[16]) noexcept
static void apply_transpose(const std::array< float, 16 > &array) noexcept
static void apply_transpose(const shz_mat3x4_t &mat) noexcept
static void apply_transpose(const shz_mat3x3_t &mat) noexcept
```

C++ wrapper around `shz_xmtrx_apply_transpose_4x4()`.

Calls: [`shz_xmtrx_apply_transpose_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_4x4/), [`shz_xmtrx_apply_transpose_unaligned_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_unaligned_4x4/), [`shz_xmtrx_apply_transpose_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_3x4/), [`shz_xmtrx_apply_transpose_3x3()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_3x3/)

### apply_reverse

```cpp
static void apply_reverse(const shz_mat4x4_t &mat4) noexcept
static void apply_reverse(const float cArray[16]) noexcept
static void apply_reverse(const std::array< float, 16 > &array) noexcept
static void apply_reverse(const shz_mat3x4_t &mat) noexcept
```

C++ wrapper around `shz_xmtrx_apply_reverse_4x4()`.

Calls: [`shz_xmtrx_apply_reverse_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_4x4/), [`shz_xmtrx_apply_reverse_unaligned_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_unaligned_4x4/), [`shz_xmtrx_apply_reverse_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_3x4/)

### apply_reverse_transpose

```cpp
static void apply_reverse_transpose(const shz_mat4x4_t &mat4) noexcept
static void apply_reverse_transpose(const float cArray[16]) noexcept
static void apply_reverse_transpose(const std::array< float, 16 > &array) noexcept
static void apply_reverse_transpose(const shz_mat3x4_t &mat) noexcept
```

C++ wrapper around `shz_xmtrx_apply_reverse_transpose_4x4()`.

Calls: [`shz_xmtrx_apply_reverse_transpose_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_transpose_4x4/), [`shz_xmtrx_apply_reverse_transpose_unaligned_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_transpose_unaligned_4x4/), [`shz_xmtrx_apply_reverse_transpose_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_transpose_3x4/)

### apply_translation

```cpp
static void apply_translation(float x, float y, float z) noexcept
static void apply_translation(const vec3 &v) noexcept
```

C++ wrapper around `shz_xmtrx_apply_translation()`.

Calls: [`shz_xmtrx_apply_translation()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_translation/)

### apply_scale

```cpp
static void apply_scale(float x, float y, float z) noexcept
static void apply_scale(const vec3 &v) noexcept
```

C++ wrapper around `shz_xmtrx_apply_scale()`.

Calls: [`shz_xmtrx_apply_scale()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_scale/)

### apply_rotation_x

```cpp
static void apply_rotation_x(float x) noexcept
```

C++ wrapper around `shz_xmtrx_apply_rotation_x()`.

Calls: [`shz_xmtrx_apply_rotation_x()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_x/)

### apply_rotation_y

```cpp
static void apply_rotation_y(float y) noexcept
```

C++ wrapper around `shz_xmtrx_apply_rotation_y()`.

Calls: [`shz_xmtrx_apply_rotation_y()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_y/)

### apply_rotation_z

```cpp
static void apply_rotation_z(float z) noexcept
```

C++ wrapper around `shz_xmtrx_apply_rotation_z()`.

Calls: [`shz_xmtrx_apply_rotation_z()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_z/)

### apply_rotation_xyz

```cpp
static void apply_rotation_xyz(float x, float y, float z) noexcept
```

C++ wrapper around `shz_xmtrx_init_rotation_xyz()`.

Calls: [`shz_xmtrx_apply_rotation_xyz()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_xyz/)

### apply_rotation_zyx

```cpp
static void apply_rotation_zyx(float z, float y, float x) noexcept
```

C++ wrapper around `shz_xmtrx_apply_rotation_zyx()`.

Calls: [`shz_xmtrx_apply_rotation_zyx()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_zyx/)

### apply_rotation_zxy

```cpp
static void apply_rotation_zxy(float z, float x, float y) noexcept
```

C++ wrapper around `shz_xmtrx_apply_rotation_zxy()`.

Calls: [`shz_xmtrx_apply_rotation_zxy()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_zxy/)

### apply_rotation_yxz

```cpp
static void apply_rotation_yxz(float y, float x, float z) noexcept
```

C++ wrapper around `shz_xmtrx_apply_rotation_yxz()`.

Calls: [`shz_xmtrx_apply_rotation_yxz()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_yxz/)

### apply_rotation

```cpp
static void apply_rotation(float angle, float x, float y, float z) noexcept
static void apply_rotation(float angle, const vec3 &axis) noexcept
```

Calls: [`shz_xmtrx_apply_rotation()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation/)

### apply_rotation_quat

```cpp
static void apply_rotation_quat(const quat &q) noexcept
```

C++ wrapper around `shz_xmtrx_apply_rotation_quat()`.

Calls: [`shz_xmtrx_apply_rotation_quat()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_quat/)

### apply_lookat

```cpp
static void apply_lookat(const vec3 &eye, const vec3 &center, const vec3 &up) noexcept
```

C++ wrapper around `shz_xmtrx_apply_lookat()`.

Calls: [`shz_xmtrx_apply_lookat()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_lookat/)

### apply_ortho

```cpp
static void apply_ortho(float left, float right, float bottom, float top, float znear, float zfar) noexcept
```

C++ wrapper around `shz_xmtrx_apply_ortho()`.

Calls: [`shz_xmtrx_apply_ortho()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_ortho/)

### apply_frustum

```cpp
static void apply_frustum(float left, float right, float bottom, float top, float znear, float zfar) noexcept
```

C++ wrapper around `shz_xmtrx_apply_frustum()`.

Calls: [`shz_xmtrx_apply_frustum()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_frustum/)

### apply_perspective

```cpp
static void apply_perspective(float fov, float aspect, float znear) noexcept
```

C++ wrapper around `shz_xmtrx_apply_perspective()`.

Calls: [`shz_xmtrx_apply_perspective()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_perspective/)

### apply_symmetric_skew

```cpp
static void apply_symmetric_skew(float x, float y, float z) noexcept
```

C++ wrapper around `shz_xmtrx_apply_symmetric_skew()`.

Calls: [`shz_xmtrx_apply_symmetric_skew()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_symmetric_skew/)

### apply_screen

```cpp
static void apply_screen(float width, float height) noexcept
```

C++ wrapper around `shz_xmtrx_apply_screen()`.

Calls: [`shz_xmtrx_apply_screen()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_screen/)

### apply_permutation_wxyz

```cpp
static void apply_permutation_wxyz() noexcept
```

C++ wrapper around `shz_xmtrx_apply_permutation_wxyz()`.

Calls: [`shz_xmtrx_apply_permutation_wxyz()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_permutation_wxyz/)

### apply_permutation_yzwx

```cpp
static void apply_permutation_yzwx() noexcept
```

C++ wrapper around `shz_xmtrx_apply_permutation_yzwx()`.

Calls: [`shz_xmtrx_apply_permutation_yzwx()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_permutation_yzwx/)

### apply_permutation_wzyx

```cpp
static void apply_permutation_wzyx() noexcept
```

C++ wrapper around `shz_xmtrx_apply_permutation_wzyx()`.

Calls: [`shz_xmtrx_apply_permutation_wzyx()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_permutation_wzyx/)

### apply_self

```cpp
static void apply_self() noexcept
```

C++ wrapper around `shz_xmtrx_apply_self()`.

Calls: [`shz_xmtrx_apply_self()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_self/)

### translate

```cpp
static void translate(float x, float y, float z) noexcept
static void translate(vec3 v) noexcept
```

C++ wrapper around `shz_xmtrx_translate()`.

Calls: [`shz_xmtrx_translate()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_translate/)

### scale

```cpp
static void scale(float x, float y, float z) noexcept
static void scale(vec3 v) noexcept
```

C++ wrapper around `shz_xmtrx_scale()`.

Calls: [`shz_xmtrx_scale()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_scale/)

### rotate_x

```cpp
static void rotate_x(float radians) noexcept
```

C++ wrapper around `shz_xmtrx_rotate_x()`.

Calls: [`shz_xmtrx_rotate_x()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_x/)

### rotate_y

```cpp
static void rotate_y(float radians) noexcept
```

C++ wrapper around `shz_xmtrx_rotate_x()`.

Calls: [`shz_xmtrx_rotate_y()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_y/)

### rotate_z

```cpp
static void rotate_z(float radians) noexcept
```

C++ wrapper around `shz_xmtrx_rotate_x()`.

Calls: [`shz_xmtrx_rotate_z()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_z/)

### rotate_xyz

```cpp
static void rotate_xyz(float x, float y, float z) noexcept
```

C++ wrapper around `shz_xmtrx_rotate_xyz()`.

Calls: [`shz_xmtrx_rotate_xyz()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_xyz/)

### rotate_zyx

```cpp
static void rotate_zyx(float z, float y, float x) noexcept
```

C++ wrapper around `shz_xmtrx_rotate_zyx()`.

Calls: [`shz_xmtrx_rotate_zyx()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_zyx/)

### rotate_zxy

```cpp
static void rotate_zxy(float z, float x, float y) noexcept
```

C++ wrapper around `shz_xmtrx_rotate_zxy()`.

Calls: [`shz_xmtrx_rotate_zxy()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_zxy/)

### rotate_yxz

```cpp
static void rotate_yxz(float y, float x, float z) noexcept
```

C++ wrapper around `shz_xmtrx_rotate_yxz()`.

Calls: [`shz_xmtrx_rotate_yxz()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_yxz/)

### rotate

```cpp
static void rotate(float radians, float x, float y, float z) noexcept
static void rotate(float radians, const vec3 &axis) noexcept
```

C++ wrapper around `shz_xmtrx_rotate()`.

Calls: [`shz_xmtrx_rotate()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate/)

### translate_reverse

```cpp
static void translate_reverse(float x, float y, float z) noexcept
static void translate_reverse(const shz::vec3 &pos) noexcept
```

Pre-multiplies and accumulates XMTRX onto the 3D translation matrix with the given components.

Calls: [`shz_xmtrx_translate_reverse()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_translate_reverse/)

### scale_reverse

```cpp
static void scale_reverse(float x, float y, float z) noexcept
static void scale_reverse(const shz::vec3 &size) noexcept
```

Pre-multiplies and accumulatse XMTRX onto the 3D scaling matrix with the given components.

Calls: [`shz_xmtrx_scale_reverse()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_scale_reverse/)

### load_apply

```cpp
static void load_apply(const shz_mat4x4_t &mat1, const shz_mat4x4_t &mat2) noexcept
static void load_apply(const float matrix1[16], const float matrix2[16]) noexcept
static void load_apply(const shz_mat3x4_t &mat1, const shz_mat3x4_t &mat2) noexcept
```

C++ wrapper around `shz_xmtrx_load_apply_4x4()`.

Calls: [`shz_xmtrx_load_apply_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_4x4/), [`shz_xmtrx_load_apply_unaligned_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_unaligned_4x4/), [`shz_xmtrx_load_apply_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_3x4/)

### apply_store

```cpp
static void apply_store(shz_mat4x4_t *out, const shz_mat4x4_t &in) noexcept
static void apply_store(float out[16], const float in[16]) noexcept
```

C++ wrapper around `shz_xmtrx_apply_store_4x4()`.

Calls: [`shz_xmtrx_apply_store_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_store_4x4/), [`shz_xmtrx_apply_store_unaligned_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_store_unaligned_4x4/)

### load_apply_store

```cpp
static void load_apply_store(shz_mat4x4_t *dst, const shz_mat4x4_t &mat1, const shz_mat4x4_t &mat2) noexcept
static void load_apply_store(float out[16], const float matrix1[16], const float matrix2[16]) noexcept
static void load_apply_store(shz_mat3x4_t *dst, const shz_mat3x4_t &mat1, const shz_mat3x4_t &mat2) noexcept
static void load_apply_store(shz_mat3x3_t *dst, const shz_mat3x3_t &mat1, const shz_mat3x3_t &mat2) noexcept
```

C++ wrapper around `shz_xmtrx_load_apply_store_4x4()`.

Calls: [`shz_xmtrx_load_apply_store_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_4x4/), [`shz_xmtrx_load_apply_store_unaligned_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_unaligned_4x4/), [`shz_xmtrx_load_apply_store_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_3x4/), [`shz_xmtrx_load_apply_store_3x3()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_3x3/)

### transform

```cpp
static vec4 transform(const vec4 &in) noexcept
static vec3 transform(const vec3 &in) noexcept
static vec2 transform(const vec2 &in) noexcept
```

C++ wrapper around `shz_xmtrx_transform_vec4()`.

Calls: [`shz_xmtrx_transform_vec4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec4/), [`shz_xmtrx_transform_vec3()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec3/), [`shz_xmtrx_transform_vec2()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec2/)

### transform_point

```cpp
static vec3 transform_point(const vec3 &pt) noexcept
static vec2 transform_point(const vec2 &pt) noexcept
```

C++ wrapper around `shz_xmtrx_transform_point3()`.

Calls: [`shz_xmtrx_transform_point3()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_point3/), [`shz_xmtrx_transform_point2()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_point2/)

### set_translation

```cpp
static void set_translation(float x, float y, float z) noexcept
static void set_translation(const vec3 &v) noexcept
```

C++ wrapper around `shz_xmtrx_set_translation()`.

Calls: [`shz_xmtrx_set_translation()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_set_translation/)

### set_scale

```cpp
static void set_scale(float x, float y, float z) noexcept
static void set_scale(const shz::vec3 &size) noexcept
```

Sets only the inner 3x3 submatrix to be a 3D scale matrix with the given components.

Calls: [`shz_xmtrx_set_scale()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_set_scale/)

### get_translation

```cpp
static vec3 get_translation() noexcept
```

C++ wrapper around `shz_xmtrx_set_translation()`.

Calls: [`shz_xmtrx_get_translation()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_get_translation/)

### get_scale

```cpp
static vec3 get_scale() noexcept
```

Returns the scaling components from the inner 3x3 matrix of XMTRX, as a 3D vector.

Calls: [`shz_xmtrx_get_scale()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_get_scale/)

### add

```cpp
static void add(const shz_mat4x4_t &mat) noexcept
```

C++ wrapper around `shz_xmtrx_add_4x4()`.

Calls: [`shz_xmtrx_add_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_add_4x4/)

### sub

```cpp
static void sub(const shz_mat4x4_t &mat) noexcept
```

C++ wrapper around `shz_xmtrx_sub_4x4()`.

Calls: [`shz_xmtrx_sub_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_sub_4x4/)

### transpose

```cpp
static void transpose() noexcept
```

C++ wrapper around `shz_xmtrx_transpose()`.

Calls: [`shz_xmtrx_transpose()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transpose/)

### negate

```cpp
static void negate() noexcept
```

C++ wrapper around `shz_xmtrx_negate()`.

Calls: [`shz_xmtrx_negate()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_negate/)

### abs

```cpp
static void abs() noexcept
```

C++ wrapper around `shz_xmtrx_abs()`.

Calls: [`shz_xmtrx_abs()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_abs/)

### to_quat

```cpp
static quat to_quat() noexcept
```

C++ wrapper around `shz_xmtrx_to_quat()`.

Calls: [`shz_xmtrx_to_quat()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_to_quat/)

### determinant

```cpp
static float determinant() noexcept
```

C++ wrapper around `shz_xmtrx_determinant()`.

Calls: [`shz_xmtrx_determinant()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_determinant/)

### invert

```cpp
static void invert() noexcept
```

C++ wrapper around `shz_xmtrx_invert()`.

Calls: [`shz_xmtrx_invert()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_invert/)

### blend

```cpp
static void blend(const shz_mat4x4_t &matrix, float weight) noexcept
static void blend(const shz_mat3x4_t &matrix, float weight) noexcept
```

Adds and accumulates a scaled 4x4 matrix onto XMTRX.

Calls: [`shz_xmtrx_blend_4x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_blend_4x4/), [`shz_xmtrx_blend_3x4()`](https://sh4zam.com/api/xmtrx/shz_xmtrx_blend_3x4/)

## Members

### reg

```cpp

```

FP back-bank registers comprising XMTRX.

### reg_t

```cpp
using reg_t = reg
```

Non-POSIX style `reg_t` alias.


---
# Matrix API

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

> In-memory matrix manipulation for 4x4 and smaller matrices

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

- **C header:** `#include <sh4zam/shz_matrix.h>`
- **C++ header:** `#include <sh4zam/shz_matrix.hpp>`
- **C++ types:** [`shz::mat4x4`](https://sh4zam.com/api/cpp/mat4x4/)
- **Symbols:** 120

## Verb model

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

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

## Suffixes

Suffixes used in this module. The full list is in [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/).

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

## Initialization

Routines for fully initializing a matrix.

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

## Decomposition

Routines for decomposing a matrix into its constituent transforms.

| Symbol | Description |
| --- | --- |
| [`shz_mat4x4_decompose`](https://sh4zam.com/api/matrix/shz_mat4x4_decompose/) | Decomposes a 4x4 transform matrix into translation, rotation, and scale. |

## Getting

Routines for getting specific values within a matrix.

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

## Setting

Routines for setting specific values within a matrix

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

## Applying

Routines for multiplying and accumulating onto the given matrix.

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

## GL Transformations

OpenGL-style 4x4 matrix transforms.

| Symbol | Description |
| --- | --- |
| [`shz_mat4x4_translate`](https://sh4zam.com/api/matrix/shz_mat4x4_translate/) | Multiplies and accumulates `mat` by a 3D translation matrix with the given components. |
| [`shz_mat4x4_scale`](https://sh4zam.com/api/matrix/shz_mat4x4_scale/) | Multiplies and accumulates `mat` by a 3D scaling matrix with the given components. |
| [`shz_mat4x4_rotate_x`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_x/) | Multiplies and accumulates `mat` by a 3D rotation matrix about the X axis. |
| [`shz_mat4x4_rotate_y`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_y/) | Multiplies and accumulates `mat` by a 3D rotation matrix about the Y axis. |
| [`shz_mat4x4_rotate_z`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_z/) | Multiplies and accumulates `mat` by a 3D rotation matrix about the Z axis. |
| [`shz_mat4x4_rotate_xyz`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_xyz/) | Multiplies and accumulates `mat` by 3D rotation matrices about the X then Y then Z axes. |
| [`shz_mat4x4_rotate_zyx`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_zyx/) | Multiplies and accumulates `mat` by 3D rotation matrices about the Z then Y then X axes. |
| [`shz_mat4x4_rotate_zxy`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_zxy/) | Multiplies and accumulates `mat` by 3D rotation matrices about the Z then X then Y axes. |
| [`shz_mat4x4_rotate_yxz`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_yxz/) | Multiplies and accumulates `mat` by 3D rotation matrices about the Y then X then Z axes. |
| [`shz_mat4x4_rotate`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate/) | Multiplies and accumulates `mat` by the 3D rotation matrix formed by the given axis and angle. |

## Reverse GL Transformations

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

| Symbol | Description |
| --- | --- |
| [`shz_mat4x4_translate_reverse`](https://sh4zam.com/api/matrix/shz_mat4x4_translate_reverse/) | Pre-multiplies and accumulates the given matrix onto the 3D translation matrix with the given components. |
| [`shz_mat4x4_scale_reverse`](https://sh4zam.com/api/matrix/shz_mat4x4_scale_reverse/) | Pre-multiplies and accumulates the given matrix onto the 3D scaling matrix with the given components. |

## Transforming

Routines for transforming vectors and points by a matrix.

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

## Miscellaneous

Other matrix-related operations and routines

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

## Types

| Symbol | Description |
| --- | --- |
| [`shz_mat4x4_t`](https://sh4zam.com/api/matrix/shz_mat4x4_t/) | Structure representing a 4x4 column-major matrix. |
| [`shz_mat4x4`](https://sh4zam.com/api/matrix/shz_mat4x4/) | Alternate [`shz_mat4x4_t`](https://sh4zam.com/api/matrix/shz_mat4x4_t/) C typedef for those who hate POSIX style. |
| [`shz_mat2x2_t`](https://sh4zam.com/api/matrix/shz_mat2x2_t/) | Structure representing a 2x2 column-major matrix. |
| [`shz_mat3x3_t`](https://sh4zam.com/api/matrix/shz_mat3x3_t/) | Structure representing a 3x3 column-major matrix. |
| [`shz_mat3x4_t`](https://sh4zam.com/api/matrix/shz_mat3x4_t/) | Structure representing a 3x4 column-major matrix. |
| [`shz_mat4x3_t`](https://sh4zam.com/api/matrix/shz_mat4x3_t/) | Structure representing a 4x3 column-major matrix. |

## Functions

| Symbol | Description |
| --- | --- |
| [`shz_mat3x3_transpose`](https://sh4zam.com/api/matrix/shz_mat3x3_transpose/) | Stores the transpose of 3x3 matrix `mat` within `out`. |
| [`shz_mat3x3_inverse_unscaled`](https://sh4zam.com/api/matrix/shz_mat3x3_inverse_unscaled/) | Computes the inverse of an orthonormal 3x3 matrix. |
| [`shz_mat3x3_inverse`](https://sh4zam.com/api/matrix/shz_mat3x3_inverse/) | Computes the inverse of a 3x3 matrix. |
| [`shz_mat3x3_scale`](https://sh4zam.com/api/matrix/shz_mat3x3_scale/) | Uniformly scales each element within a 3x3 matrix by the given value. |
| [`shz_mat3x3_transform_vec3`](https://sh4zam.com/api/matrix/shz_mat3x3_transform_vec3/) | Transforms an input vector by a 3x3 matrix, returning the resulting vector. |
| [`shz_mat3x3_transform_vec3_transpose`](https://sh4zam.com/api/matrix/shz_mat3x3_transform_vec3_transpose/) | Transforms an input vector by the transpose of a 3x3 matrix, returning the resulting vector. |


---
# shz_mat2x2_t

Source: https://sh4zam.com/api/matrix/shz_mat2x2_t/

```c
typedef SHZ_ALIGNAS(8) struct shz_mat2x2 {
    union {
        float       elem[4];
        float       elem2D[2][2];
        shz_vec2_t  col[2];
    };
} shz_mat2x2_t;
```

Structure representing a 2x2 column-major matrix.

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `elem` | `float[4]` |  |
| `elem2D` | `float[2][2]` |  |
| `col` | `shz_vec2_t[2]` |  |

## Warnings

- This structure MUST be aligned on 8-byte boundaries!

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_matrix.h:889`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L889)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Types"


---
# shz_mat3x3_inverse_unscaled

Source: https://sh4zam.com/api/matrix/shz_mat3x3_inverse_unscaled/

```c
SHZ_INLINE void shz_mat3x3_inverse_unscaled(const shz_mat3x3_t* mat, shz_mat3x3_t* out) SHZ_NOEXCEPT;
```

Computes the inverse of an orthonormal 3x3 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat3x3_t *` | Pointer to the 3x3 matrix to invert. |
| `out` | `shz_mat3x3_t *` | Pointer to the resulting inverted matrix. |

## Returns

Nothing (`void`).

## Notes

- The routine saves cycles by not scaling by the determinant, which is typically useful for normals and lighting, where the matrix has no scale factor.

## Warnings

- This routine clobbers XMTRX.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:959`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L959)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Functions"


---
# shz_mat3x3_inverse

Source: https://sh4zam.com/api/matrix/shz_mat3x3_inverse/

```c
SHZ_INLINE void shz_mat3x3_inverse(const shz_mat3x3_t* mat, shz_mat3x3_t* out) SHZ_NOEXCEPT;
```

Computes the inverse of a 3x3 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat3x3_t *` | Pointer to the 3x3 matrix to invert. |
| `out` | `shz_mat3x3_t *` | Pointer to the resulting inverted matrix. |

## Returns

Nothing (`void`).

## Notes

- Only valid for non-singular matrices.

## Warnings

- This routine clobbers XMTRX.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:970`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L970)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Functions"


---
# shz_mat3x3_scale

Source: https://sh4zam.com/api/matrix/shz_mat3x3_scale/

```c
SHZ_INLINE void shz_mat3x3_scale(shz_mat3x3_t* dst, const shz_mat3x3_t* src, float value) SHZ_NOEXCEPT;
```

Uniformly scales each element within a 3x3 matrix by the given value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `shz_mat3x3_t *` |  |
| `src` | `const shz_mat3x3_t *` |  |
| `value` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:973`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L973)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Functions"


---
# shz_mat3x3_t

Source: https://sh4zam.com/api/matrix/shz_mat3x3_t/

```c
typedef struct shz_mat3x3 {
    union {
        float      elem[9];
        float      elem2D[3][3];
        shz_vec3_t col[3];
        struct {
            shz_vec3_t left;
            shz_vec3_t up;
            shz_vec3_t forward;
        };
    };
} shz_mat3x3_t;
```

Structure representing a 3x3 column-major matrix.

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `elem` | `float[9]` |  |
| `elem2D` | `float[3][3]` |  |
| `col` | `shz_vec3_t[3]` |  |
| `left` | `shz_vec3_t` |  |
| `up` | `shz_vec3_t` |  |
| `forward` | `shz_vec3_t` |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_matrix.h:898`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L898)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Types"


---
# shz_mat3x3_transform_vec3_transpose

Source: https://sh4zam.com/api/matrix/shz_mat3x3_transform_vec3_transpose/

```c
SHZ_INLINE shz_vec3_t shz_mat3x3_transform_vec3_transpose(const shz_mat3x3_t* m, shz_vec3_t v) SHZ_NOEXCEPT;
```

Transforms an input vector by the transpose of a 3x3 matrix, returning the resulting vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `const shz_mat3x3_t *` |  |
| `v` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:979`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L979)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Functions"


---
# shz_mat3x3_transform_vec3

Source: https://sh4zam.com/api/matrix/shz_mat3x3_transform_vec3/

```c
SHZ_INLINE shz_vec3_t shz_mat3x3_transform_vec3(const shz_mat3x3_t* m, shz_vec3_t v) SHZ_NOEXCEPT;
```

Transforms an input vector by a 3x3 matrix, returning the resulting vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `const shz_mat3x3_t *` |  |
| `v` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:976`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L976)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Functions"


---
# shz_mat3x3_transpose

Source: https://sh4zam.com/api/matrix/shz_mat3x3_transpose/

> Stores the transpose of 3x3 matrix mat within out

```c
SHZ_INLINE void shz_mat3x3_transpose(const shz_mat3x3_t* mat, shz_mat3x3_t* out) SHZ_NOEXCEPT;
```

Stores the transpose of 3x3 matrix `mat` within `out`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat3x3_t *` | Pointer to the 3x3 matrix to transpose. |
| `out` | `shz_mat3x3_t *` | Pointer to the resulting transposed matrix. |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:947`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L947)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Functions"


---
# shz_mat3x4_t

Source: https://sh4zam.com/api/matrix/shz_mat3x4_t/

```c
typedef struct shz_mat3x4 {
    union {
        float      elem[12];
        float      elem2D[4][3];
        shz_vec3_t col[4];
        struct {
            shz_vec3_t left;
            shz_vec3_t up;
            shz_vec3_t forward;
            shz_vec3_t pos;
        };
    };
} shz_mat3x4_t;
```

Structure representing a 3x4 column-major matrix.

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `elem` | `float[12]` |  |
| `elem2D` | `float[4][3]` |  |
| `col` | `shz_vec3_t[4]` |  |
| `left` | `shz_vec3_t` |  |
| `up` | `shz_vec3_t` |  |
| `forward` | `shz_vec3_t` |  |
| `pos` | `shz_vec3_t` |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_matrix.h:912`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L912)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Types"


---
# shz_mat4x3_t

Source: https://sh4zam.com/api/matrix/shz_mat4x3_t/

```c
typedef struct shz_mat4x3 {
    union {
        float      elem[12];
        float      elem2D[3][4];
        shz_vec4_t col[3];
        struct {
            shz_vec4_t left;
            shz_vec4_t up;
            shz_vec4_t forward;
        };
    };
} shz_mat4x3_t;
```

Structure representing a 4x3 column-major matrix.

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `elem` | `float[12]` |  |
| `elem2D` | `float[3][4]` |  |
| `col` | `shz_vec4_t[3]` |  |
| `left` | `shz_vec4_t` |  |
| `up` | `shz_vec4_t` |  |
| `forward` | `shz_vec4_t` |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_matrix.h:927`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L927)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Types"


---
# shz_mat4x4_3x3_determinant

Source: https://sh4zam.com/api/matrix/shz_mat4x4_3x3_determinant/

```c
SHZ_INLINE float shz_mat4x4_3x3_determinant(const shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Returns the determinant of the given 4x4 matrix's internal top-level 3x3 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |

## Returns

`float`

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:339`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L339)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Getting"


---
# shz_mat4x4_3x3_inverse_unscaled

Source: https://sh4zam.com/api/matrix/shz_mat4x4_3x3_inverse_unscaled/

```c
SHZ_INLINE void shz_mat4x4_3x3_inverse_unscaled(const shz_mat4x4_t* mat4, shz_mat3x3_t* invmat3) SHZ_NOEXCEPT;
```

Extracts and inverts the top-level, unscaled 3x3 of the given 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat4` | `const shz_mat4x4_t *` |  |
| `invmat3` | `shz_mat3x3_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:333`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L333)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Getting"


---
# shz_mat4x4_3x3_inverse

Source: https://sh4zam.com/api/matrix/shz_mat4x4_3x3_inverse/

```c
SHZ_INLINE void shz_mat4x4_3x3_inverse(const shz_mat4x4_t* mat4, shz_mat3x3_t* invmat3) SHZ_NOEXCEPT;
```

Extracts and inverts the top-level 3x3 (which may be scaled) of the given 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat4` | `const shz_mat4x4_t *` |  |
| `invmat3` | `shz_mat3x3_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:336`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L336)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Getting"


---
# shz_mat4x4_3x3

Source: https://sh4zam.com/api/matrix/shz_mat4x4_3x3/

```c
SHZ_INLINE void shz_mat4x4_3x3(const shz_mat4x4_t* mat4, shz_mat3x3_t* mat3) SHZ_NOEXCEPT;
```

Extracts the top-left 3x3 of the given 4D matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat4` | `const shz_mat4x4_t *` |  |
| `mat3` | `shz_mat3x3_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:330`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L330)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Getting"


---
# shz_mat4x4_apply_frustum

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_frustum/

```c
SHZ_INLINE void shz_mat4x4_apply_frustum(shz_mat4x4_t* m, float left, float right, float bottom, float top, float znear, float zfar) SHZ_NOEXCEPT;
```

Multiplies and accumulates the frustum matrix constructed from the given values onto the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `shz_mat4x4_t *` |  |
| `left` | `float` |  |
| `right` | `float` |  |
| `bottom` | `float` |  |
| `top` | `float` |  |
| `znear` | `float` |  |
| `zfar` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_frustum`](https://sh4zam.com/api/cpp/mat4x4/#apply_frustum)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:495`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L495)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_lookat

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_lookat/

```c
SHZ_INLINE void shz_mat4x4_apply_lookat(shz_mat4x4_t* m, shz_vec3_t pos, shz_vec3_t target, shz_vec3_t up) SHZ_NOEXCEPT;
```

Applies the 3D "lookAt" matrix constructed with the given vector components onto the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `shz_mat4x4_t *` |  |
| `pos` | `shz_vec3_t` |  |
| `target` | `shz_vec3_t` |  |
| `up` | `shz_vec3_t` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_lookat`](https://sh4zam.com/api/cpp/mat4x4/#apply_lookat)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:483`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L483)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_ortho

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_ortho/

```c
SHZ_INLINE void shz_mat4x4_apply_ortho(shz_mat4x4_t* m, float left, float right, float bottom, float top, float znear, float zfar) SHZ_NOEXCEPT;
```

Multiplies and accumulates the ortho matrix constructed from the given values onto the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `shz_mat4x4_t *` |  |
| `left` | `float` |  |
| `right` | `float` |  |
| `bottom` | `float` |  |
| `top` | `float` |  |
| `znear` | `float` |  |
| `zfar` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_ortho`](https://sh4zam.com/api/cpp/mat4x4/#apply_ortho)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:489`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L489)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_permutation_wxyz

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_permutation_wxyz/

```c
SHZ_INLINE void shz_mat4x4_apply_permutation_wxyz(shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in WXYZ order.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_permutation_wxyz`](https://sh4zam.com/api/cpp/mat4x4/#apply_permutation_wxyz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:519`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L519)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_permutation_yzwx

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_permutation_yzwx/

```c
SHZ_INLINE void shz_mat4x4_apply_permutation_yzwx(shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in YZWX order.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_permutation_yzwx`](https://sh4zam.com/api/cpp/mat4x4/#apply_permutation_yzwx)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:525`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L525)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_perspective

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_perspective/

```c
SHZ_INLINE void shz_mat4x4_apply_perspective(shz_mat4x4_t* m, float fov, float aspect, float znear) SHZ_NOEXCEPT;
```

Multiplies and accumulates the perspective matrix constructed from the given values onto the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `shz_mat4x4_t *` |  |
| `fov` | `float` |  |
| `aspect` | `float` |  |
| `znear` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_perspective`](https://sh4zam.com/api/cpp/mat4x4/#apply_perspective)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:501`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L501)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_rotation_quat

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_quat/

```c
SHZ_INLINE void shz_mat4x4_apply_rotation_quat(shz_mat4x4_t* m, shz_quat_t q) SHZ_NOEXCEPT;
```

Multiplies and accumulates the given matrix with a rotation matrix whose orientation is given by a quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `shz_mat4x4_t *` |  |
| `q` | `shz_quat_t` |  |

## Returns

Nothing (`void`).

## Notes

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:477`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L477)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_rotation_x

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_x/

> Multiplies and accumulates a rotation matrix by xAngle radians about the X-axis onto the given matrix

```c
SHZ_INLINE void shz_mat4x4_apply_rotation_x(shz_mat4x4_t* mat, float xAngle) SHZ_NOEXCEPT;
```

Multiplies and accumulates a rotation matrix by `xAngle` radians about the X-axis onto the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `xAngle` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_rotation_x`](https://sh4zam.com/api/cpp/mat4x4/#apply_rotation_x)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:419`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L419)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_rotation_xyz

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_xyz/

```c
SHZ_INLINE void shz_mat4x4_apply_rotation_xyz(shz_mat4x4_t* mat, float xAngle, float yAngle, float zAngle) SHZ_NOEXCEPT;
```

Rotates the given transform matrix about the X axis, then the Y axis, then the Z axis by the given angles in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `xAngle` | `float` |  |
| `yAngle` | `float` |  |
| `zAngle` | `float` |  |

## Returns

Nothing (`void`).

## Details

Multiplies and accumulates the given matrix with the 3D rotation matrix formed from the intrinsic rotation created by the given Tait-Bryan X-Y-Z angles.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_rotation_xyz`](https://sh4zam.com/api/cpp/mat4x4/#apply_rotation_xyz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:439`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L439)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_rotation_y

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_y/

> Multiplies and accumulates a rotation matrix by yAngle radians about the Y-axis onto the given matrix

```c
SHZ_INLINE void shz_mat4x4_apply_rotation_y(shz_mat4x4_t* mat, float yAngle) SHZ_NOEXCEPT;
```

Multiplies and accumulates a rotation matrix by `yAngle` radians about the Y-axis onto the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `yAngle` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_rotation_y`](https://sh4zam.com/api/cpp/mat4x4/#apply_rotation_y)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:425`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L425)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_rotation_yxz

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_yxz/

```c
SHZ_INLINE void shz_mat4x4_apply_rotation_yxz(shz_mat4x4_t* mat, float yAngle, float xAngle, float zAngle) SHZ_NOEXCEPT;
```

Rotates the given transform matrix about the Y axis, then the X axis, then the Z axis by the given angles in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `yAngle` | `float` |  |
| `xAngle` | `float` |  |
| `zAngle` | `float` |  |

## Returns

Nothing (`void`).

## Details

Multiplies and accumulates the given matrix with the 3D rotation matrix formed from the intrinsic rotation created by the given Tait-Bryan Y-X-Z angles.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_rotation_yxz`](https://sh4zam.com/api/cpp/mat4x4/#apply_rotation_yxz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:463`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L463)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_rotation_z

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_z/

> Multiplies and accumulates a rotation matrix by zAngle radians about the Z-axis onto the given matrix

```c
SHZ_INLINE void shz_mat4x4_apply_rotation_z(shz_mat4x4_t* mat, float zAngle) SHZ_NOEXCEPT;
```

Multiplies and accumulates a rotation matrix by `zAngle` radians about the Z-axis onto the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `zAngle` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_rotation_z`](https://sh4zam.com/api/cpp/mat4x4/#apply_rotation_z)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:431`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L431)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_rotation_zxy

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_zxy/

```c
SHZ_INLINE void shz_mat4x4_apply_rotation_zxy(shz_mat4x4_t* mat, float zAngle, float xAngle, float yAngle) SHZ_NOEXCEPT;
```

Rotates the given transform matrix about the Z axis, then the X axis, then the Y axis by the given angles in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `zAngle` | `float` |  |
| `xAngle` | `float` |  |
| `yAngle` | `float` |  |

## Returns

Nothing (`void`).

## Details

Multiplies and accumulates the given matrix with the 3D rotation matrix formed from the intrinsic rotation created by the given Tait-Bryan Z-Y-X angles.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_rotation_zxy`](https://sh4zam.com/api/cpp/mat4x4/#apply_rotation_zxy)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:455`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L455)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_rotation_zyx

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_zyx/

```c
SHZ_INLINE void shz_mat4x4_apply_rotation_zyx(shz_mat4x4_t* mat, float zAngle, float yAngle, float xAngle) SHZ_NOEXCEPT;
```

Rotates the given transform matrix about the Z axis, then the Y axis, then the X axis by the given angles in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `zAngle` | `float` |  |
| `yAngle` | `float` |  |
| `xAngle` | `float` |  |

## Returns

Nothing (`void`).

## Details

Multiplies and accumulates the given matrix with the 3D rotation matrix formed from the intrinsic rotation created by the given Tait-Bryan Z-Y-X angles.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_rotation_zyx`](https://sh4zam.com/api/cpp/mat4x4/#apply_rotation_zyx)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:447`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L447)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_rotation

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation/

```c
SHZ_INLINE void shz_mat4x4_apply_rotation(shz_mat4x4_t* mat, float angle, float xAxis, float yAxis, float zAxis) SHZ_NOEXCEPT;
```

Rotates the given transform matrix about the arbitrary axis given by a 3D direction vector and angle of rotation in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `angle` | `float` |  |
| `xAxis` | `float` |  |
| `yAxis` | `float` |  |
| `zAxis` | `float` |  |

## Returns

Nothing (`void`).

## Details

Multiplies and accumulates the given matrix with the 3D rotation matrix formed from the intrinsic rotation created by the given Tait-Bryan Z-Y-X angles.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:471`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L471)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_scale

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_scale/

```c
SHZ_INLINE void shz_mat4x4_apply_scale(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Multiplies and accumulates the scale-related elements of the given matrix by the given 3D components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_scale`](https://sh4zam.com/api/cpp/mat4x4/#apply_scale)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:413`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L413)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_screen

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_screen/

```c
SHZ_INLINE void shz_mat4x4_apply_screen(shz_mat4x4_t* m, float width, float height) SHZ_NOEXCEPT;
```

Multiplies and accumulates the viewport matrix created with the given components ont othe given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `shz_mat4x4_t *` |  |
| `width` | `float` |  |
| `height` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_screen`](https://sh4zam.com/api/cpp/mat4x4/#apply_screen)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:507`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L507)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_self

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_self/

```c
SHZ_INLINE void shz_mat4x4_apply_self(shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Multiplies and accumulates the given matrix onto itself.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_self`](https://sh4zam.com/api/cpp/mat4x4/#apply_self)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:531`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L531)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_symmetric_skew

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_symmetric_skew/

```c
SHZ_INLINE void shz_mat4x4_apply_symmetric_skew(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Multiplies and accumulates the given matrix with a symmetric skew matrix formed from the given 3D vector components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_symmetric_skew`](https://sh4zam.com/api/cpp/mat4x4/#apply_symmetric_skew)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:513`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L513)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_translation

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_translation/

```c
SHZ_INLINE void shz_mat4x4_apply_translation(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Adds the given 3D vector components to the translational values of the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Notes

- This routine does not use XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::apply_translation`](https://sh4zam.com/api/cpp/mat4x4/#apply_translation)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:407`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L407)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_transpose_unaligned

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_transpose_unaligned/

> Multiplies and accumulates the transposed unaligned src 4x4 matrix onto the dst 4x4 matrix

```c
SHZ_INLINE void shz_mat4x4_apply_transpose_unaligned(shz_mat4x4_t* dst, const float src[16]) SHZ_NOEXCEPT;
```

Multiplies and accumulates the transposed unaligned `src` 4x4 matrix onto the `dst` 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `shz_mat4x4_t *` |  |
| `src` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:401`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L401)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_transpose

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_transpose/

> Multiplies and accumulates the transposed src 4x4 matrix onto the dst 4x4 matrix

```c
SHZ_INLINE void shz_mat4x4_apply_transpose(shz_mat4x4_t* dst, const shz_mat4x4_t* src) SHZ_NOEXCEPT;
```

Multiplies and accumulates the transposed `src` 4x4 matrix onto the `dst` 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `shz_mat4x4_t *` |  |
| `src` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:395`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L395)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply_unaligned

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply_unaligned/

> Multiplies and accumulates the unaligned src 4x4 matrix onto the dst 4x4 matrix

```c
SHZ_INLINE void shz_mat4x4_apply_unaligned(shz_mat4x4_t* dst, const float src[16]) SHZ_NOEXCEPT;
```

Multiplies and accumulates the unaligned `src` 4x4 matrix onto the `dst` 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `shz_mat4x4_t *` |  |
| `src` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:389`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L389)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_apply

Source: https://sh4zam.com/api/matrix/shz_mat4x4_apply/

> Multiplies and accumulates the src 4x4 matrix onto the dst 4x4 matrix

```c
SHZ_INLINE void shz_mat4x4_apply(shz_mat4x4_t* dst, const shz_mat4x4_t* src) SHZ_NOEXCEPT;
```

Multiplies and accumulates the `src` 4x4 matrix onto the `dst` 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `shz_mat4x4_t *` |  |
| `src` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:383`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L383)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Applying"


---
# shz_mat4x4_blend

Source: https://sh4zam.com/api/matrix/shz_mat4x4_blend/

```c
SHZ_INLINE void shz_mat4x4_blend(shz_mat4x4_t* dst, const shz_mat4x4_t* matrix, float weights) SHZ_NOEXCEPT;
```

Adds and accumulates a scaled 4x4 matrix into the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `shz_mat4x4_t *` |  |
| `matrix` | `const shz_mat4x4_t *` |  |
| `weights` | `float` |  |

## Returns

Nothing (`void`).

## Details

Each component of `joint_matrix` will be multiplied by `weight`, with the result being added to the existing value of that component in `dst`.

This is useful for accumulating weighted joint matrices onto an initially zeroed-out matrix.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::blend`](https://sh4zam.com/api/cpp/mat4x4/#blend)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:879`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L879)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Miscellaneous"

## See also

[`shz_mat4x4_init_zero`](https://sh4zam.com/api/matrix/shz_mat4x4_init_zero/)


---
# shz_mat4x4_col

Source: https://sh4zam.com/api/matrix/shz_mat4x4_col/

> Extracts the col index as a 4D column vector from the given matrix

```c
SHZ_INLINE shz_vec4_t shz_mat4x4_col(const shz_mat4x4_t* mat, size_t col) SHZ_NOEXCEPT;
```

Extracts the `col` index as a 4D column vector from the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |
| `col` | `size_t` |  |

## Returns

`shz_vec4_t`

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::col`](https://sh4zam.com/api/cpp/mat4x4/#col)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:311`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L311)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Getting"


---
# shz_mat4x4_copy_unaligned

Source: https://sh4zam.com/api/matrix/shz_mat4x4_copy_unaligned/

> Copies the given unaligned src 4x4 matrix into the given dst 4x4 matrix

```c
SHZ_INLINE void shz_mat4x4_copy_unaligned(shz_mat4x4_t* dst, const float src[16]) SHZ_NOEXCEPT;
```

Copies the given unaligned `src` 4x4 matrix into the given `dst` 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `shz_mat4x4_t *` |  |
| `src` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:859`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L859)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Miscellaneous"


---
# shz_mat4x4_copy

Source: https://sh4zam.com/api/matrix/shz_mat4x4_copy/

> Copies the given src 4x4 matrix into the given dst 4x4 matrix

```c
SHZ_INLINE void shz_mat4x4_copy(shz_mat4x4_t* dst, const shz_mat4x4_t* src) SHZ_NOEXCEPT;
```

Copies the given `src` 4x4 matrix into the given `dst` 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `shz_mat4x4_t *` |  |
| `src` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::mat4x4`](https://sh4zam.com/api/cpp/mat4x4/#mat4x4), [`shz::mat4x4::operator=`](https://sh4zam.com/api/cpp/mat4x4/)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:853`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L853)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Miscellaneous"


---
# shz_mat4x4_decompose

Source: https://sh4zam.com/api/matrix/shz_mat4x4_decompose/

```c
void shz_mat4x4_decompose(const shz_mat4x4_t* mat, shz_vec3_t* translation, shz_quat_t* rotation, shz_vec3_t* scale) SHZ_NOEXCEPT;
```

Decomposes a 4x4 transform matrix into translation, rotation, and scale.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |
| `translation` | `shz_vec3_t *` |  |
| `rotation` | `shz_quat_t *` |  |
| `scale` | `shz_vec3_t *` |  |

## Returns

Nothing (`void`).

## Notes

- Any output pointer may be NULL to skip that component.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::decompose`](https://sh4zam.com/api/cpp/mat4x4/#decompose)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:295`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L295)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Decomposition"


---
# shz_mat4x4_determinant

Source: https://sh4zam.com/api/matrix/shz_mat4x4_determinant/

```c
SHZ_INLINE float shz_mat4x4_determinant(const shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Returns the determinant of the given 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |

## Returns

`float`

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::determinant`](https://sh4zam.com/api/cpp/mat4x4/#determinant)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:324`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L324)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Getting"


---
# shz_mat4x4_equal

Source: https://sh4zam.com/api/matrix/shz_mat4x4_equal/

```c
SHZ_INLINE bool shz_mat4x4_equal(const shz_mat4x4_t* SHZ_RESTRICT mat1, const shz_mat4x4_t* mat2) SHZ_NOEXCEPT;
```

Returns true if the two matrices are equal, based on either absolute or relative tolerance.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat1` | `const shz_mat4x4_t *SHZ_RESTRICT` |  |
| `mat2` | `const shz_mat4x4_t *` |  |

## Returns

`bool`

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:847`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L847)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Miscellaneous"


---
# shz_mat4x4_get_scale

Source: https://sh4zam.com/api/matrix/shz_mat4x4_get_scale/

```c
SHZ_INLINE shz_vec3_t shz_mat4x4_get_scale(const shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Exracts the 3D scale factors from the given 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |

## Returns

`shz_vec3_t`

## Warnings

- This routine assumes `mat` is a standard TRS-style transform matrix, without shearing or reflection.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::get_scale`](https://sh4zam.com/api/cpp/mat4x4/#get_scale)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:321`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L321)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Getting"


---
# shz_mat4x4_get_translation

Source: https://sh4zam.com/api/matrix/shz_mat4x4_get_translation/

```c
SHZ_INLINE shz_vec3_t shz_mat4x4_get_translation(const shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Returns the translational components from the 4th column as a 3D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |

## Returns

`shz_vec3_t`

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::get_translation`](https://sh4zam.com/api/cpp/mat4x4/#get_translation)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:314`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L314)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Getting"


---
# shz_mat4x4_init_diagonal

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_diagonal/

```c
SHZ_INLINE void shz_mat4x4_init_diagonal(shz_mat4x4_t* mat, float x, float y, float z, float w) SHZ_NOEXCEPT;
```

Initializes the given matrix to a diagonal matrix with the given 4 values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |
| `w` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_diagonal`](https://sh4zam.com/api/cpp/mat4x4/#init_diagonal)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:210`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L210)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_fill

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_fill/

```c
SHZ_INLINE void shz_mat4x4_init_fill(shz_mat4x4_t* mat, float value) SHZ_NOEXCEPT;
```

Initializes the given matrix with all elements assigned to the given value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `value` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_fill`](https://sh4zam.com/api/cpp/mat4x4/#init_fill)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:122`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L122)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_frustum

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_frustum/

```c
SHZ_INLINE void shz_mat4x4_init_frustum(shz_mat4x4_t* mat, float left, float right, float bottom, float top, float znear, float zfar) SHZ_NOEXCEPT;
```

Initializes the given matrix to a frustum projection matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `left` | `float` |  |
| `right` | `float` |  |
| `bottom` | `float` |  |
| `top` | `float` |  |
| `znear` | `float` |  |
| `zfar` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_frustum`](https://sh4zam.com/api/cpp/mat4x4/#init_frustum)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:274`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L274)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_identity_safe

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_identity_safe/

```c
SHZ_INLINE void shz_mat4x4_init_identity_safe(shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Safely initializes the given matrix to the 4x4 identity matrix.

**Deprecated:** `shz_mat4x4_init_identity()` is already safe now by default. This routine simply calls directly into it and should not be used.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:104`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L104)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"

## See also

[`shz_mat4x4_init_identity`](https://sh4zam.com/api/matrix/shz_mat4x4_init_identity/)


---
# shz_mat4x4_init_identity

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_identity/

```c
SHZ_INLINE void shz_mat4x4_init_identity(shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Initializes the given matrix to the 4x4 identity matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_identity`](https://sh4zam.com/api/cpp/mat4x4/#init_identity), [`shz::mat4x4::init_identity_safe`](https://sh4zam.com/api/cpp/mat4x4/#init_identity_safe)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:91`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L91)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_lookat

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_lookat/

```c
SHZ_INLINE void shz_mat4x4_init_lookat(shz_mat4x4_t* mat, shz_vec3_t eye, shz_vec3_t center, shz_vec3_t up) SHZ_NOEXCEPT;
```

Initializes the given matrix to a "lookAt" view matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `eye` | `shz_vec3_t` |  |
| `center` | `shz_vec3_t` |  |
| `up` | `shz_vec3_t` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_lookat`](https://sh4zam.com/api/cpp/mat4x4/#init_lookat)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:262`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L262)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_lower_triangular

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_lower_triangular/

```c
SHZ_INLINE void shz_mat4x4_init_lower_triangular(shz_mat4x4_t* mat, shz_vec4_t col1, shz_vec3_t col2, shz_vec2_t col3, float col4) SHZ_NOEXCEPT;
```

Initializes the given matrix to a lower triangular matrix whose nonzero entries have the given value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `col1` | `shz_vec4_t` |  |
| `col2` | `shz_vec3_t` |  |
| `col3` | `shz_vec2_t` |  |
| `col4` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_lower_triangular`](https://sh4zam.com/api/cpp/mat4x4/#init_lower_triangular)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:222`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L222)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_one

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_one/

```c
SHZ_INLINE void shz_mat4x4_init_one(shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Initializes the given matrix with all 1s for its element values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_one`](https://sh4zam.com/api/cpp/mat4x4/#init_one)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:116`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L116)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_ortho

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_ortho/

```c
SHZ_INLINE void shz_mat4x4_init_ortho(shz_mat4x4_t* mat, float left, float right, float bottom, float top, float znear, float zfar) SHZ_NOEXCEPT;
```

Initializes the given matrix to an orthographic projection matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `left` | `float` |  |
| `right` | `float` |  |
| `bottom` | `float` |  |
| `top` | `float` |  |
| `znear` | `float` |  |
| `zfar` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_ortho`](https://sh4zam.com/api/cpp/mat4x4/#init_ortho)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:268`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L268)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_outer_product

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_outer_product/

```c
SHZ_INLINE void shz_mat4x4_init_outer_product(shz_mat4x4_t* mat, shz_vec4_t v1, shz_vec4_t v2) SHZ_NOEXCEPT;
```

Initializes the given matrix to be the result from taking the outer product of the two given 4D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `v1` | `shz_vec4_t` |  |
| `v2` | `shz_vec4_t` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_outer_product`](https://sh4zam.com/api/cpp/mat4x4/#init_outer_product)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:238`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L238)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_permutation_wxyz

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_permutation_wxyz/

```c
SHZ_INLINE void shz_mat4x4_init_permutation_wxyz(shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Initializes the matrix to to a permutation matrix, which reorders the components of transformed vectors to be in WXYZ order.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_permutation_wxyz`](https://sh4zam.com/api/cpp/mat4x4/#init_permutation_wxyz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:244`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L244)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_permutation_yzwx

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_permutation_yzwx/

```c
SHZ_INLINE void shz_mat4x4_init_permutation_yzwx(shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Initializes the matrix to to a permutation matrix, which reorders the components of transformed vectors to be in YZWX order.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_permutation_yzwx`](https://sh4zam.com/api/cpp/mat4x4/#init_permutation_yzwx)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:250`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L250)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_perspective

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_perspective/

```c
SHZ_INLINE void shz_mat4x4_init_perspective(shz_mat4x4_t* mat, float fov, float aspect, float znear) SHZ_NOEXCEPT;
```

Initializes the given matrix to a perspective projection matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `fov` | `float` |  |
| `aspect` | `float` |  |
| `znear` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_perspective`](https://sh4zam.com/api/cpp/mat4x4/#init_perspective)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:280`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L280)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_rotation_dir

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_dir/

> Initializes the given 4x4 matrix to contain a 3D rotation matrix of angle radians about the given direction

```c
SHZ_INLINE void shz_mat4x4_init_rotation_dir(shz_mat4x4_t* mat, float angle, float x, float y, float z) SHZ_NOEXCEPT;
```

Initializes the given 4x4 matrix to contain a 3D rotation matrix of `angle` radians about the given direction.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `angle` | `float` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Details

This is a faster version of `shz_mat4x4_init_rotation()` or glRotatef() which requires being passed a unit vector for the rotation axis.

## Warnings

- The vector components representing the axis of rotation must be prenormalized!

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_rotation_dir`](https://sh4zam.com/api/cpp/mat4x4/#init_rotation_dir)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:198`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L198)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"

## See also

[`shz_mat4x4_init_rotation`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation/)


---
# shz_mat4x4_init_rotation_quat

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_quat/

```c
SHZ_INLINE void shz_mat4x4_init_rotation_quat(shz_mat4x4_t* m, shz_quat_t q) SHZ_NOEXCEPT;
```

Initializes the given matrix to a 3D rotation matrix with its orientation given by a quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `shz_mat4x4_t *` |  |
| `q` | `shz_quat_t` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:204`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L204)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_rotation_x

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_x/

> Initializes the given matrix to a 3D rotation matrix by xAngle radians over the X-axis

```c
SHZ_INLINE void shz_mat4x4_init_rotation_x(shz_mat4x4_t* mat, float xAngle) SHZ_NOEXCEPT;
```

Initializes the given matrix to a 3D rotation matrix by `xAngle` radians over the X-axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `xAngle` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_rotation_x`](https://sh4zam.com/api/cpp/mat4x4/#init_rotation_x)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:140`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L140)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_rotation_xyz

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_xyz/

```c
SHZ_INLINE void shz_mat4x4_init_rotation_xyz(shz_mat4x4_t* mat, float xAngle, float yAngle, float zAngle) SHZ_NOEXCEPT;
```

Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan X-Y-Z angles.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `xAngle` | `float` |  |
| `yAngle` | `float` |  |
| `zAngle` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_rotation_xyz`](https://sh4zam.com/api/cpp/mat4x4/#init_rotation_xyz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:158`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L158)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_rotation_y

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_y/

> Initializes the given matrix to a 3D rotation matrix by yAngle radians over the Y-axis

```c
SHZ_INLINE void shz_mat4x4_init_rotation_y(shz_mat4x4_t* mat, float yAngle) SHZ_NOEXCEPT;
```

Initializes the given matrix to a 3D rotation matrix by `yAngle` radians over the Y-axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `yAngle` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_rotation_y`](https://sh4zam.com/api/cpp/mat4x4/#init_rotation_y)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:146`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L146)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_rotation_yxz

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_yxz/

```c
SHZ_INLINE void shz_mat4x4_init_rotation_yxz(shz_mat4x4_t* mat, float yAngle, float xAngle, float zAngle) SHZ_NOEXCEPT;
```

Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan Y-X-Z angles.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `yAngle` | `float` |  |
| `xAngle` | `float` |  |
| `zAngle` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_rotation_yxz`](https://sh4zam.com/api/cpp/mat4x4/#init_rotation_yxz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:176`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L176)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_rotation_z

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_z/

> Initializes the given matrix to a 3D rotation matrix by zAngle radians over the Z-axis

```c
SHZ_INLINE void shz_mat4x4_init_rotation_z(shz_mat4x4_t* mat, float zAngle) SHZ_NOEXCEPT;
```

Initializes the given matrix to a 3D rotation matrix by `zAngle` radians over the Z-axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `zAngle` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobber XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_rotation_z`](https://sh4zam.com/api/cpp/mat4x4/#init_rotation_z)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:152`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L152)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_rotation_zxy

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_zxy/

```c
SHZ_INLINE void shz_mat4x4_init_rotation_zxy(shz_mat4x4_t* mat, float zAngle, float xAngle, float yAngle) SHZ_NOEXCEPT;
```

Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan Z-X-Y angles.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `zAngle` | `float` |  |
| `xAngle` | `float` |  |
| `yAngle` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_rotation_zxy`](https://sh4zam.com/api/cpp/mat4x4/#init_rotation_zxy)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:170`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L170)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_rotation_zyx

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_zyx/

```c
SHZ_INLINE void shz_mat4x4_init_rotation_zyx(shz_mat4x4_t* mat, float zAngle, float yAngle, float xAngle) SHZ_NOEXCEPT;
```

Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan Z-Y-X angles.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `zAngle` | `float` |  |
| `yAngle` | `float` |  |
| `xAngle` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_rotation_zyx`](https://sh4zam.com/api/cpp/mat4x4/#init_rotation_zyx)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:164`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L164)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_rotation

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation/

> Initializes the given 4x4 matrix to a 3D rotation matrix of angle radians about the vector with the given components

```c
SHZ_INLINE void shz_mat4x4_init_rotation(shz_mat4x4_t* mat, float radians, float xAxis, float yAxis, float zAxis) SHZ_NOEXCEPT;
```

Initializes the given 4x4 matrix to a 3D rotation matrix of `angle` radians about the vector with the given components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `radians` | `float` |  |
| `xAxis` | `float` |  |
| `yAxis` | `float` |  |
| `zAxis` | `float` |  |

## Returns

Nothing (`void`).

## Notes

- This routine works similarly to glRotatef() applied to an identitiy matrix. The given axis will automatically be normalized internally.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:187`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L187)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"

## See also

[`shz_mat4x4_init_rotation_dir`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_dir/)


---
# shz_mat4x4_init_scale

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_scale/

```c
SHZ_INLINE void shz_mat4x4_init_scale(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Initializes the given matrix to a 3D scaling matrix with the given dimensions.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_scale`](https://sh4zam.com/api/cpp/mat4x4/#init_scale)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:134`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L134)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_screen

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_screen/

```c
SHZ_INLINE void shz_mat4x4_init_screen(shz_mat4x4_t* mat, float width, float height) SHZ_NOEXCEPT;
```

Initializes the given matrix to the viewport matrix with the given dimenions.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `width` | `float` |  |
| `height` | `float` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_screen`](https://sh4zam.com/api/cpp/mat4x4/#init_screen)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:256`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L256)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_symmetric_skew

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_symmetric_skew/

```c
SHZ_INLINE void shz_mat4x4_init_symmetric_skew(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Initializes the given matrix to be the symmetric skew of the given 3D vector components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Notes

- This can be useful for batching the cross-product operation against a constant vector. For one-offs, prefer `shz_vec3_cross()`.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_symmetric_skew`](https://sh4zam.com/api/cpp/mat4x4/#init_symmetric_skew)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:232`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L232)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_translation

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_translation/

```c
SHZ_INLINE void shz_mat4x4_init_translation(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Initializes the given matrix to a 3D translation matrix with the given coordinates.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_translation`](https://sh4zam.com/api/cpp/mat4x4/#init_translation)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:128`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L128)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_upper_triangular

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_upper_triangular/

```c
SHZ_INLINE void shz_mat4x4_init_upper_triangular(shz_mat4x4_t* mat, float col1, shz_vec2_t col2, shz_vec3_t col3, shz_vec4_t col4) SHZ_NOEXCEPT;
```

Initializes the given matrix to an upper triangular matrix whose nonzero entries have the given value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `col1` | `float` |  |
| `col2` | `shz_vec2_t` |  |
| `col3` | `shz_vec3_t` |  |
| `col4` | `shz_vec4_t` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_upper_triangular`](https://sh4zam.com/api/cpp/mat4x4/#init_upper_triangular)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:216`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L216)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_init_zero

Source: https://sh4zam.com/api/matrix/shz_mat4x4_init_zero/

```c
SHZ_INLINE void shz_mat4x4_init_zero(shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Initializes the given matrix with all 0s for its element values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::init_zero`](https://sh4zam.com/api/cpp/mat4x4/#init_zero)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:110`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L110)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Initialization"


---
# shz_mat4x4_inverse_block_triangular

Source: https://sh4zam.com/api/matrix/shz_mat4x4_inverse_block_triangular/

```c
void shz_mat4x4_inverse_block_triangular(const shz_mat4x4_t* mtx, shz_mat4x4_t* out) SHZ_NOEXCEPT;
```

Computes the inverse of a 4x4 matrix in block-triangular form.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mtx` | `const shz_mat4x4_t *` |  |
| `out` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Details

This is a special-case faster optimization for 4x4 matrices which take the form:

```text
A = [ M   b ]
    [ 0   w ]
```

Where A is 4x4, M is 3x3, b is 3x1, and the bottom row is (0, 0, 0, w) with w != 0. For this block-triangular form, det(A) = det(M) \* w. Then

```text
inv(A) = [ inv(M)        -inv(M) * b / w ]
         [   0                 1/w       ]
```

## Notes

- A regular 3D transform matrix is already in this form.
- `shz_mat4x4_inverse()` will dynamically check whether to use this optimization.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::inverse_block_triangular`](https://sh4zam.com/api/cpp/mat4x4/#inverse_block_triangular)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:844`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L844)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Miscellaneous"


---
# shz_mat4x4_inverse

Source: https://sh4zam.com/api/matrix/shz_mat4x4_inverse/

```c
void shz_mat4x4_inverse(const shz_mat4x4_t* SHZ_RESTRICT mtrx, shz_mat4x4_t* SHZ_RESTRICT out) SHZ_NOEXCEPT;
```

Computes the inverse of a 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mtrx` | `const shz_mat4x4_t *SHZ_RESTRICT` | Pointer to the 4x4 matrix to invert. |
| `out` | `shz_mat4x4_t *SHZ_RESTRICT` | Pointer to the resulting inverted matrix. |

## Returns

Nothing (`void`).

## Notes

- In-place inversion (mtrx == out) is not supported.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::inverse`](https://sh4zam.com/api/cpp/mat4x4/#inverse)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:824`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L824)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Miscellaneous"


---
# shz_mat4x4_is_block_triangular

Source: https://sh4zam.com/api/matrix/shz_mat4x4_is_block_triangular/

> Returns true if the given matrix is in block-triangular form: having a bottom row in the form of <0.0f, 0.0f, 0.0f, w>

```c
SHZ_INLINE bool shz_mat4x4_is_block_triangular(const shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Returns true if the given matrix is in block-triangular form: having a bottom row in the form of `<0.0f, 0.0f, 0.0f, w>`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |

## Returns

`bool`

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:850`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L850)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Miscellaneous"


---
# shz_mat4x4_mult_transpose_unaligned

Source: https://sh4zam.com/api/matrix/shz_mat4x4_mult_transpose_unaligned/

> Multiplies the regular matrix, lhs, by the transpose of the unaligned matrix, rhs, storing the result into mat

```c
SHZ_INLINE void shz_mat4x4_mult_transpose_unaligned(shz_mat4x4_t* mat, const shz_mat4x4_t* lhs, const float rhs[16]) SHZ_NOEXCEPT;
```

Multiplies the regular matrix, `lhs`, by the transpose of the unaligned matrix, `rhs`, storing the result into `mat`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `lhs` | `const shz_mat4x4_t *` |  |
| `rhs` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:651`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L651)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"


---
# shz_mat4x4_mult_transpose

Source: https://sh4zam.com/api/matrix/shz_mat4x4_mult_transpose/

> Multiplies the regular matrix, lhs, by the transpose of the matrix, rhs, storing the result into mat

```c
SHZ_INLINE void shz_mat4x4_mult_transpose(shz_mat4x4_t* mat, const shz_mat4x4_t* lhs, const shz_mat4x4_t* rhs) SHZ_NOEXCEPT;
```

Multiplies the regular matrix, `lhs`, by the transpose of the matrix, `rhs`, storing the result into `mat`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `lhs` | `const shz_mat4x4_t *` |  |
| `rhs` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:645`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L645)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"


---
# shz_mat4x4_mult_unaligned

Source: https://sh4zam.com/api/matrix/shz_mat4x4_mult_unaligned/

```c
SHZ_INLINE void shz_mat4x4_mult_unaligned(shz_mat4x4_t* mat, const shz_mat4x4_t* lhs, const float rhs[16]) SHZ_NOEXCEPT;
```

Multiplies two 4x4 matrices together, with the right handed matrix being unaligned, storing the result into a third.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `lhs` | `const shz_mat4x4_t *` |  |
| `rhs` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:639`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L639)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"


---
# shz_mat4x4_mult

Source: https://sh4zam.com/api/matrix/shz_mat4x4_mult/

```c
SHZ_INLINE void shz_mat4x4_mult(shz_mat4x4_t* mat, const shz_mat4x4_t* lhs, const shz_mat4x4_t* rhs) SHZ_NOEXCEPT;
```

Multiplies two 4x4 matrices together, storing the result into a third.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `lhs` | `const shz_mat4x4_t *` |  |
| `rhs` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:633`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L633)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"


---
# shz_mat4x4_rotate_x

Source: https://sh4zam.com/api/matrix/shz_mat4x4_rotate_x/

> Multiplies and accumulates mat by a 3D rotation matrix about the X axis

```c
SHZ_INLINE void shz_mat4x4_rotate_x(shz_mat4x4_t* mat, float radians) SHZ_NOEXCEPT;
```

Multiplies and accumulates `mat` by a 3D rotation matrix about the X axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `radians` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::rotate_x`](https://sh4zam.com/api/cpp/mat4x4/#rotate_x)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:558`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L558)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "GL Transformations"


---
# shz_mat4x4_rotate_xyz

Source: https://sh4zam.com/api/matrix/shz_mat4x4_rotate_xyz/

> Multiplies and accumulates mat by 3D rotation matrices about the X then Y then Z axes

```c
SHZ_INLINE void shz_mat4x4_rotate_xyz(shz_mat4x4_t* mat, float xRadians, float yRadians, float zRadians) SHZ_NOEXCEPT;
```

Multiplies and accumulates `mat` by 3D rotation matrices about the X then Y then Z axes.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `xRadians` | `float` |  |
| `yRadians` | `float` |  |
| `zRadians` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::rotate_xyz`](https://sh4zam.com/api/cpp/mat4x4/#rotate_xyz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:576`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L576)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "GL Transformations"


---
# shz_mat4x4_rotate_y

Source: https://sh4zam.com/api/matrix/shz_mat4x4_rotate_y/

> Multiplies and accumulates mat by a 3D rotation matrix about the Y axis

```c
SHZ_INLINE void shz_mat4x4_rotate_y(shz_mat4x4_t* mat, float radians) SHZ_NOEXCEPT;
```

Multiplies and accumulates `mat` by a 3D rotation matrix about the Y axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `radians` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::rotate_y`](https://sh4zam.com/api/cpp/mat4x4/#rotate_y)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:564`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L564)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "GL Transformations"


---
# shz_mat4x4_rotate_yxz

Source: https://sh4zam.com/api/matrix/shz_mat4x4_rotate_yxz/

> Multiplies and accumulates mat by 3D rotation matrices about the Y then X then Z axes

```c
SHZ_INLINE void shz_mat4x4_rotate_yxz(shz_mat4x4_t* mat, float yRadians, float xRadians, float zRadians) SHZ_NOEXCEPT;
```

Multiplies and accumulates `mat` by 3D rotation matrices about the Y then X then Z axes.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `yRadians` | `float` |  |
| `xRadians` | `float` |  |
| `zRadians` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::rotate_yxz`](https://sh4zam.com/api/cpp/mat4x4/#rotate_yxz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:594`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L594)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "GL Transformations"


---
# shz_mat4x4_rotate_z

Source: https://sh4zam.com/api/matrix/shz_mat4x4_rotate_z/

> Multiplies and accumulates mat by a 3D rotation matrix about the Z axis

```c
SHZ_INLINE void shz_mat4x4_rotate_z(shz_mat4x4_t* mat, float radians) SHZ_NOEXCEPT;
```

Multiplies and accumulates `mat` by a 3D rotation matrix about the Z axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `radians` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::rotate_z`](https://sh4zam.com/api/cpp/mat4x4/#rotate_z)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:570`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L570)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "GL Transformations"


---
# shz_mat4x4_rotate_zxy

Source: https://sh4zam.com/api/matrix/shz_mat4x4_rotate_zxy/

> Multiplies and accumulates mat by 3D rotation matrices about the Z then X then Y axes

```c
SHZ_INLINE void shz_mat4x4_rotate_zxy(shz_mat4x4_t* mat, float zRadians, float xRadians, float yRadians) SHZ_NOEXCEPT;
```

Multiplies and accumulates `mat` by 3D rotation matrices about the Z then X then Y axes.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `zRadians` | `float` |  |
| `xRadians` | `float` |  |
| `yRadians` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::rotate_zxy`](https://sh4zam.com/api/cpp/mat4x4/#rotate_zxy)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:588`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L588)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "GL Transformations"


---
# shz_mat4x4_rotate_zyx

Source: https://sh4zam.com/api/matrix/shz_mat4x4_rotate_zyx/

> Multiplies and accumulates mat by 3D rotation matrices about the Z then Y then X axes

```c
SHZ_INLINE void shz_mat4x4_rotate_zyx(shz_mat4x4_t* mat, float zRadians, float yRadians, float xRadians) SHZ_NOEXCEPT;
```

Multiplies and accumulates `mat` by 3D rotation matrices about the Z then Y then X axes.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `zRadians` | `float` |  |
| `yRadians` | `float` |  |
| `xRadians` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::rotate_zyx`](https://sh4zam.com/api/cpp/mat4x4/#rotate_zyx)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:582`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L582)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "GL Transformations"


---
# shz_mat4x4_rotate

Source: https://sh4zam.com/api/matrix/shz_mat4x4_rotate/

> Multiplies and accumulates mat by the 3D rotation matrix formed by the given axis and angle

```c
SHZ_INLINE void shz_mat4x4_rotate(shz_mat4x4_t* mat, float radians, float xAxis, float yAxis, float zAxis) SHZ_NOEXCEPT;
```

Multiplies and accumulates `mat` by the 3D rotation matrix formed by the given axis and angle.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `radians` | `float` |  |
| `xAxis` | `float` |  |
| `yAxis` | `float` |  |
| `zAxis` | `float` |  |

## Returns

Nothing (`void`).

## Notes

- Equivalent to glRotatef().

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::rotate`](https://sh4zam.com/api/cpp/mat4x4/#rotate)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:601`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L601)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "GL Transformations"


---
# shz_mat4x4_row

Source: https://sh4zam.com/api/matrix/shz_mat4x4_row/

> Extracts the row index as a 4D row vector from the given matrix

```c
SHZ_INLINE shz_vec4_t shz_mat4x4_row(const shz_mat4x4_t* mat, size_t row) SHZ_NOEXCEPT;
```

Extracts the `row` index as a 4D row vector from the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |
| `row` | `size_t` |  |

## Returns

`shz_vec4_t`

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::row`](https://sh4zam.com/api/cpp/mat4x4/#row)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:308`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L308)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Getting"


---
# shz_mat4x4_scale_reverse

Source: https://sh4zam.com/api/matrix/shz_mat4x4_scale_reverse/

```c
SHZ_INLINE void shz_mat4x4_scale_reverse(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Pre-multiplies and accumulates the given matrix onto the 3D scaling matrix with the given components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX

## Naming and requirements

- `_reverse`: Reversed multiplication order (pre-multiply instead of post-multiply). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::scale_reverse`](https://sh4zam.com/api/cpp/mat4x4/#scale_reverse)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:620`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L620)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Reverse GL Transformations"


---
# shz_mat4x4_scale

Source: https://sh4zam.com/api/matrix/shz_mat4x4_scale/

> Multiplies and accumulates mat by a 3D scaling matrix with the given components

```c
SHZ_INLINE void shz_mat4x4_scale(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Multiplies and accumulates `mat` by a 3D scaling matrix with the given components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Notes

- glScalef() equivalent.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::scale`](https://sh4zam.com/api/cpp/mat4x4/#scale)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:552`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L552)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "GL Transformations"


---
# shz_mat4x4_set_col

Source: https://sh4zam.com/api/matrix/shz_mat4x4_set_col/

> Sets the values of mat at the given col to those of the 4D vector, vec

```c
SHZ_INLINE void shz_mat4x4_set_col(shz_mat4x4_t* mat, size_t col, shz_vec4_t vec) SHZ_NOEXCEPT;
```

Sets the values of `mat` at the given `col` to those of the 4D vector, `vec`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `col` | `size_t` |  |
| `vec` | `shz_vec4_t` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::set_col`](https://sh4zam.com/api/cpp/mat4x4/#set_col)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:352`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L352)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Setting"


---
# shz_mat4x4_set_diagonal

Source: https://sh4zam.com/api/matrix/shz_mat4x4_set_diagonal/

```c
SHZ_INLINE void shz_mat4x4_set_diagonal(shz_mat4x4_t* mat, float x, float y, float z, float w) SHZ_NOEXCEPT;
```

Assigns only the 4 elements along the diagonal of the given matrix to the given values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |
| `w` | `float` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::set_diagonal`](https://sh4zam.com/api/cpp/mat4x4/#set_diagonal)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:370`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L370)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Setting"


---
# shz_mat4x4_set_rotation_quat

Source: https://sh4zam.com/api/matrix/shz_mat4x4_set_rotation_quat/

```c
SHZ_INLINE void shz_mat4x4_set_rotation_quat(shz_mat4x4_t* m, shz_quat_t q) SHZ_NOEXCEPT;
```

Sets just the rotational component of the matrix to the orientation given by a quaternion, keeping the other elements in-tact.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `shz_mat4x4_t *` |  |
| `q` | `shz_quat_t` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::set_rotation`](https://sh4zam.com/api/cpp/mat4x4/#set_rotation)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:367`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L367)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Setting"


---
# shz_mat4x4_set_row

Source: https://sh4zam.com/api/matrix/shz_mat4x4_set_row/

> Sets the values of mat at the given row to those of the 4D vector, vec

```c
SHZ_INLINE void shz_mat4x4_set_row(shz_mat4x4_t* mat, size_t row, shz_vec4_t vec) SHZ_NOEXCEPT;
```

Sets the values of `mat` at the given `row` to those of the 4D vector, `vec`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `row` | `size_t` |  |
| `vec` | `shz_vec4_t` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::set_row`](https://sh4zam.com/api/cpp/mat4x4/#set_row)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:349`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L349)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Setting"


---
# shz_mat4x4_set_scale

Source: https://sh4zam.com/api/matrix/shz_mat4x4_set_scale/

```c
SHZ_INLINE void shz_mat4x4_set_scale(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Assigns only the 3D scale-related elements of the given matrix to the given values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::set_scale`](https://sh4zam.com/api/cpp/mat4x4/#set_scale)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:364`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L364)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Setting"


---
# shz_mat4x4_set_translation

Source: https://sh4zam.com/api/matrix/shz_mat4x4_set_translation/

```c
SHZ_INLINE void shz_mat4x4_set_translation(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Assigns only the 3D translation-related elements of the given matrix to the given values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::set_translation`](https://sh4zam.com/api/cpp/mat4x4/#set_translation)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:361`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L361)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Setting"


---
# shz_mat4x4_swap_cols

Source: https://sh4zam.com/api/matrix/shz_mat4x4_swap_cols/

> Swaps the 4D column vectors located at col1 and col2 within mat

```c
SHZ_INLINE void shz_mat4x4_swap_cols(shz_mat4x4_t* mat, size_t col1, size_t col2) SHZ_NOEXCEPT;
```

Swaps the 4D column vectors located at `col1` and `col2` within `mat`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `col1` | `size_t` |  |
| `col2` | `size_t` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::swap_cols`](https://sh4zam.com/api/cpp/mat4x4/#swap_cols)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:358`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L358)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Setting"


---
# shz_mat4x4_swap_rows

Source: https://sh4zam.com/api/matrix/shz_mat4x4_swap_rows/

> Swaps the 4D row vectors located at row1 and row2 within mat

```c
SHZ_INLINE void shz_mat4x4_swap_rows(shz_mat4x4_t* mat, size_t row1, size_t row2) SHZ_NOEXCEPT;
```

Swaps the 4D row vectors located at `row1` and `row2` within `mat`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `row1` | `size_t` |  |
| `row2` | `size_t` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::swap_rows`](https://sh4zam.com/api/cpp/mat4x4/#swap_rows)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:355`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L355)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Setting"


---
# shz_mat4x4_swap

Source: https://sh4zam.com/api/matrix/shz_mat4x4_swap/

> Swaps the contents of the two given matrices, matA and matB

```c
SHZ_INLINE void shz_mat4x4_swap(shz_mat4x4_t* matA, shz_mat4x4_t* matB) SHZ_NOEXCEPT;
```

Swaps the contents of the two given matrices, `matA` and `matB`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matA` | `shz_mat4x4_t *` |  |
| `matB` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:865`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L865)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Miscellaneous"


---
# shz_mat4x4_t

Source: https://sh4zam.com/api/matrix/shz_mat4x4_t/

```c
typedef SHZ_ALIGNAS(8) struct shz_mat4x4 {
    union {                     //!< Inner convenience union.
        float      elem[16];        //!< Access the matrix as a 1D array of 16 single-precision floats.
        float      elem2D[4][4];    //!< Access the matrix as a 2D array of 4x4 single-precision floats.
        shz_vec4_t col[4];          //!< Access the matrix as an array of 4 1x4 column vectors.
        struct {                //!< Named column vectors.
            shz_vec4_t left;        //!< Access the first column of the matrix as a 1x4 vector.
            shz_vec4_t up;          //!< Access the second column of the matrix as a 1x4 vector.
            shz_vec4_t forward;     //!< Access the third column of the matrix as a 1x4 vector.
            shz_vec4_t pos;         //!< Access the last column of the matrix as a 1x4 vector.
        };
    };
} shz_mat4x4_t;
```

Structure representing a 4x4 column-major matrix.

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `elem` | `float[16]` | \< Inner convenience union. |
| `elem2D` | `float[4][4]` | Access the matrix as a 2D array of 4x4 single-precision floats. |
| `col` | `shz_vec4_t[4]` | Access the matrix as an array of 4 1x4 column vectors. |
| `left` | `shz_vec4_t` | \< Named column vectors. |
| `up` | `shz_vec4_t` | Access the second column of the matrix as a 1x4 vector. |
| `forward` | `shz_vec4_t` | Access the third column of the matrix as a 1x4 vector. |
| `pos` | `shz_vec4_t` | Access the last column of the matrix as a 1x4 vector. |

## Warnings

- This structure MUST be aligned on 8-byte boundaries!

## Availability

- **C++ equivalent:** [`shz::mat4x4`](https://sh4zam.com/api/cpp/mat4x4/)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_matrix.h:65`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L65)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Types"


---
# shz_mat4x4_to_quat

Source: https://sh4zam.com/api/matrix/shz_mat4x4_to_quat/

```c
SHZ_INLINE shz_quat_t shz_mat4x4_to_quat(const shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Converts the given 4x4 orientation matrix into a quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |

## Returns

`shz_quat_t`

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::to_quat`](https://sh4zam.com/api/cpp/mat4x4/#to_quat)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:806`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L806)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Miscellaneous"


---
# shz_mat4x4_trace

Source: https://sh4zam.com/api/matrix/shz_mat4x4_trace/

```c
SHZ_INLINE float shz_mat4x4_trace(const shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Returns the trace of the given 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |

## Returns

`float`

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::trace`](https://sh4zam.com/api/cpp/mat4x4/#trace)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:327`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L327)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Getting"


---
# shz_mat4x4_transform_point2_transpose

Source: https://sh4zam.com/api/matrix/shz_mat4x4_transform_point2_transpose/

```c
SHZ_INLINE shz_vec2_t shz_mat4x4_transform_point2_transpose(const shz_mat4x4_t* mat, shz_vec2_t pt) SHZ_NOEXCEPT;
```

Transforms a 2D point by the transpose of a 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |
| `pt` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Details

This is a routine specializing in one-off transforms of a *single* 2D point by the transpose of a a *single* 4x4 matrix. It should be faster than going through XMTRX.

## Notes

- For batch transforming multiple 2D points against the same 4x4 matrix, preload the matrix into XMTRX, use `shz_xmtrx_transpose()`, then use `shz_xmtrx_transform_point2()`.

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:781`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L781)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"

## See also

[`shz_xmtrx_transpose`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transpose/), [`shz_xmtrx_transform_point2`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_point2/)


---
# shz_mat4x4_transform_point2

Source: https://sh4zam.com/api/matrix/shz_mat4x4_transform_point2/

```c
SHZ_INLINE shz_vec2_t shz_mat4x4_transform_point2(const shz_mat4x4_t* mat, shz_vec2_t pt) SHZ_NOEXCEPT;
```

Transforms a 2D point by a 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |
| `pt` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Details

This is a routine specializing in one-off transforms of a *single* 2D point by a *single* 4x4 matrix. It should be faster than going through XMTRX.

## Notes

- For batch transforming multiple 2D points against the same 4x4 matrix, preload the matrix into XMTRX, then use `shz_xmtrx_transform_point2()`.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:752`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L752)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"

## See also

[`shz_xmtrx_transform_point2`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_point2/)


---
# shz_mat4x4_transform_point3_transpose

Source: https://sh4zam.com/api/matrix/shz_mat4x4_transform_point3_transpose/

```c
SHZ_INLINE shz_vec3_t shz_mat4x4_transform_point3_transpose(const shz_mat4x4_t* mat, shz_vec3_t pt) SHZ_NOEXCEPT;
```

Transforms a 3D point by the transpose of a 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |
| `pt` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Details

This is a routine specializing in one-off transforms of a *single* 3D point by the transpose of a a *single* 4x4 matrix. It should be faster than going through XMTRX.

## Notes

- For batch transforming multiple 3D points against the same 4x4 matrix, preload the matrix into XMTRX, use `shz_xmtrx_transpose()`, then use `shz_xmtrx_transform_point2()`.

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:796`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L796)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"

## See also

[`shz_xmtrx_transpose`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transpose/), [`shz_xmtrx_transform_point3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_point3/)


---
# shz_mat4x4_transform_point3

Source: https://sh4zam.com/api/matrix/shz_mat4x4_transform_point3/

```c
SHZ_INLINE shz_vec3_t shz_mat4x4_transform_point3(const shz_mat4x4_t* mat, shz_vec3_t pt) SHZ_NOEXCEPT;
```

Transforms a 3D point by a 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |
| `pt` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Details

This is a routine specializing in one-off transforms of a *single* 3D point by a *single* 4x4 matrix. It should be faster than going through XMTRX.

## Notes

- For batch transforming multiple 3D points against the same 4x4 matrix, preload the matrix into XMTRX, then use `shz_xmtrx_transform_point3()`.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:766`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L766)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"

## See also

[`shz_xmtrx_transform_point3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_point3/)


---
# shz_mat4x4_transform_vec2_transpose

Source: https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec2_transpose/

```c
SHZ_INLINE shz_vec2_t shz_mat4x4_transform_vec2_transpose(const shz_mat4x4_t* m, shz_vec2_t v) SHZ_NOEXCEPT;
```

Transforms a 2D vector the the transpose of a 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `const shz_mat4x4_t *` |  |
| `v` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Details

This is a routine specializing in one-off transforms of a **single** 2D vector by the transpose of a **single** 4x4 matrix. It should be faster than going through XMTRX.

## Notes

- For batch transforming multiple 2D vectors against the transpose of the same 4x4 matrix, preload the matrix into XMTRX, take its transpose with `shz_xmtrx_transpose()`, then use `shz_xmtrx_transform_vec2()`.

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:708`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L708)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"

## See also

[`shz_xmtrx_transpose`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transpose/), [`shz_xmtrx_transform_vec2`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec2/)


---
# shz_mat4x4_transform_vec2

Source: https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec2/

```c
SHZ_INLINE shz_vec2_t shz_mat4x4_transform_vec2(const shz_mat4x4_t* m, shz_vec2_t v) SHZ_NOEXCEPT;
```

Transforms a 2D vector by a 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `const shz_mat4x4_t *` |  |
| `v` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Details

This is a routine specializing in one-off transforms of a **single** 2D vector by a **single** 4x4 matrix. It should be faster than going through XMTRX.

## Notes

- For batch transforming multiple 2D vectors against the same 4x4 matrix, preload the matrix into XMTRX, then use `shz_xmtrx_transform_vec2()`.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:665`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L665)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"

## See also

[`shz_xmtrx_transform_vec3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec3/)


---
# shz_mat4x4_transform_vec3_transpose

Source: https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec3_transpose/

```c
SHZ_INLINE shz_vec3_t shz_mat4x4_transform_vec3_transpose(const shz_mat4x4_t* m, shz_vec3_t v) SHZ_NOEXCEPT;
```

Transforms a 3D vector the the transpose of a 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `const shz_mat4x4_t *` |  |
| `v` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Details

This is a routine specializing in one-off transforms of a **single** 3D vector by the transpose of a **single** 4x4 matrix. It should be faster than going through XMTRX.

## Notes

- For batch transforming multiple 3D vectors against the transpose of the same 4x4 matrix, preload the matrix into XMTRX, take its transpose with `shz_xmtrx_transpose()`, then use `shz_xmtrx_transform_vec3()`.

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:723`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L723)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"

## See also

[`shz_xmtrx_transpose`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transpose/), [`shz_xmtrx_transform_vec3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec3/)


---
# shz_mat4x4_transform_vec3

Source: https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec3/

```c
SHZ_INLINE shz_vec3_t shz_mat4x4_transform_vec3(const shz_mat4x4_t* m, shz_vec3_t v) SHZ_NOEXCEPT;
```

Transforms a 3D vector by a 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `const shz_mat4x4_t *` |  |
| `v` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Details

This is a routine specializing in one-off transforms of a **single** 3D vector (such as a normal, without a W component) by a **single** 4x4 matrix. It should be faster than going through XMTRX.

## Notes

- For batch transforming multiple 3D vectors against the same 4x4 matrix, preload the matrix into XMTRX, then use `shz_xmtrx_transform_vec3()`.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:679`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L679)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"

## See also

[`shz_mat4x4_transform_vec4`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec4/), [`shz_xmtrx_transform_vec3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec3/)


---
# shz_mat4x4_transform_vec4_transpose

Source: https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec4_transpose/

```c
SHZ_INLINE shz_vec4_t shz_mat4x4_transform_vec4_transpose(const shz_mat4x4_t* m, shz_vec4_t v) SHZ_NOEXCEPT;
```

Transforms a 4D vector the the transpose of a 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `m` | `const shz_mat4x4_t *` |  |
| `v` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Details

This is a routine specializing in one-off transforms of a **single** 4D vector by the transpose of a **single** 4x4 matrix. It should be faster than going through XMTRX.

## Notes

- For batch transforming multiple 4D vectors against the transpose of the same 4x4 matrix, preload the matrix into XMTRX, take its transpose with `shz_xmtrx_transpose()`, then use `shz_xmtrx_transform_vec4()`.

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:738`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L738)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"

## See also

[`shz_xmtrx_transpose`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transpose/), [`shz_xmtrx_transform_vec4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec4/)


---
# shz_mat4x4_transform_vec4

Source: https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec4/

```c
SHZ_INLINE shz_vec4_t shz_mat4x4_transform_vec4(const shz_mat4x4_t* mat, shz_vec4_t in) SHZ_NOEXCEPT;
```

Transforms a 4D vector by a 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |
| `in` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Details

This is a routine specializing in one-off transforms of a *single* 4D vector by a *single* 4x4 matrix. It should be faster than going through XMTRX.

## Notes

- For batch transforming multiple 4D vectors against the same 4x4 matrix, preload the matrix into XMTRX, then use `shz_xmtrx_transform_vec4()`.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:693`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L693)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Transforming"

## See also

[`shz_mat4x4_transform_vec3`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec3/), [`shz_xmtrx_transform_vec4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec4/)


---
# shz_mat4x4_translate_reverse

Source: https://sh4zam.com/api/matrix/shz_mat4x4_translate_reverse/

```c
SHZ_INLINE void shz_mat4x4_translate_reverse(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Pre-multiplies and accumulates the given matrix onto the 3D translation matrix with the given components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routin clobbers XMTRX.

## Naming and requirements

- `_reverse`: Reversed multiplication order (pre-multiply instead of post-multiply). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::translate_reverse`](https://sh4zam.com/api/cpp/mat4x4/#translate_reverse)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:614`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L614)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Reverse GL Transformations"


---
# shz_mat4x4_translate

Source: https://sh4zam.com/api/matrix/shz_mat4x4_translate/

> Multiplies and accumulates mat by a 3D translation matrix with the given components

```c
SHZ_INLINE void shz_mat4x4_translate(shz_mat4x4_t* mat, float x, float y, float z) SHZ_NOEXCEPT;
```

Multiplies and accumulates `mat` by a 3D translation matrix with the given components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `shz_mat4x4_t *` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Notes

- glTranslatef() equivalent.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::mat4x4::translate`](https://sh4zam.com/api/cpp/mat4x4/#translate)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:545`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L545)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "GL Transformations"


---
# shz_mat4x4_transpose

Source: https://sh4zam.com/api/matrix/shz_mat4x4_transpose/

> Stores the transpose of mat within out

```c
SHZ_INLINE void shz_mat4x4_transpose(const shz_mat4x4_t* mat, shz_mat4x4_t* out) SHZ_NOEXCEPT;
```

Stores the transpose of `mat` within `out`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |
| `out` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_matrix.h:812`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L812)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Miscellaneous"


---
# shz_mat4x4

Source: https://sh4zam.com/api/matrix/shz_mat4x4/

> Alternate shz_mat4x4_t C typedef for those who hate POSIX style

```c
typedef shz_mat4x4_t shz_mat4x4;
```

Alternate [`shz_mat4x4_t`](https://sh4zam.com/api/matrix/shz_mat4x4_t/) C typedef for those who hate POSIX style.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_matrix.h:80`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_matrix.h#L80)
- **Module:** [Matrix](https://sh4zam.com/api/matrix/), section "Types"


---
# Memory API

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

> Routines for copying memory, store queues, cache operations and prefetching

This API provides special instruction intrinsics, cache operations and `memcpy()`-type routines. `shz_memcpy()` is a generic drop-in `memcpy()` replacement; when you know and control the alignment and batch sizes, you can micro-optimize by calling the most specific specialization instead. `sq_` routines write through the SH4 store queues, and `_xmtrx` routines use the XMTRX register bank as a scratch buffer, clobbering it. `memcpy()`-like routines will typically always check for proper alignment and size increments of parameters using `assert()`, so make sure to build a release build (`-DNDEBUG`) for maximal gainz when not debugging. There is no `shz_memset()` yet; it is listed as a TODO in the header.

- **C header:** `#include <sh4zam/shz_mem.h>`
- **C++ header:** `#include <sh4zam/shz_mem.hpp>`
- **Symbols:** 23

## Suffixes

Suffixes used in this module. The full list is in [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/).

- `sq_`: Writes through the SH4 store queues (burst writes to memory or the PVR).
- `_xmtrx`: Uses the XMTRX register bank as a 64-byte scratch buffer. Clobbers XMTRX.
- `memcpyN`: A numeric suffix on `memcpy`/`memset` names the element granularity or count, e.g. `shz_memcpy32_1` copies exactly one 32-byte line.

## C stdlib Replacements

Routine replacing the C standard library copy/set API.

| Symbol | Description |
| --- | --- |
| [`shz_memcpy`](https://sh4zam.com/api/memory/shz_memcpy/) | Generic drop-in fast memcpy() replacement. |
| [`shz_memmove`](https://sh4zam.com/api/memory/shz_memmove/) | Generic drop-in fast memmove() replacement. |

## Specializations

Specialized routines for specific sizes + alignments.

| Symbol | Description |
| --- | --- |
| [`shz_memcpy1`](https://sh4zam.com/api/memory/shz_memcpy1/) | Copies an unaligned buffer to another one byte at a time. |
| [`shz_memcpy2`](https://sh4zam.com/api/memory/shz_memcpy2/) | Copies from one 2-byte aligned buffer to another two bytes at a time. |
| [`shz_memcpy4`](https://sh4zam.com/api/memory/shz_memcpy4/) | Copies a from one 4-byte aligned buffer to another 4 bytes at a time. |
| [`shz_memcpy8`](https://sh4zam.com/api/memory/shz_memcpy8/) | Copies a from one 8-byte aligned buffer to another 8 bytes at a time. |
| [`shz_memset8`](https://sh4zam.com/api/memory/shz_memset8/) | Assigns the given 8-byte `value` to the `bytes` in `dst`. |
| [`shz_memcpy32`](https://sh4zam.com/api/memory/shz_memcpy32/) | Copies `bytes` from the `src` to the `dst` buffer in 32-byte chunks. |
| [`shz_sq_memcpy32`](https://sh4zam.com/api/memory/shz_sq_memcpy32/) | Copies `bytes` from `src` to `dst` in 32-byte chunks, using the Store Queues. |
| [`shz_sq_memcpy32_xmtrx`](https://sh4zam.com/api/memory/shz_sq_memcpy32_xmtrx/) | Copies `bytes` from `src` to `dst` in 32-byte chunks, using the Store Queues and XMTRX. |
| [`shz_memcpy64`](https://sh4zam.com/api/memory/shz_memcpy64/) | Specialized memcpy() variant for copying multiples of 64-bytes. |
| [`shz_memcpy128`](https://sh4zam.com/api/memory/shz_memcpy128/) | Specialized memcpy() variant for copying multiples of 128 bytes. |

## Constant-sized Operations

Specialized routines for operating on statically sized buffers.

| Symbol | Description |
| --- | --- |
| [`shz_memcpy2_8`](https://sh4zam.com/api/memory/shz_memcpy2_8/) | Copies 8 shorts from `src` to `dst`. |
| [`shz_memcpy2_16`](https://sh4zam.com/api/memory/shz_memcpy2_16/) | Copies 16 shorts from `src` to `dst`. |
| [`shz_memset2_16`](https://sh4zam.com/api/memory/shz_memset2_16/) | Sets the values of the 16 shorts pointed to by `dst` to the given `value`. |
| [`shz_memcpy4_16`](https://sh4zam.com/api/memory/shz_memcpy4_16/) | Copies 16 4-byte, long values from `src` to `dst`. |
| [`shz_memcpy32_1`](https://sh4zam.com/api/memory/shz_memcpy32_1/) | Copies 32 bytes from `p1` to `p2` as a single chunk. |
| [`shz_memswap32_1`](https://sh4zam.com/api/memory/shz_memswap32_1/) | Swaps the values within the given 32-byte buffers. |
| [`shz_memswap32_1_xmtrx`](https://sh4zam.com/api/memory/shz_memswap32_1_xmtrx/) | Swaps the values within the given 32-byte buffers, using XMTRX. |
| [`shz_sq_memcpy32_1`](https://sh4zam.com/api/memory/shz_sq_memcpy32_1/) | Copies `src` to `dst` in a single 32-byte transaction using the Store Queues. |
| [`shz_sq_memcpy32_1_xmtrx`](https://sh4zam.com/api/memory/shz_sq_memcpy32_1_xmtrx/) | Copies `src` to `dst` in a single 32-byte transaction using the Store Queues and XMTRX. |
| [`shz_dcache_alloc_line`](https://sh4zam.com/api/memory/shz_dcache_alloc_line/) | Intrinsic around the SH4 `MOVCA.L` instruction. |

## Macros

| Symbol | Description |
| --- | --- |
| [`SHZ_PREFETCH`](https://sh4zam.com/api/memory/SHZ_PREFETCH/) | Used to prepopulate the cache line mapping to the given address, before it is used. |


---
# shz_dcache_alloc_line

Source: https://sh4zam.com/api/memory/shz_dcache_alloc_line/

> Intrinsic around the SH4 MOVCA.L instruction

```c
SHZ_INLINE void shz_dcache_alloc_line(void* src) SHZ_NOEXCEPT;
```

Intrinsic around the SH4 `MOVCA.L` instruction.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `src` | `void *` |  |

## Returns

Nothing (`void`).

## Details

Preallocates the cache-line containing `src`.

Zero-initializes all 32-bytes within the `src` cache-line, setting the valid bit to `1`.

## Availability

- **C++ equivalent:** [`shz::dcache_alloc_line`](https://sh4zam.com/api/cpp/#shzdcache_alloc_line)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:365`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L365)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Constant-sized Operations"


---
# shz_memcpy

Source: https://sh4zam.com/api/memory/shz_memcpy/

```c
SHZ_INLINE void* shz_memcpy( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes) SHZ_NOEXCEPT;
```

Generic drop-in fast memcpy() replacement.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Details

Copies `bytes` from `src` to `dst`, determining the most efficient specialization to call into at run-time, returning `dst`.

There are no alignment or size requirements for this routine, but it is specifically optimized for 2-, 4-, 8-, and 32-byte alignments, with bigger alignments bringing bigger gainz.

## Notes

- When you know of and can control the `src` and `dst` alignments and batch sizes, you can micro-optimize by calling into the most specific memcpy() specialization for your given scenario, over just using this generic implementation, which must choose which one to use at run-time.

## Warnings

- `dst` and `src` buffers should not be overlapping.

## Availability

- **C++ equivalent:** [`shz::memcpy`](https://sh4zam.com/api/cpp/#shzmemcpy)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:75`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L75)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "C stdlib Replacements"

## See also

[`shz_memcpy1`](https://sh4zam.com/api/memory/shz_memcpy1/), [`shz_memcpy2`](https://sh4zam.com/api/memory/shz_memcpy2/), [`shz_memcpy4`](https://sh4zam.com/api/memory/shz_memcpy4/), [`shz_memcpy8`](https://sh4zam.com/api/memory/shz_memcpy8/), [`shz_memcpy32`](https://sh4zam.com/api/memory/shz_memcpy32/), [`shz_memcpy64`](https://sh4zam.com/api/memory/shz_memcpy64/), [`shz_memcpy128`](https://sh4zam.com/api/memory/shz_memcpy128/)


---
# shz_memcpy1

Source: https://sh4zam.com/api/memory/shz_memcpy1/

```c
SHZ_INLINE void* shz_memcpy1( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes) SHZ_NOEXCEPT;
```

Copies an unaligned buffer to another one byte at a time.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Details

The `dst` pointer is returned.

## Notes

- Typically, unless you know you are copying a tiny number of definitely unaligned bytes, you want to use `shz_memcpy()`, which automatically handles arbitrary alignment for you, potentially more efficiently than copying byte-by-byte.

## Warnings

- `dst` and `src` buffers should not be overlapping.

## Availability

- **C++ equivalent:** [`shz::memcpy1`](https://sh4zam.com/api/cpp/#shzmemcpy1)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:114`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L114)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Specializations"

## See also

[`shz_memcpy`](https://sh4zam.com/api/memory/shz_memcpy/)


---
# shz_memcpy2_8

Source: https://sh4zam.com/api/memory/shz_memcpy2_8/

> Copies 8 shorts from src to dst

```c
SHZ_INLINE void shz_memcpy2_8( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src) SHZ_NOEXCEPT;
```

Copies 8 shorts from `src` to `dst`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |

## Returns

Nothing (`void`).

## Warnings

- `src` and `dst` buffers must not overlap.
- `dst` and `src` must both be aligned by at least two bytes.

## Availability

- **C++ equivalent:** [`shz::memcpy2_8`](https://sh4zam.com/api/cpp/#shzmemcpy2_8)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:273`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L273)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Constant-sized Operations"


---
# shz_memcpy2_16

Source: https://sh4zam.com/api/memory/shz_memcpy2_16/

> Copies 16 shorts from src to dst

```c
SHZ_INLINE void shz_memcpy2_16( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src) SHZ_NOEXCEPT;
```

Copies 16 shorts from `src` to `dst`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |

## Returns

Nothing (`void`).

## Warnings

- `src` and `dst` buffers must not overlap.
- `dst` and `src` must both be aligned by at least two bytes.

## Availability

- **C++ equivalent:** [`shz::memcpy2_16`](https://sh4zam.com/api/cpp/#shzmemcpy2_16)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:284`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L284)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Constant-sized Operations"


---
# shz_memcpy2

Source: https://sh4zam.com/api/memory/shz_memcpy2/

```c
SHZ_INLINE void* shz_memcpy2( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes) SHZ_NOEXCEPT;
```

Copies from one 2-byte aligned buffer to another two bytes at a time.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Details

The `dst` pointer is returned.

## Warnings

- `dst` and `src` must both be aligned by at least 2 bytes, and `bytes` must be a multiple of 2.
- `dst` and `src` buffers should not be overlapping.

## Availability

- **C++ equivalent:** [`shz::memcpy2`](https://sh4zam.com/api/cpp/#shzmemcpy2)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:129`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L129)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Specializations"


---
# shz_memcpy4_16

Source: https://sh4zam.com/api/memory/shz_memcpy4_16/

> Copies 16 4-byte, long values from src to dst

```c
SHZ_INLINE void shz_memcpy4_16( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src) SHZ_NOEXCEPT;
```

Copies 16 4-byte, long values from `src` to `dst`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |

## Returns

Nothing (`void`).

## Warnings

- `src` and `dst` buffers must not overlap.
- The `src` and `dst` buffers must both be at least 4-byte aligned.

## Availability

- **C++ equivalent:** [`shz::memcpy4_16`](https://sh4zam.com/api/cpp/#shzmemcpy4_16)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:302`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L302)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Constant-sized Operations"


---
# shz_memcpy4

Source: https://sh4zam.com/api/memory/shz_memcpy4/

```c
SHZ_INLINE void* shz_memcpy4( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes) SHZ_NOEXCEPT;
```

Copies a from one 4-byte aligned buffer to another 4 bytes at a time.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Details

The `dst` buffer is returned.

## Warnings

- `dst` and `src` must both be aligned by at least 4 bytes, and `bytes` must be a multiple of 4.
- `dst` and `src` buffers should not be overlapping.

## Availability

- **C++ equivalent:** [`shz::memcpy4`](https://sh4zam.com/api/cpp/#shzmemcpy4)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:144`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L144)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Specializations"


---
# shz_memcpy8

Source: https://sh4zam.com/api/memory/shz_memcpy8/

```c
SHZ_INLINE void* shz_memcpy8( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes) SHZ_NOEXCEPT;
```

Copies a from one 8-byte aligned buffer to another 8 bytes at a time.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Details

The `dst` buffer is returned.

## Warnings

- `dst` and `src` must both be aligned by at least 8 bytes, and `bytes` must be a multiple of 8.
- `src` and `dst` should not overlap.

## Availability

- **C++ equivalent:** [`shz::memcpy8`](https://sh4zam.com/api/cpp/#shzmemcpy8)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:159`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L159)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Specializations"


---
# shz_memcpy32_1

Source: https://sh4zam.com/api/memory/shz_memcpy32_1/

> Copies 32 bytes from p1 to p2 as a single chunk

```c
SHZ_INLINE void shz_memcpy32_1( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src) SHZ_NOEXCEPT;
```

Copies 32 bytes from `p1` to `p2` as a single chunk.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |

## Returns

Nothing (`void`).

## Warnings

- `dst` must be 32-byte aligned, while `src` can be only 8-byte aligned.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:310`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L310)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Constant-sized Operations"


---
# shz_memcpy32

Source: https://sh4zam.com/api/memory/shz_memcpy32/

> Copies bytes from the src to the dst buffer in 32-byte chunks

```c
SHZ_INLINE void* shz_memcpy32( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes) SHZ_NOEXCEPT;
```

Copies `bytes` from the `src` to the `dst` buffer in 32-byte chunks.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Details

Transfers from 8-byte aligned buffer, `src` to 32-byte aligned buffer, `dst`, 32 bytes at a time. Returns the `dst` address.

## Notes

- This is the quickest way to move 32-byte chunks of data around *within memory*, but the `shz_sq_memcpy32()` will be faster when writing through the cache to external memory.

## Warnings

- `dst` must be 32-byte aligned, while `src` can be only 8-byte aligned. `bytes` must be a multiple of 32.
- `src` and `dst` buffers must not overlap.

## Availability

- **C++ equivalent:** [`shz::memcpy32`](https://sh4zam.com/api/cpp/#shzmemcpy32)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:189`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L189)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Specializations"

## See also

[`shz_sq_memcpy32`](https://sh4zam.com/api/memory/shz_sq_memcpy32/)


---
# shz_memcpy64

Source: https://sh4zam.com/api/memory/shz_memcpy64/

```c
SHZ_INLINE void* shz_memcpy64( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes) SHZ_NOEXCEPT;
```

Specialized memcpy() variant for copying multiples of 64-bytes.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Details

Copies a from an 8-byte aligned buffer to a 32-byte aligned buffer, 64 bytes at a time. Returns the `dst` address.

## Warnings

- `src` and `dst` buffers must not overlap.
- `dst` must be 32-byte aligned, while `src` can be only 8-byte aligned. `bytes` must be a multiple of 64.

## Availability

- **C++ equivalent:** [`shz::memcpy64`](https://sh4zam.com/api/cpp/#shzmemcpy64)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:238`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L238)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Specializations"


---
# shz_memcpy128

Source: https://sh4zam.com/api/memory/shz_memcpy128/

```c
SHZ_INLINE void* shz_memcpy128( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes) SHZ_NOEXCEPT;
```

Specialized memcpy() variant for copying multiples of 128 bytes.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Details

Copies a from an 8-byte aligned buffer to a 32-byte aligned buffer, 128 bytes at a time. Returns the `dst` address.

## Warnings

- `src` and `dst` buffers must not overlap.
- `dst` must be 32-byte aligned, while `src` can be only 8-byte aligned. `bytes` must be a multiple of 128.

## Availability

- **C++ equivalent:** [`shz::memcpy128`](https://sh4zam.com/api/cpp/#shzmemcpy128)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:254`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L254)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Specializations"


---
# shz_memmove

Source: https://sh4zam.com/api/memory/shz_memmove/

```c
SHZ_INLINE void* shz_memmove(void* dst, const void* src, size_t bytes) SHZ_NOEXCEPT;
```

Generic drop-in fast memmove() replacement.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *` |  |
| `src` | `const void *` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Details

Copies `bytes` from `src` to `dst`, determining the most efficient specialization to call into at run-time, return `dst`. The source and destination buffers are allowed to overlap, making this routine slightly less efficient, but more versatile than `shz_memcpy()`.

There is no alignment or size requirement for this routine.

## Availability

- **C++ equivalent:** [`shz::memmove`](https://sh4zam.com/api/cpp/#shzmemmove)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:90`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L90)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "C stdlib Replacements"

## See also

[`shz_memcpy`](https://sh4zam.com/api/memory/shz_memcpy/)


---
# shz_memset2_16

Source: https://sh4zam.com/api/memory/shz_memset2_16/

> Sets the values of the 16 shorts pointed to by dst to the given value

```c
SHZ_INLINE void shz_memset2_16(void* dst, uint16_t value) SHZ_NOEXCEPT;
```

Sets the values of the 16 shorts pointed to by `dst` to the given `value`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *` |  |
| `value` | `uint16_t` |  |

## Returns

Nothing (`void`).

## Warnings

- `dst` must be aligned by at least two bytes.

## Availability

- **C++ equivalent:** [`shz::memset2_16`](https://sh4zam.com/api/cpp/#shzmemset2_16)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:292`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L292)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Constant-sized Operations"


---
# shz_memset8

Source: https://sh4zam.com/api/memory/shz_memset8/

> Assigns the given 8-byte value to the bytes in dst

```c
SHZ_INLINE void* shz_memset8(void* dst, uint64_t value, size_t bytes) SHZ_NOEXCEPT;
```

Assigns the given 8-byte `value` to the `bytes` in `dst`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *` |  |
| `value` | `uint64_t` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Warnings

- `dst` should be at least 8-byte aligned, and `bytes` should be a multiple of 8!

## Availability

- **C++ equivalent:** [`shz::memset8`](https://sh4zam.com/api/cpp/#shzmemset8)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:169`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L169)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Specializations"


---
# shz_memswap32_1_xmtrx

Source: https://sh4zam.com/api/memory/shz_memswap32_1_xmtrx/

```c
SHZ_INLINE void shz_memswap32_1_xmtrx(void* SHZ_RESTRICT p1, void* SHZ_RESTRICT p2) SHZ_NOEXCEPT;
```

Swaps the values within the given 32-byte buffers, using XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `p1` | `void *SHZ_RESTRICT` |  |
| `p2` | `void *SHZ_RESTRICT` |  |

## Returns

Nothing (`void`).

## Details

Equivalent to `shz_memcpy32_1()`, except copying is done through XMTRX.

## Warnings

- This routine clobbers XMTRX!

## Naming and requirements

- `_xmtrx`: Uses the XMTRX register bank as a 64-byte scratch buffer. Clobbers XMTRX. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::memswap32_1_xmtrx`](https://sh4zam.com/api/cpp/#shzmemswap32_1_xmtrx)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:328`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L328)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Constant-sized Operations"


---
# shz_memswap32_1

Source: https://sh4zam.com/api/memory/shz_memswap32_1/

```c
SHZ_INLINE void shz_memswap32_1(void* SHZ_RESTRICT p1, void* SHZ_RESTRICT p2) SHZ_NOEXCEPT;
```

Swaps the values within the given 32-byte buffers.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `p1` | `void *SHZ_RESTRICT` |  |
| `p2` | `void *SHZ_RESTRICT` |  |

## Returns

Nothing (`void`).

## Warnings

- `p1` and `p2` must be at least 8-byte aligned.

## Availability

- **C++ equivalent:** [`shz::memswap32_1`](https://sh4zam.com/api/cpp/#shzmemswap32_1)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:318`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L318)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Constant-sized Operations"


---
# SHZ_PREFETCH

Source: https://sh4zam.com/api/memory/SHZ_PREFETCH/

```c
#define SHZ_PREFETCH(ptr) SHZ_PREFETCH_(ptr)
```

Used to prepopulate the cache line mapping to the given address, before it is used.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ptr` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_mem.h:45`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L45)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Macros"


---
# shz_sq_memcpy32_1_xmtrx

Source: https://sh4zam.com/api/memory/shz_sq_memcpy32_1_xmtrx/

> Copies src to dst in a single 32-byte transaction using the Store Queues and XMTRX

```c
SHZ_INLINE void* shz_sq_memcpy32_1_xmtrx( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src) SHZ_NOEXCEPT;
```

Copies `src` to `dst` in a single 32-byte transaction using the Store Queues and XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |

## Returns

`void *`

## Details

Equivalent to `shz_sq_memcpy32_1()`, except copying is done through XMTRX.

## Warnings

- This routine clobberx XMTRX.

## Naming and requirements

- `_xmtrx`: Uses the XMTRX register bank as a 64-byte scratch buffer. Clobbers XMTRX. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `sq_`: Writes through the SH4 store queues (burst writes to memory or the PVR). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::sq_memcpy32_1_xmtrx`](https://sh4zam.com/api/cpp/#shzsq_memcpy32_1_xmtrx)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:355`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L355)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Constant-sized Operations"

## See also

[`shz_memcpy32`](https://sh4zam.com/api/memory/shz_memcpy32/)


---
# shz_sq_memcpy32_1

Source: https://sh4zam.com/api/memory/shz_sq_memcpy32_1/

> Copies src to dst in a single 32-byte transaction using the Store Queues

```c
SHZ_INLINE void* shz_sq_memcpy32_1( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src) SHZ_NOEXCEPT;
```

Copies `src` to `dst` in a single 32-byte transaction using the Store Queues.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |

## Returns

`void *`

## Notes

- The Store Queues bypass the SH4's data-cache! They are typically used to transfer to *external memory* and are slower for memory-to-memory transactions.

## Warnings

- `dst` must be at least 4-byte aligned, while `src` must be at least 8-byte aligned.

## Naming and requirements

- `sq_`: Writes through the SH4 store queues (burst writes to memory or the PVR). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::sq_memcpy32_1`](https://sh4zam.com/api/cpp/#shzsq_memcpy32_1)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:342`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L342)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Constant-sized Operations"

## See also

[`shz_memcpy32`](https://sh4zam.com/api/memory/shz_memcpy32/)


---
# shz_sq_memcpy32_xmtrx

Source: https://sh4zam.com/api/memory/shz_sq_memcpy32_xmtrx/

> Copies bytes from src to dst in 32-byte chunks, using the Store Queues and XMTRX

```c
SHZ_INLINE void* shz_sq_memcpy32_xmtrx( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes) SHZ_NOEXCEPT;
```

Copies `bytes` from `src` to `dst` in 32-byte chunks, using the Store Queues and XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Details

Equiavalent to `shz_sq_memcpy32()`, except copying is done through XMTRX.

## Warnings

- This routine clobbers XMTRX.

## Naming and requirements

- `_xmtrx`: Uses the XMTRX register bank as a 64-byte scratch buffer. Clobbers XMTRX. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `sq_`: Writes through the SH4 store queues (burst writes to memory or the PVR). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::sq_memcpy32_xmtrx`](https://sh4zam.com/api/cpp/#shzsq_memcpy32_xmtrx)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:222`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L222)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Specializations"


---
# shz_sq_memcpy32

Source: https://sh4zam.com/api/memory/shz_sq_memcpy32/

> Copies bytes from src to dst in 32-byte chunks, using the Store Queues

```c
SHZ_INLINE void* shz_sq_memcpy32( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes) SHZ_NOEXCEPT;
```

Copies `bytes` from `src` to `dst` in 32-byte chunks, using the Store Queues.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `dst` | `void *SHZ_RESTRICT` |  |
| `src` | `const void *SHZ_RESTRICT` |  |
| `bytes` | `size_t` |  |

## Returns

`void *`

## Details

Transfers from 8-byte aligned buffer, `src` to 4-byte aligned address, `dst`, 32 bytes at a time, writing through the cache, using the SH4's Store Queues. Returns the `dst` address.

## Notes

- This is the quickest way to move 32-byte chunks of data to *external memory*. When copying to cached memory, you must invalidate the cache lines containing `dst` before initiating the copy... Which means this routine becomes slower than doing memory-to-memory copies with `shz_memcpy32()`.

## Warnings

- `src` must be at least 8-byte aligned, while `dst` can be only 4-byte aligned. `bytes` must be a multiple of 32.

## Naming and requirements

- `sq_`: Writes through the SH4 store queues (burst writes to memory or the PVR). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::sq_memcpy32`](https://sh4zam.com/api/cpp/#shzsq_memcpy32)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_mem.h:211`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_mem.h#L211)
- **Module:** [Memory](https://sh4zam.com/api/memory/), section "Specializations"

## See also

[`shz_memcpy32`](https://sh4zam.com/api/memory/shz_memcpy32/), [`shz_sq_memcpy32_1`](https://sh4zam.com/api/memory/shz_sq_memcpy32_1/)


---
# Quaternion API

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

> Routines for quaternion math

This module contains the public type(s) and interface providing the quaternion math API. Quaternions are a mathematical structure representing a rotation about a single arbitrary axis. `shz_quat_t` is stored in `<W, X, Y, Z>` order, with W first, and the identity quaternion is (1, 0, 0, 0). Interpolation covers `lerp`, `nlerp`, `slerp` and `squad`, and C++ users get the same API on `shz::quat`.

- **C header:** `#include <sh4zam/shz_quat.h>`
- **C++ header:** `#include <sh4zam/shz_quat.hpp>`
- **C++ types:** [`shz::quat`](https://sh4zam.com/api/cpp/quat/)
- **Symbols:** 47

## 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.
- `_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.

## Initialization

Routines for creating and initializing quaternions.

| Symbol | Description |
| --- | --- |
| [`shz_quat_init`](https://sh4zam.com/api/quat/shz_quat_init/) | Initializes and returns a new quaternion with the given components, in WXYZ order. |
| [`shz_quat_identity`](https://sh4zam.com/api/quat/shz_quat_identity/) | Initializes and returns an identity quaternion. |
| [`shz_quat_equal`](https://sh4zam.com/api/quat/shz_quat_equal/) | Returns true if the two given quaternions are considered equal based on either absolute or relative tolerance. |
| [`shz_quat_from_angles_xyz`](https://sh4zam.com/api/quat/shz_quat_from_angles_xyz/) | Initializes and returns a quaternion with the given X-Y-Z rotations in radians. |
| [`shz_quat_from_rotation_xyz`](https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz/) | Returns the quaternion of the rotation `shz_xmtrx_init_rotation_xyz()` builds, from angles in radians. |
| [`shz_quat_from_rotation_zyx`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx/) | Returns the quaternion of the rotation `shz_xmtrx_init_rotation_zyx()` builds, Qz \* Qy \* Qx, from angles in radians. |
| [`shz_quat_from_rotation_zxy`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy/) | Returns the quaternion of the rotation `shz_xmtrx_init_rotation_zxy()` builds, Qz \* Qx \* Qy, from angles in radians. |
| [`shz_quat_from_rotation_yxz`](https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz/) | Returns the quaternion of the rotation `shz_xmtrx_init_rotation_yxz()` builds, Qy \* Qx \* Qz, from angles in radians. |
| [`shz_quat_from_rotation_xyz_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz_u16/) | Equivalent to `shz_quat_from_rotation_xyz()`, with 16-bit binary angles (65536 per turn, the FSCA unit). |
| [`shz_quat_from_rotation_zyx_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx_u16/) | Equivalent to `shz_quat_from_rotation_zyx()`, with 16-bit binary angles. |
| [`shz_quat_from_rotation_zxy_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy_u16/) | Equivalent to `shz_quat_from_rotation_zxy()`, with 16-bit binary angles. |
| [`shz_quat_from_rotation_yxz_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz_u16/) | Equivalent to `shz_quat_from_rotation_yxz()`, with 16-bit binary angles. |
| [`shz_quat_from_axis_angle`](https://sh4zam.com/api/quat/shz_quat_from_axis_angle/) | Initializes and returns a quaternion representing a rotation of `angle` radians about the given `axis`. |
| [`shz_quat_from_look_axis`](https://sh4zam.com/api/quat/shz_quat_from_look_axis/) | Creates a quaternion looking in the given direction with the given reference direction. |
| [`shz_quat_from_rotated_axis`](https://sh4zam.com/api/quat/shz_quat_from_rotated_axis/) | Returns the quaternion representing the rotation from axis `v1` to `v2`. |
| [`shz_quat_lerp`](https://sh4zam.com/api/quat/shz_quat_lerp/) | Returns the quaternion that is linearly interpolating `a` to `b`, by a t factor of `0.0f-1.0f`. |
| [`shz_quat_nlerp`](https://sh4zam.com/api/quat/shz_quat_nlerp/) | Equivalent to `shz_quat_lerp()`, except that the resulting quaternion is normalized. |
| [`shz_quat_slerp`](https://sh4zam.com/api/quat/shz_quat_slerp/) | Returns the quaternion that is spherically linearly interpolating `a` to `b`, by a `t` factor of `0.0f-1.0f`. |
| [`shz_quat_squad`](https://sh4zam.com/api/quat/shz_quat_squad/) | Evaluates a smooth cubic spherical interpolation (SQUAD) at parameter `t`. |

## Properties

Routines returning derived values from a quaternion.

| Symbol | Description |
| --- | --- |
| [`shz_quat_angle`](https://sh4zam.com/api/quat/shz_quat_angle/) | Returns the angle of rotation from the given quaternion. |
| [`shz_quat_axis`](https://sh4zam.com/api/quat/shz_quat_axis/) | Returns the axis of rotation from the given quaternion. |
| [`shz_quat_angle_x`](https://sh4zam.com/api/quat/shz_quat_angle_x/) | Returns the angle of rotation the quaternion represents about the X axis in radians. |
| [`shz_quat_angle_y`](https://sh4zam.com/api/quat/shz_quat_angle_y/) | Returns the angle of rotation the quaternion represents about the Y axis in radians. |
| [`shz_quat_angle_z`](https://sh4zam.com/api/quat/shz_quat_angle_z/) | Returns the angle of rotation the quaternion represents about the Z axis in radians. |
| [`shz_quat_to_axis_angle`](https://sh4zam.com/api/quat/shz_quat_to_axis_angle/) | Returns both the axis and angle of rotation simultaneously (faster if both are needed) from the given quaternion. |
| [`shz_quat_to_angles_xyz`](https://sh4zam.com/api/quat/shz_quat_to_angles_xyz/) | Returns the roll, pitch, and yaw angles of rotation represented by the given quaternion. |
| [`shz_quat_magnitude_sqr`](https://sh4zam.com/api/quat/shz_quat_magnitude_sqr/) | Returns the squared magnitude of the given quaternion. |
| [`shz_quat_magnitude`](https://sh4zam.com/api/quat/shz_quat_magnitude/) | Returns the magnitude of the given quaternion. |
| [`shz_quat_magnitude_inv`](https://sh4zam.com/api/quat/shz_quat_magnitude_inv/) | Returns the inverse magnitude of the given quaternion. |

## Modifiers

Routines for returning new quaternions derived from existing ones.

| Symbol | Description |
| --- | --- |
| [`shz_quat_normalize`](https://sh4zam.com/api/quat/shz_quat_normalize/) | Returns the normalized form of the given quaternion. |
| [`shz_quat_normalize_safe`](https://sh4zam.com/api/quat/shz_quat_normalize_safe/) | SAFELY returns the normalized form of the given quaternion. |
| [`shz_quat_conjugate`](https://sh4zam.com/api/quat/shz_quat_conjugate/) | Returns the conjugate of the given quaternion. |
| [`shz_quat_inv`](https://sh4zam.com/api/quat/shz_quat_inv/) | Returns the inverse of the given quaternion. |
| [`shz_quat_neg`](https://sh4zam.com/api/quat/shz_quat_neg/) | Returns the negation of the given quaternion. |

## Arithmetic

Routines performing calculations with quaternions.

| Symbol | Description |
| --- | --- |
| [`shz_quat_add`](https://sh4zam.com/api/quat/shz_quat_add/) | Returns the quaternion produced from adding each component of the given quaternions. |
| [`shz_quat_sub`](https://sh4zam.com/api/quat/shz_quat_sub/) | Returns the quaternion produced from subtracting each component of quaternion `p` from quaterion `q`. |
| [`shz_quat_scale`](https://sh4zam.com/api/quat/shz_quat_scale/) | Scales the components of the given quaternion by the given factor. |
| [`shz_quat_mult`](https://sh4zam.com/api/quat/shz_quat_mult/) | Multiplies the two quaternions, returning the result as a new quaternion. |
| [`shz_quat_div`](https://sh4zam.com/api/quat/shz_quat_div/) | Divides quaternion `p` by quaternion `q` (multiplying by its inverse), returning the resulting quaternion. |
| [`shz_quat_dot`](https://sh4zam.com/api/quat/shz_quat_dot/) | Returns the dot product of the two quaternions. |
| [`shz_quat_dot2`](https://sh4zam.com/api/quat/shz_quat_dot2/) | Returns the two dot products taken between the `l` quaternion and the `r1` and `r2` quaternions. |
| [`shz_quat_dot3`](https://sh4zam.com/api/quat/shz_quat_dot3/) | Returns the two dot products taken between the `l` quaternion and the `r1`, `r2`, and `r3` quaternions. |

## Miscellaneous

Other types of quaternion operations.

| Symbol | Description |
| --- | --- |
| [`shz_quat_angle_between`](https://sh4zam.com/api/quat/shz_quat_angle_between/) | Returns the angle in radians between the rotations represented by quaternions `q` and `p`. |
| [`shz_quat_rotate_towards`](https://sh4zam.com/api/quat/shz_quat_rotate_towards/) | Rotates quaternion `from` towards quaternion `to` by at most `max_angle` radians. |

## Transformations

Routines for applying quaternion transforms.

| Symbol | Description |
| --- | --- |
| [`shz_quat_transform_vec3`](https://sh4zam.com/api/quat/shz_quat_transform_vec3/) | Rotates a vector by the given quaternion. |

## Types

| Symbol | Description |
| --- | --- |
| [`shz_quat_t`](https://sh4zam.com/api/quat/shz_quat_t/) | Represents a 3D quaternion. |
| [`shz_quat`](https://sh4zam.com/api/quat/shz_quat/) | Alternate [`shz_quat_t`](https://sh4zam.com/api/quat/shz_quat_t/) C typedef for those who hate POSIX style. |


---
# shz_quat_add

Source: https://sh4zam.com/api/quat/shz_quat_add/

```c
SHZ_INLINE shz_quat_t shz_quat_add(shz_quat_t q, shz_quat_t p) SHZ_NOEXCEPT;
```

Returns the quaternion produced from adding each component of the given quaternions.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |
| `p` | `shz_quat_t` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::add`](https://sh4zam.com/api/cpp/quat/#add)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:215`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L215)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Arithmetic"


---
# shz_quat_angle_between

Source: https://sh4zam.com/api/quat/shz_quat_angle_between/

> Returns the angle in radians between the rotations represented by quaternions q and p

```c
SHZ_INLINE float shz_quat_angle_between(shz_quat_t q, shz_quat_t p) SHZ_NOEXCEPT;
```

Returns the angle in radians between the rotations represented by quaternions `q` and `p`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |
| `p` | `shz_quat_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::quat::angle_between`](https://sh4zam.com/api/cpp/quat/#angle_between)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:246`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L246)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Miscellaneous"


---
# shz_quat_angle_x

Source: https://sh4zam.com/api/quat/shz_quat_angle_x/

```c
SHZ_INLINE float shz_quat_angle_x(shz_quat_t q) SHZ_NOEXCEPT;
```

Returns the angle of rotation the quaternion represents about the X axis in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::quat::angle_x`](https://sh4zam.com/api/cpp/quat/#angle_x)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:159`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L159)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Properties"


---
# shz_quat_angle_y

Source: https://sh4zam.com/api/quat/shz_quat_angle_y/

```c
SHZ_INLINE float shz_quat_angle_y(shz_quat_t q) SHZ_NOEXCEPT;
```

Returns the angle of rotation the quaternion represents about the Y axis in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::quat::angle_y`](https://sh4zam.com/api/cpp/quat/#angle_y)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:162`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L162)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Properties"


---
# shz_quat_angle_z

Source: https://sh4zam.com/api/quat/shz_quat_angle_z/

```c
SHZ_INLINE float shz_quat_angle_z(shz_quat_t q) SHZ_NOEXCEPT;
```

Returns the angle of rotation the quaternion represents about the Z axis in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::quat::angle_z`](https://sh4zam.com/api/cpp/quat/#angle_z)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:165`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L165)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Properties"


---
# shz_quat_angle

Source: https://sh4zam.com/api/quat/shz_quat_angle/

```c
SHZ_INLINE float shz_quat_angle(shz_quat_t q) SHZ_NOEXCEPT;
```

Returns the angle of rotation from the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::quat::angle`](https://sh4zam.com/api/cpp/quat/#angle)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:153`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L153)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Properties"


---
# shz_quat_axis

Source: https://sh4zam.com/api/quat/shz_quat_axis/

```c
SHZ_INLINE shz_vec3_t shz_quat_axis(shz_quat_t q) SHZ_NOEXCEPT;
```

Returns the axis of rotation from the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::quat::axis`](https://sh4zam.com/api/cpp/quat/#axis)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:156`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L156)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Properties"


---
# shz_quat_conjugate

Source: https://sh4zam.com/api/quat/shz_quat_conjugate/

```c
SHZ_INLINE shz_quat_t shz_quat_conjugate(shz_quat_t quat) SHZ_NOEXCEPT;
```

Returns the conjugate of the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `quat` | `shz_quat_t` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::conjugated`](https://sh4zam.com/api/cpp/quat/#conjugated)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:199`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L199)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Modifiers"


---
# shz_quat_div

Source: https://sh4zam.com/api/quat/shz_quat_div/

> Divides quaternion p by quaternion q (multiplying by its inverse), returning the resulting quaternion

```c
SHZ_INLINE shz_quat_t shz_quat_div(shz_quat_t q, shz_quat_t p) SHZ_NOEXCEPT;
```

Divides quaternion `p` by quaternion `q` (multiplying by its inverse), returning the resulting quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |
| `p` | `shz_quat_t` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::div`](https://sh4zam.com/api/cpp/quat/#div)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:227`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L227)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Arithmetic"


---
# shz_quat_dot

Source: https://sh4zam.com/api/quat/shz_quat_dot/

```c
SHZ_INLINE float shz_quat_dot(shz_quat_t q1, shz_quat_t q2) SHZ_NOEXCEPT;
```

Returns the dot product of the two quaternions.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q1` | `shz_quat_t` |  |
| `q2` | `shz_quat_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:230`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L230)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Arithmetic"


---
# shz_quat_dot2

Source: https://sh4zam.com/api/quat/shz_quat_dot2/

> Returns the two dot products taken between the l quaternion and the r1 and r2 quaternions

```c
SHZ_INLINE shz_vec2_t shz_quat_dot2(shz_quat_t l, shz_quat_t r1, shz_quat_t r2) SHZ_NOEXCEPT;
```

Returns the two dot products taken between the `l` quaternion and the `r1` and `r2` quaternions.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `l` | `shz_quat_t` |  |
| `r1` | `shz_quat_t` |  |
| `r2` | `shz_quat_t` |  |

## Returns

`shz_vec2_t`

## Naming and requirements

- `dot2/dot3`: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined `FIPR` sequence. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:233`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L233)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Arithmetic"


---
# shz_quat_dot3

Source: https://sh4zam.com/api/quat/shz_quat_dot3/

> Returns the two dot products taken between the l quaternion and the r1, r2, and r3 quaternions

```c
SHZ_INLINE shz_vec3_t shz_quat_dot3(shz_quat_t l, shz_quat_t r1, shz_quat_t r2, shz_quat_t r3) SHZ_NOEXCEPT;
```

Returns the two dot products taken between the `l` quaternion and the `r1`, `r2`, and `r3` quaternions.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `l` | `shz_quat_t` |  |
| `r1` | `shz_quat_t` |  |
| `r2` | `shz_quat_t` |  |
| `r3` | `shz_quat_t` |  |

## Returns

`shz_vec3_t`

## Naming and requirements

- `dot2/dot3`: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined `FIPR` sequence. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:236`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L236)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Arithmetic"


---
# shz_quat_equal

Source: https://sh4zam.com/api/quat/shz_quat_equal/

```c
SHZ_INLINE bool shz_quat_equal(shz_quat_t a, shz_quat_t b) SHZ_NOEXCEPT;
```

Returns true if the two given quaternions are considered equal based on either absolute or relative tolerance.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_quat_t` |  |
| `b` | `shz_quat_t` |  |

## Returns

`bool`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:63`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L63)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_from_angles_xyz

Source: https://sh4zam.com/api/quat/shz_quat_from_angles_xyz/

```c
SHZ_INLINE shz_quat_t shz_quat_from_angles_xyz(float xangle, float yangle, float zangle) SHZ_NOEXCEPT;
```

Initializes and returns a quaternion with the given X-Y-Z rotations in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `xangle` | `float` |  |
| `yangle` | `float` |  |
| `zangle` | `float` |  |

## Returns

`shz_quat_t`

## Details

The rotation is applied first around the X-axis, then the Y-, then the Z-axis.

## Notes

- These angles are Tait-Bryan angles representing an intrinsic rotation.

## Availability

- **C++ equivalent:** [`shz::quat::from_angles_xyz`](https://sh4zam.com/api/cpp/quat/#from_angles_xyz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:73`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L73)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_from_axis_angle

Source: https://sh4zam.com/api/quat/shz_quat_from_axis_angle/

> Initializes and returns a quaternion representing a rotation of angle radians about the given axis

```c
SHZ_INLINE shz_quat_t shz_quat_from_axis_angle(shz_vec3_t axis, float angle) SHZ_NOEXCEPT;
```

Initializes and returns a quaternion representing a rotation of `angle` radians about the given `axis`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `axis` | `shz_vec3_t` |  |
| `angle` | `float` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::from_axis_angle`](https://sh4zam.com/api/cpp/quat/#from_axis_angle)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:113`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L113)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_from_look_axis

Source: https://sh4zam.com/api/quat/shz_quat_from_look_axis/

```c
shz_quat_t shz_quat_from_look_axis(shz_vec3_t forward, shz_vec3_t up) SHZ_NOEXCEPT;
```

Creates a quaternion looking in the given direction with the given reference direction.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `forward` | `shz_vec3_t` |  |
| `up` | `shz_vec3_t` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::from_look_axis`](https://sh4zam.com/api/cpp/quat/#from_look_axis)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:116`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L116)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_from_rotated_axis

Source: https://sh4zam.com/api/quat/shz_quat_from_rotated_axis/

> Returns the quaternion representing the rotation from axis v1 to v2

```c
SHZ_INLINE shz_quat_t shz_quat_from_rotated_axis(shz_vec3_t v1, shz_vec3_t v2) SHZ_NOEXCEPT;
```

Returns the quaternion representing the rotation from axis `v1` to `v2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `v1` | `shz_vec3_t` |  |
| `v2` | `shz_vec3_t` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::from_rotated_axis`](https://sh4zam.com/api/cpp/quat/#from_rotated_axis)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:119`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L119)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_from_rotation_xyz_u16

Source: https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz_u16/

> Equivalent to shz_quat_from_rotation_xyz(), with 16-bit binary angles (65536 per turn, the FSCA unit)

```c
SHZ_INLINE shz_quat_t shz_quat_from_rotation_xyz_u16(uint16_t xAngle, uint16_t yAngle, uint16_t zAngle) SHZ_NOEXCEPT;
```

Equivalent to `shz_quat_from_rotation_xyz()`, with 16-bit binary angles (65536 per turn, the FSCA unit).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `xAngle` | `uint16_t` |  |
| `yAngle` | `uint16_t` |  |
| `zAngle` | `uint16_t` |  |

## Returns

`shz_quat_t`

## Details

For games whose orientations are stored as 16-bit angles, such as N64 titles. Signed 16-bit angles can be passed as they are. The half angles go to FSCA directly, without a conversion to radians, so an odd angle is off by half a unit (1/131072 of a turn) in its half angle.

## Naming and requirements

- `u16`: Angle is a 16-bit fixed-point value: 0..65535 maps to 0..2π, the native `FSCA` input format. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::quat::from_rotation_xyz_u16`](https://sh4zam.com/api/cpp/quat/#from_rotation_xyz_u16)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:101`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L101)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"

## See also

[`shz_sincosu16`](https://sh4zam.com/api/trig/shz_sincosu16/)


---
# shz_quat_from_rotation_xyz

Source: https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz/

> Returns the quaternion of the rotation shz_xmtrx_init_rotation_xyz() builds, from angles in radians

```c
SHZ_INLINE shz_quat_t shz_quat_from_rotation_xyz(float xAngle, float yAngle, float zAngle) SHZ_NOEXCEPT;
```

Returns the quaternion of the rotation `shz_xmtrx_init_rotation_xyz()` builds, from angles in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `xAngle` | `float` |  |
| `yAngle` | `float` |  |
| `zAngle` | `float` |  |

## Returns

`shz_quat_t`

## Details

The result equals the product of the axis quaternions in the order of the name, Qx \* Qy \* Qz, so it describes the same orientation as the matrix of the same name.

## Availability

- **C++ equivalent:** [`shz::quat::from_rotation_xyz`](https://sh4zam.com/api/cpp/quat/#from_rotation_xyz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:82`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L82)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"

## See also

[`shz_quat_from_rotation_xyz_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz_u16/), [`shz_xmtrx_init_rotation_xyz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_xyz/), [`shz_xmtrx_init_rotation_quat`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_quat/)


---
# shz_quat_from_rotation_yxz_u16

Source: https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz_u16/

> Equivalent to shz_quat_from_rotation_yxz(), with 16-bit binary angles

```c
SHZ_INLINE shz_quat_t shz_quat_from_rotation_yxz_u16(uint16_t yAngle, uint16_t xAngle, uint16_t zAngle) SHZ_NOEXCEPT;
```

Equivalent to `shz_quat_from_rotation_yxz()`, with 16-bit binary angles.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `yAngle` | `uint16_t` |  |
| `xAngle` | `uint16_t` |  |
| `zAngle` | `uint16_t` |  |

## Returns

`shz_quat_t`

## Naming and requirements

- `u16`: Angle is a 16-bit fixed-point value: 0..65535 maps to 0..2π, the native `FSCA` input format. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::quat::from_rotation_yxz_u16`](https://sh4zam.com/api/cpp/quat/#from_rotation_yxz_u16)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:110`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L110)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_from_rotation_yxz

Source: https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz/

> Returns the quaternion of the rotation shz_xmtrx_init_rotation_yxz() builds, Qy \ Qx \ Qz, from angles in radians

```c
SHZ_INLINE shz_quat_t shz_quat_from_rotation_yxz(float yAngle, float xAngle, float zAngle) SHZ_NOEXCEPT;
```

Returns the quaternion of the rotation `shz_xmtrx_init_rotation_yxz()` builds, Qy \* Qx \* Qz, from angles in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `yAngle` | `float` |  |
| `xAngle` | `float` |  |
| `zAngle` | `float` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::from_rotation_yxz`](https://sh4zam.com/api/cpp/quat/#from_rotation_yxz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:91`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L91)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_from_rotation_zxy_u16

Source: https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy_u16/

> Equivalent to shz_quat_from_rotation_zxy(), with 16-bit binary angles

```c
SHZ_INLINE shz_quat_t shz_quat_from_rotation_zxy_u16(uint16_t zAngle, uint16_t xAngle, uint16_t yAngle) SHZ_NOEXCEPT;
```

Equivalent to `shz_quat_from_rotation_zxy()`, with 16-bit binary angles.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `zAngle` | `uint16_t` |  |
| `xAngle` | `uint16_t` |  |
| `yAngle` | `uint16_t` |  |

## Returns

`shz_quat_t`

## Naming and requirements

- `u16`: Angle is a 16-bit fixed-point value: 0..65535 maps to 0..2π, the native `FSCA` input format. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::quat::from_rotation_zxy_u16`](https://sh4zam.com/api/cpp/quat/#from_rotation_zxy_u16)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:107`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L107)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_from_rotation_zxy

Source: https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy/

> Returns the quaternion of the rotation shz_xmtrx_init_rotation_zxy() builds, Qz \ Qx \ Qy, from angles in radians

```c
SHZ_INLINE shz_quat_t shz_quat_from_rotation_zxy(float zAngle, float xAngle, float yAngle) SHZ_NOEXCEPT;
```

Returns the quaternion of the rotation `shz_xmtrx_init_rotation_zxy()` builds, Qz \* Qx \* Qy, from angles in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `zAngle` | `float` |  |
| `xAngle` | `float` |  |
| `yAngle` | `float` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::from_rotation_zxy`](https://sh4zam.com/api/cpp/quat/#from_rotation_zxy)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:88`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L88)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_from_rotation_zyx_u16

Source: https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx_u16/

> Equivalent to shz_quat_from_rotation_zyx(), with 16-bit binary angles

```c
SHZ_INLINE shz_quat_t shz_quat_from_rotation_zyx_u16(uint16_t zAngle, uint16_t yAngle, uint16_t xAngle) SHZ_NOEXCEPT;
```

Equivalent to `shz_quat_from_rotation_zyx()`, with 16-bit binary angles.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `zAngle` | `uint16_t` |  |
| `yAngle` | `uint16_t` |  |
| `xAngle` | `uint16_t` |  |

## Returns

`shz_quat_t`

## Naming and requirements

- `u16`: Angle is a 16-bit fixed-point value: 0..65535 maps to 0..2π, the native `FSCA` input format. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::quat::from_rotation_zyx_u16`](https://sh4zam.com/api/cpp/quat/#from_rotation_zyx_u16)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:104`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L104)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_from_rotation_zyx

Source: https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx/

> Returns the quaternion of the rotation shz_xmtrx_init_rotation_zyx() builds, Qz \ Qy \ Qx, from angles in radians

```c
SHZ_INLINE shz_quat_t shz_quat_from_rotation_zyx(float zAngle, float yAngle, float xAngle) SHZ_NOEXCEPT;
```

Returns the quaternion of the rotation `shz_xmtrx_init_rotation_zyx()` builds, Qz \* Qy \* Qx, from angles in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `zAngle` | `float` |  |
| `yAngle` | `float` |  |
| `xAngle` | `float` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::from_rotation_zyx`](https://sh4zam.com/api/cpp/quat/#from_rotation_zyx)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:85`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L85)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_identity

Source: https://sh4zam.com/api/quat/shz_quat_identity/

```c
SHZ_INLINE shz_quat_t shz_quat_identity(void) SHZ_NOEXCEPT;
```

Initializes and returns an identity quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::identity`](https://sh4zam.com/api/cpp/quat/#identity)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:60`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L60)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_init

Source: https://sh4zam.com/api/quat/shz_quat_init/

```c
SHZ_INLINE shz_quat_t shz_quat_init(float w, float x, float y, float z) SHZ_NOEXCEPT;
```

Initializes and returns a new quaternion with the given components, in WXYZ order.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `w` | `float` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:57`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L57)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_inv

Source: https://sh4zam.com/api/quat/shz_quat_inv/

```c
SHZ_INLINE shz_quat_t shz_quat_inv(shz_quat_t quat) SHZ_NOEXCEPT;
```

Returns the inverse of the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `quat` | `shz_quat_t` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::inverse`](https://sh4zam.com/api/cpp/quat/#inverse)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:202`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L202)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Modifiers"


---
# shz_quat_lerp

Source: https://sh4zam.com/api/quat/shz_quat_lerp/

> Returns the quaternion that is linearly interpolating a to b, by a t factor of 0.0f-1.0f

```c
SHZ_INLINE shz_quat_t shz_quat_lerp(shz_quat_t a, shz_quat_t b, float t) SHZ_NOEXCEPT;
```

Returns the quaternion that is linearly interpolating `a` to `b`, by a t factor of `0.0f-1.0f`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_quat_t` |  |
| `b` | `shz_quat_t` |  |
| `t` | `float` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::lerp`](https://sh4zam.com/api/cpp/quat/#lerp)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:122`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L122)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_magnitude_inv

Source: https://sh4zam.com/api/quat/shz_quat_magnitude_inv/

```c
SHZ_INLINE float shz_quat_magnitude_inv(shz_quat_t quat) SHZ_NOEXCEPT;
```

Returns the inverse magnitude of the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `quat` | `shz_quat_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::quat::magnitude_inv`](https://sh4zam.com/api/cpp/quat/#magnitude_inv)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:180`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L180)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Properties"


---
# shz_quat_magnitude_sqr

Source: https://sh4zam.com/api/quat/shz_quat_magnitude_sqr/

```c
SHZ_INLINE float shz_quat_magnitude_sqr(shz_quat_t quat) SHZ_NOEXCEPT;
```

Returns the squared magnitude of the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `quat` | `shz_quat_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::quat::magnitude_sqr`](https://sh4zam.com/api/cpp/quat/#magnitude_sqr)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:174`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L174)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Properties"


---
# shz_quat_magnitude

Source: https://sh4zam.com/api/quat/shz_quat_magnitude/

```c
SHZ_INLINE float shz_quat_magnitude(shz_quat_t quat) SHZ_NOEXCEPT;
```

Returns the magnitude of the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `quat` | `shz_quat_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::quat::magnitude`](https://sh4zam.com/api/cpp/quat/#magnitude)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:177`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L177)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Properties"


---
# shz_quat_mult

Source: https://sh4zam.com/api/quat/shz_quat_mult/

```c
SHZ_INLINE shz_quat_t shz_quat_mult(shz_quat_t q1, shz_quat_t q2) SHZ_NOEXCEPT;
```

Multiplies the two quaternions, returning the result as a new quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q1` | `shz_quat_t` |  |
| `q2` | `shz_quat_t` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::mult`](https://sh4zam.com/api/cpp/quat/#mult)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:224`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L224)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Arithmetic"


---
# shz_quat_neg

Source: https://sh4zam.com/api/quat/shz_quat_neg/

```c
SHZ_INLINE shz_quat_t shz_quat_neg(shz_quat_t quat) SHZ_NOEXCEPT;
```

Returns the negation of the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `quat` | `shz_quat_t` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::negated`](https://sh4zam.com/api/cpp/quat/#negated)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:205`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L205)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Modifiers"


---
# shz_quat_nlerp

Source: https://sh4zam.com/api/quat/shz_quat_nlerp/

> Equivalent to shz_quat_lerp(), except that the resulting quaternion is normalized

```c
SHZ_INLINE shz_quat_t shz_quat_nlerp(shz_quat_t a, shz_quat_t b, float t) SHZ_NOEXCEPT;
```

Equivalent to `shz_quat_lerp()`, except that the resulting quaternion is normalized.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_quat_t` |  |
| `b` | `shz_quat_t` |  |
| `t` | `float` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::nlerp`](https://sh4zam.com/api/cpp/quat/#nlerp)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:125`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L125)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_normalize_safe

Source: https://sh4zam.com/api/quat/shz_quat_normalize_safe/

```c
SHZ_INLINE shz_quat_t shz_quat_normalize_safe(shz_quat_t quat) SHZ_NOEXCEPT;
```

SAFELY returns the normalized form of the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `quat` | `shz_quat_t` |  |

## Returns

`shz_quat_t`

## Details

Returns the identity quaternion when magnitude is 0.0f.

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::quat::normalized_safe`](https://sh4zam.com/api/cpp/quat/#normalized_safe)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:196`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L196)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Modifiers"


---
# shz_quat_normalize

Source: https://sh4zam.com/api/quat/shz_quat_normalize/

```c
SHZ_INLINE shz_quat_t shz_quat_normalize(shz_quat_t quat) SHZ_NOEXCEPT;
```

Returns the normalized form of the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `quat` | `shz_quat_t` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::normalized`](https://sh4zam.com/api/cpp/quat/#normalized)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:190`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L190)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Modifiers"


---
# shz_quat_rotate_towards

Source: https://sh4zam.com/api/quat/shz_quat_rotate_towards/

> Rotates quaternion from towards quaternion to by at most max_angle radians

```c
SHZ_INLINE shz_quat_t shz_quat_rotate_towards(shz_quat_t from, shz_quat_t to, float max_angle) SHZ_NOEXCEPT;
```

Rotates quaternion `from` towards quaternion `to` by at most `max_angle` radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `from` | `shz_quat_t` |  |
| `to` | `shz_quat_t` |  |
| `max_angle` | `float` |  |

## Returns

`shz_quat_t`

## Notes

- Returns `to` if the angle between them is already less than `max_angle`.

## Availability

- **C++ equivalent:** [`shz::quat::rotate_towards`](https://sh4zam.com/api/cpp/quat/#rotate_towards)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:252`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L252)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Miscellaneous"


---
# shz_quat_scale

Source: https://sh4zam.com/api/quat/shz_quat_scale/

```c
SHZ_INLINE shz_quat_t shz_quat_scale(shz_quat_t q, float f) SHZ_NOEXCEPT;
```

Scales the components of the given quaternion by the given factor.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |
| `f` | `float` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::scaled`](https://sh4zam.com/api/cpp/quat/#scaled)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:221`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L221)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Arithmetic"


---
# shz_quat_slerp

Source: https://sh4zam.com/api/quat/shz_quat_slerp/

> Returns the quaternion that is spherically linearly interpolating a to b, by a t factor of 0.0f-1.0f

```c
SHZ_INLINE shz_quat_t shz_quat_slerp(shz_quat_t q, shz_quat_t p, float t) SHZ_NOEXCEPT;
```

Returns the quaternion that is spherically linearly interpolating `a` to `b`, by a `t` factor of `0.0f-1.0f`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |
| `p` | `shz_quat_t` |  |
| `t` | `float` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::slerp`](https://sh4zam.com/api/cpp/quat/#slerp)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:128`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L128)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_squad

Source: https://sh4zam.com/api/quat/shz_quat_squad/

> Evaluates a smooth cubic spherical interpolation (SQUAD) at parameter t

```c
SHZ_INLINE shz_quat_t shz_quat_squad(shz_quat_t q1, shz_quat_t q2, shz_quat_t s1, shz_quat_t s2, float t) SHZ_NOEXCEPT;
```

Evaluates a smooth cubic spherical interpolation (SQUAD) at parameter `t`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q1` | `shz_quat_t` | Start quaternion. |
| `q2` | `shz_quat_t` | End quaternion. |
| `s1` | `shz_quat_t` | Inner control point for `q1` (typically computed from surrounding keyframes). |
| `s2` | `shz_quat_t` | Inner control point for `q2` (typically computed from surrounding keyframes). |
| `t` | `float` | Interpolation factor in \[0, 1\]. |

## Returns

Resulting interpolated quaternion

## Notes

- SQUAD(q1, q2, s1, s2, t) = slerp(slerp(q1, q2, t), slerp(s1, s2, t), 2t(1-t))

## Availability

- **C++ equivalent:** [`shz::quat::squad`](https://sh4zam.com/api/cpp/quat/#squad)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:143`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L143)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Initialization"


---
# shz_quat_sub

Source: https://sh4zam.com/api/quat/shz_quat_sub/

> Returns the quaternion produced from subtracting each component of quaternion p from quaterion q

```c
SHZ_INLINE shz_quat_t shz_quat_sub(shz_quat_t q, shz_quat_t p) SHZ_NOEXCEPT;
```

Returns the quaternion produced from subtracting each component of quaternion `p` from quaterion `q`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |
| `p` | `shz_quat_t` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::quat::sub`](https://sh4zam.com/api/cpp/quat/#sub)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:218`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L218)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Arithmetic"


---
# shz_quat_t

Source: https://sh4zam.com/api/quat/shz_quat_t/

```c
typedef struct shz_quat {
    union {           //!< Convenience anonymous union between named and array-indexed components.
        struct {      //!< Anonymous structure with named components.
            float w;             //!< W or scalar component/real part of quaternion.
            union {   //!< Convenience anonymous union for vector components.
                struct {
                    float x;     //!< X component of axis of rotation (imaginary)
                    float y;     //!< Y component of axis of rotation (imaginary)
                    float z;     //!< Z component of axis of rotation (imaginary)
                };
                shz_vec3_t axis; //!< 3D vector representing axis of rotation
            };
        };
        float e[4];              //!< Array-indexed components.
    };
} shz_quat_t;
```

Represents a 3D quaternion.

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `e` | `float[4]` | Array-indexed components. |
| `w` | `float` | \< Anonymous structure with named components. |
| `axis` | `shz_vec3_t` | 3D vector representing axis of rotation |
| `x` | `float` | X component of axis of rotation (imaginary). |
| `y` | `float` | Y component of axis of rotation (imaginary). |
| `z` | `float` | Z component of axis of rotation (imaginary). |

## Details

Quaternions are a mathematical structure representing a rotation about a single arbitrary axis.

## Availability

- **C++ equivalent:** [`shz::quat`](https://sh4zam.com/api/cpp/quat/)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_quat.h:31`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L31)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Types"


---
# shz_quat_to_angles_xyz

Source: https://sh4zam.com/api/quat/shz_quat_to_angles_xyz/

```c
SHZ_INLINE shz_vec3_t shz_quat_to_angles_xyz(shz_quat_t q) SHZ_NOEXCEPT;
```

Returns the roll, pitch, and yaw angles of rotation represented by the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::quat::to_angles_xyz`](https://sh4zam.com/api/cpp/quat/#to_angles_xyz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:171`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L171)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Properties"


---
# shz_quat_to_axis_angle

Source: https://sh4zam.com/api/quat/shz_quat_to_axis_angle/

```c
SHZ_INLINE void shz_quat_to_axis_angle(shz_quat_t q, shz_vec3_t* vec, float* angle) SHZ_NOEXCEPT;
```

Returns both the axis and angle of rotation simultaneously (faster if both are needed) from the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |
| `vec` | `shz_vec3_t *` |  |
| `angle` | `float *` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::quat::to_axis_angle`](https://sh4zam.com/api/cpp/quat/#to_axis_angle)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:168`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L168)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Properties"


---
# shz_quat_transform_vec3

Source: https://sh4zam.com/api/quat/shz_quat_transform_vec3/

```c
SHZ_INLINE shz_vec3_t shz_quat_transform_vec3(shz_quat_t q, shz_vec3_t v) SHZ_NOEXCEPT;
```

Rotates a vector by the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |
| `v` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Notes

- This routine is meant for one-off rotations of a single vector by a single quaternion. If you plan to rotate multiple vectors by the same quaternion, you should use the XMTRX API to apply the quaternion as a rotation matrix.

## Availability

- **C++ equivalent:** [`shz::quat::transform`](https://sh4zam.com/api/cpp/quat/#transform)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_quat.h:270`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L270)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Transformations"

## See also

[`shz_xmtrx_apply_rotation_quat`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_quat/)


---
# shz_quat

Source: https://sh4zam.com/api/quat/shz_quat/

> Alternate shz_quat_t C typedef for those who hate POSIX style

```c
typedef shz_quat_t shz_quat;
```

Alternate [`shz_quat_t`](https://sh4zam.com/api/quat/shz_quat_t/) C typedef for those who hate POSIX style.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_quat.h:49`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_quat.h#L49)
- **Module:** [Quaternion](https://sh4zam.com/api/quat/), section "Types"


---
# Scalar API

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

> Scalar functions and utilities, including faster <math.h> replacements

This API is designed around performing various scalar operations, providing alternatives for routines typically found within `<math.h>`. Many are drop-in replacements that beat libm on the SH4 by staying in single-precision `float`: no libm call and no promotion to `double`. Unlike the standard C floating-point routines, these routines are often saving cycles by not handling NaN and INF values as well as by not reporting rounding and domain errors back to the user. The `_fsrra` variants use the SH4 `FSRRA` instruction (fast approximate reciprocal square root) and the FIPR helpers run raw dot products through the vector FPU. In C++ every routine is also available as an alias in `namespace shz` with the `shz_` prefix dropped, for example `shz::floorf`.

- **C header:** `#include <sh4zam/shz_scalar.h>`
- **C++ header:** `#include <sh4zam/shz_scalar.hpp>`
- **Symbols:** 56

## Suffixes

Suffixes used in this module. The full list is in [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/).

- `_fsrra`: Uses `FSRRA` (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise.
- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost.

## Comparisons

Routines for comparing and classifying floating-point values.

| Symbol | Description |
| --- | --- |
| [`shz_fminf`](https://sh4zam.com/api/scalar/shz_fminf/) | Returns the minimum value of two given floats. |
| [`shz_fmaxf`](https://sh4zam.com/api/scalar/shz_fmaxf/) | Returns the maximum value of two given floats. |
| [`shz_equalf`](https://sh4zam.com/api/scalar/shz_equalf/) | Checks for equality based on EITHER the absolute tolerance or relative tolerance, using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/). |
| [`shz_equalf_abs`](https://sh4zam.com/api/scalar/shz_equalf_abs/) | Checks for equality based on the absolute tolerance using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/). |
| [`shz_equalf_rel`](https://sh4zam.com/api/scalar/shz_equalf_rel/) | Checks for equality based on the relative tolerance using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/). |

## Rounding

Routines for rounding and manipulating floats.

| Symbol | Description |
| --- | --- |
| [`shz_floorf`](https://sh4zam.com/api/scalar/shz_floorf/) | Replacement for the \<math.h> routine, floorf(). |
| [`shz_ceilf`](https://sh4zam.com/api/scalar/shz_ceilf/) | Replacement for the \<math.h> routine, ceilf(). |
| [`shz_roundf`](https://sh4zam.com/api/scalar/shz_roundf/) | Replacement for the \<math.h> routine, roundf(). |
| [`shz_truncf`](https://sh4zam.com/api/scalar/shz_truncf/) | Replacement for the \<math.h> routine, truncf(). |
| [`shz_remainderf`](https://sh4zam.com/api/scalar/shz_remainderf/) | Replacement for the \<math.h> routine, remainderf(). |
| [`shz_fmodf`](https://sh4zam.com/api/scalar/shz_fmodf/) | Replacement for the \<math.h> routine, fmodf(). |
| [`shz_remquof`](https://sh4zam.com/api/scalar/shz_remquof/) | (Sorta) Replacement for the \<math.h> routine, remquof(). |

## Mapping

Routines for mapping a number to another range.

| Symbol | Description |
| --- | --- |
| [`shz_clampf`](https://sh4zam.com/api/scalar/shz_clampf/) | Clamps a floating-point value by the given `min` and `max` values. |
| [`shz_normalizef`](https://sh4zam.com/api/scalar/shz_normalizef/) | Maps a value within the given range `from` to `to`, to be within the range of `0.0f += 1.0f`. |
| [`shz_normalizef_fsrra`](https://sh4zam.com/api/scalar/shz_normalizef_fsrra/) | Maps a value within the given range `from` to `to`, to be within the range of `0.0f + 1.0f` more quickly, provided `to` - `from` is a positive difference. |
| [`shz_remapf`](https://sh4zam.com/api/scalar/shz_remapf/) | Maps a value within the given range `inputStart` to `inputEnd`, to be within the range of `outputStart` to `outputEnd`. |
| [`shz_remapf_fsrra`](https://sh4zam.com/api/scalar/shz_remapf_fsrra/) | Maps a value within the given range `inputStart` to `inputEnd`, to be within the range of `outputStart` to `outputEnd` more quickly, provided the `outputEnd` - `outputStart` is a positive difference. |
| [`shz_wrapf`](https://sh4zam.com/api/scalar/shz_wrapf/) | Wraps the given `value` back to be within the range of `min` to `max`. |
| [`shz_wrapf_fsrra`](https://sh4zam.com/api/scalar/shz_wrapf_fsrra/) | Wraps the given `value` back to be within the range of `min` to `max` more quickly, provided `max` - `min` is a positive difference. |
| [`shz_fractf`](https://sh4zam.com/api/scalar/shz_fractf/) | Returns the fractional part of `x`, equivalent to GLSL `fract()`. |
| [`shz_signf`](https://sh4zam.com/api/scalar/shz_signf/) | Returns -1.0f if `x` \< 0, 0.0f if `x` == 0, or 1.0f if `x` > 0. |
| [`shz_saturatef`](https://sh4zam.com/api/scalar/shz_saturatef/) | Clamps `x` to the range \[0.0f, 1.0f\]. |

## Miscellaneous

Assorted routines implementing other fp operations.

| Symbol | Description |
| --- | --- |
| [`shz_fabsf`](https://sh4zam.com/api/scalar/shz_fabsf/) | Replacement for the \<math.h> routine, fabsf(). |
| [`shz_copysignf`](https://sh4zam.com/api/scalar/shz_copysignf/) | Replacement for the \<math.h> routine, copysignf(). |
| [`shz_fmaf`](https://sh4zam.com/api/scalar/shz_fmaf/) | Replacement for the \<math.h> routine, fmaf(). |
| [`shz_fdimf`](https://sh4zam.com/api/scalar/shz_fdimf/) | Replacement for the \<math.h> routine, fdimf(),. |
| [`shz_hypotf`](https://sh4zam.com/api/scalar/shz_hypotf/) | Replacement for the \<math.h> routine, hypotf(). |
| [`shz_cbrtf`](https://sh4zam.com/api/scalar/shz_cbrtf/) | Replacement for the \<math.h> routine, cbrtf(). |
| [`shz_lerpf`](https://sh4zam.com/api/scalar/shz_lerpf/) | Returns a value that is linearly interpolated between `a` and `b` by the given ratio, `t`. |
| [`shz_barycentric_lerpf`](https://sh4zam.com/api/scalar/shz_barycentric_lerpf/) | Returns a value that is barycentrically interpolated between `a`, `b`, and `c` using the given barycentric coordinates, `u` and `v`. |
| [`shz_quadratic_roots`](https://sh4zam.com/api/scalar/shz_quadratic_roots/) | Uses the quadratic formula with the given coefficients to solve for the two roots, returning `true` if any real roots exist, and `false` if the roots are only imaginary. |
| [`shz_randf`](https://sh4zam.com/api/scalar/shz_randf/) | Returns a random floating-point number between `0.0f` and `1.0f`, using and updating the given seed. |
| [`shz_randf_range`](https://sh4zam.com/api/scalar/shz_randf_range/) | Returns a random floating-point number between `min` and `max`, using and updating the given seed. |
| [`shz_stepf`](https://sh4zam.com/api/scalar/shz_stepf/) | returns 0.0f if x \< edge, otherwise 1.0f |
| [`shz_smoothstepf`](https://sh4zam.com/api/scalar/shz_smoothstepf/) | Returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. edge0 must be less than edge1 or result is undefined. |
| [`shz_smoothstepf_safe`](https://sh4zam.com/api/scalar/shz_smoothstepf_safe/) | Returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. Accepts inverse edges. |

## FSRRA

Routines built around fast reciprocal square root instruction.

| Symbol | Description |
| --- | --- |
| [`shz_inv_sqrtf_fsrra`](https://sh4zam.com/api/scalar/shz_inv_sqrtf_fsrra/) | Calculates 1.0f/sqrtf( `x`), using a fast approximation. |
| [`shz_inv_sqrtf`](https://sh4zam.com/api/scalar/shz_inv_sqrtf/) | Calculates 1.0f/sqrtf( `x` ), using a fast approximation, while safely protecting against division-by-zero. |
| [`shz_sqrtf_fsrra`](https://sh4zam.com/api/scalar/shz_sqrtf_fsrra/) | Returns the fast approximate square root of the given value, `x`. |
| [`shz_sqrtf`](https://sh4zam.com/api/scalar/shz_sqrtf/) | Returns the fast approximate square root of the given value, `x`, safely returning `0.0f` is `x` == `0.0f`. |
| [`shz_invf_fsrra`](https://sh4zam.com/api/scalar/shz_invf_fsrra/) | Takes the inverse of `x` using a very fast approximation, returning a positive result. |
| [`shz_invf`](https://sh4zam.com/api/scalar/shz_invf/) | Takes the inverse of `x` using a slighty faster approximation than doing a full division, safely handling negative values. |
| [`shz_divf_fsrra`](https://sh4zam.com/api/scalar/shz_divf_fsrra/) | Divides `num` by `denom` using a very fast approximation, which requires `denom` be a positive value. |
| [`shz_divf`](https://sh4zam.com/api/scalar/shz_divf/) | Divides `num` by `denom` using a slightly faster approximation, allowing `denom` to be negative. |

## FIPR

Routines built around fast 4D dot product.

| Symbol | Description |
| --- | --- |
| [`shz_dot6f`](https://sh4zam.com/api/scalar/shz_dot6f/) | Takes two sets of 3D vectors as 3 floats and calculates their dot product using an approximation. |
| [`shz_dot8f`](https://sh4zam.com/api/scalar/shz_dot8f/) | Takes two sets of 4D vectors as 4 floats and calculates their dot product using an approximation. |
| [`shz_mag_sqr3f`](https://sh4zam.com/api/scalar/shz_mag_sqr3f/) | Takes a 3D vector as 3 floats and calculates its squared magnitude using a fast approximation. |
| [`shz_mag_sqr4f`](https://sh4zam.com/api/scalar/shz_mag_sqr4f/) | Takes a 4D vector as 4 floats and calculates its squared magnitude using a fast approximation. |

## Transcendental

Fast approximations for non-trig transcendental functions.

| Symbol | Description |
| --- | --- |
| [`shz_pow2f`](https://sh4zam.com/api/scalar/shz_pow2f/) | Fast approximation for raising 2 to a floating-point power. |
| [`shz_powf`](https://sh4zam.com/api/scalar/shz_powf/) | Fast approximation for C's powf(). |
| [`shz_pow10f`](https://sh4zam.com/api/scalar/shz_pow10f/) | Fast approximation of POSIX's pow10f(). |
| [`shz_log2f`](https://sh4zam.com/api/scalar/shz_log2f/) | Fast approximation for C's log2f(). |
| [`shz_logf`](https://sh4zam.com/api/scalar/shz_logf/) | Fast approximation for C's logf(). |
| [`shz_log10f`](https://sh4zam.com/api/scalar/shz_log10f/) | Fast approximation for C's log10f(). |
| [`shz_expf`](https://sh4zam.com/api/scalar/shz_expf/) | Fast approximation for C's expf(). |

## Macros

| Symbol | Description |
| --- | --- |
| [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/) | Floating-point epsilon used with inexact FP-based comparisons. |


---
# shz_barycentric_lerpf

Source: https://sh4zam.com/api/scalar/shz_barycentric_lerpf/

> Returns a value that is barycentrically interpolated between a, b, and c using the given barycentric coordinates, u and v

```c
SHZ_INLINE float shz_barycentric_lerpf(float a, float b, float c, float u, float v) SHZ_NOEXCEPT;
```

Returns a value that is barycentrically interpolated between `a`, `b`, and `c` using the given barycentric coordinates, `u` and `v`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `float` |  |
| `b` | `float` |  |
| `c` | `float` |  |
| `u` | `float` |  |
| `v` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::barycentric_lerpf`](https://sh4zam.com/api/cpp/#shzbarycentric_lerpf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:249`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L249)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_cbrtf

Source: https://sh4zam.com/api/scalar/shz_cbrtf/

> Replacement for the <math.h> routine, cbrtf()

```c
SHZ_INLINE float shz_cbrtf(float x) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, cbrtf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Details

Returns the cubed root of `x`, using a fast approximation.

## Availability

- **C++ equivalent:** [`shz::cbrtf`](https://sh4zam.com/api/cpp/#shzcbrtf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:243`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L243)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_ceilf

Source: https://sh4zam.com/api/scalar/shz_ceilf/

> Replacement for the <math.h> routine, ceilf()

```c
SHZ_INLINE float shz_ceilf(float x) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, ceilf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Details

Returns the closest integral value to `x`, rounded up, as a float.

## Warnings

- This routine only returns valid values for the input range INT32_MIN \<= `x` \<= INT32_MAX.

## Availability

- **C++ equivalent:** [`shz::ceilf`](https://sh4zam.com/api/cpp/#shzceilf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:92`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L92)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Rounding"


---
# shz_clampf

Source: https://sh4zam.com/api/scalar/shz_clampf/

> Clamps a floating-point value by the given min and max values

```c
SHZ_INLINE float shz_clampf(float value, float min, float max) SHZ_NOEXCEPT;
```

Clamps a floating-point value by the given `min` and `max` values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` | `float` |  |
| `min` | `float` |  |
| `max` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::clampf`](https://sh4zam.com/api/cpp/#shzclampf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:164`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L164)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Mapping"


---
# shz_copysignf

Source: https://sh4zam.com/api/scalar/shz_copysignf/

> Replacement for the <math.h> routine, copysignf()

```c
SHZ_INLINE float shz_copysignf(float x, float y) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, copysignf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |

## Returns

`float`

## Details

Returns the value of `x` with the sign of `y`.

## Warnings

- When `y == -0.0f`, a positive value is returned.

## Availability

- **C++ equivalent:** [`shz::copysignf`](https://sh4zam.com/api/cpp/#shzcopysignf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:212`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L212)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_divf_fsrra

Source: https://sh4zam.com/api/scalar/shz_divf_fsrra/

> Divides num by denom using a very fast approximation, which requires denom be a positive value

```c
SHZ_INLINE float shz_divf_fsrra(float num, float denom) SHZ_NOEXCEPT;
```

Divides `num` by `denom` using a very fast approximation, which requires `denom` be a positive value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `num` | `float` |  |
| `denom` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_fsrra`: Uses `FSRRA` (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::divf_fsrra`](https://sh4zam.com/api/cpp/#shzdivf_fsrra)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:295`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L295)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FSRRA"


---
# shz_divf

Source: https://sh4zam.com/api/scalar/shz_divf/

> Divides num by denom using a slightly faster approximation, allowing denom to be negative

```c
SHZ_INLINE float shz_divf(float num, float denom) SHZ_NOEXCEPT;
```

Divides `num` by `denom` using a slightly faster approximation, allowing `denom` to be negative.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `num` | `float` |  |
| `denom` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::divf`](https://sh4zam.com/api/cpp/#shzdivf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:298`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L298)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FSRRA"


---
# shz_dot6f

Source: https://sh4zam.com/api/scalar/shz_dot6f/

```c
SHZ_INLINE float shz_dot6f(float x1, float y1, float z1, float x2, float y2, float z2) SHZ_NOEXCEPT;
```

Takes two sets of 3D vectors as 3 floats and calculates their dot product using an approximation.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x1` | `float` |  |
| `y1` | `float` |  |
| `z1` | `float` |  |
| `x2` | `float` |  |
| `y2` | `float` |  |
| `z2` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::dot6f`](https://sh4zam.com/api/cpp/#shzdot6f)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:309`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L309)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FIPR"


---
# shz_dot8f

Source: https://sh4zam.com/api/scalar/shz_dot8f/

```c
SHZ_INLINE float shz_dot8f(float x1, float y1, float z1, float w1, float x2, float y2, float z2, float w2) SHZ_NOEXCEPT;
```

Takes two sets of 4D vectors as 4 floats and calculates their dot product using an approximation.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x1` | `float` |  |
| `y1` | `float` |  |
| `z1` | `float` |  |
| `w1` | `float` |  |
| `x2` | `float` |  |
| `y2` | `float` |  |
| `z2` | `float` |  |
| `w2` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::dot8f`](https://sh4zam.com/api/cpp/#shzdot8f)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:313`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L313)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FIPR"


---
# shz_equalf_abs

Source: https://sh4zam.com/api/scalar/shz_equalf_abs/

> Checks for equality based on the absolute tolerance using SHZ_FLT_EPSILON

```c
SHZ_INLINE bool shz_equalf_abs(float a, float b) SHZ_NOEXCEPT;
```

Checks for equality based on the absolute tolerance using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `float` |  |
| `b` | `float` |  |

## Returns

`bool`

## Availability

- **C++ equivalent:** [`shz::equalf_abs`](https://sh4zam.com/api/cpp/#shzequalf_abs)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:59`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L59)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Comparisons"


---
# shz_equalf_rel

Source: https://sh4zam.com/api/scalar/shz_equalf_rel/

> Checks for equality based on the relative tolerance using SHZ_FLT_EPSILON

```c
SHZ_INLINE bool shz_equalf_rel(float a, float b) SHZ_NOEXCEPT;
```

Checks for equality based on the relative tolerance using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `float` |  |
| `b` | `float` |  |

## Returns

`bool`

## Availability

- **C++ equivalent:** [`shz::equalf_rel`](https://sh4zam.com/api/cpp/#shzequalf_rel)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:62`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L62)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Comparisons"


---
# shz_equalf

Source: https://sh4zam.com/api/scalar/shz_equalf/

> Checks for equality based on EITHER the absolute tolerance or relative tolerance, using SHZ_FLT_EPSILON

```c
SHZ_INLINE bool shz_equalf(float a, float b) SHZ_NOEXCEPT;
```

Checks for equality based on EITHER the absolute tolerance or relative tolerance, using [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `float` |  |
| `b` | `float` |  |

## Returns

`bool`

## Availability

- **C++ equivalent:** [`shz::equalf`](https://sh4zam.com/api/cpp/#shzequalf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:56`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L56)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Comparisons"


---
# shz_expf

Source: https://sh4zam.com/api/scalar/shz_expf/

```c
SHZ_INLINE float shz_expf(float p) SHZ_NOEXCEPT;
```

Fast approximation for C's expf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `p` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::expf`](https://sh4zam.com/api/cpp/#shzexpf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:348`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L348)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Transcendental"


---
# shz_fabsf

Source: https://sh4zam.com/api/scalar/shz_fabsf/

> Replacement for the <math.h> routine, fabsf()

```c
SHZ_INLINE float shz_fabsf(float x) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, fabsf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Details

Returns the absolute value of `x`.

## Availability

- **C++ equivalent:** [`shz::fabsf`](https://sh4zam.com/api/cpp/#shzfabsf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:204`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L204)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_fdimf

Source: https://sh4zam.com/api/scalar/shz_fdimf/

> Replacement for the <math.h> routine, fdimf(),

```c
SHZ_INLINE float shz_fdimf(float x, float y) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, fdimf(),.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |

## Returns

`float`

## Details

Returns the positive difference between `x` and `y` or zero if y >= x.

## Warnings

- Unlike fdimf(), this routine does not handle INF and NAN values.

## Availability

- **C++ equivalent:** [`shz::fdimf`](https://sh4zam.com/api/cpp/#shzfdimf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:228`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L228)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_floorf

Source: https://sh4zam.com/api/scalar/shz_floorf/

> Replacement for the <math.h> routine, floorf()

```c
SHZ_INLINE float shz_floorf(float x) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, floorf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Details

Returns the closest integral value to `x`, rounded down, as a float.

## Warnings

- This routine is only valid for for the range INT32_MIN \<= `x` \<= INT32_MAX.

## Availability

- **C++ equivalent:** [`shz::floorf`](https://sh4zam.com/api/cpp/#shzfloorf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:80`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L80)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Rounding"


---
# SHZ_FLT_EPSILON

Source: https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/

```c
#define SHZ_FLT_EPSILON 0.01f
```

Floating-point epsilon used with inexact FP-based comparisons.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_scalar.h:40`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L40)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Macros"


---
# shz_fmaf

Source: https://sh4zam.com/api/scalar/shz_fmaf/

> Replacement for the <math.h> routine, fmaf()

```c
SHZ_INLINE float shz_fmaf(float a, float b, float c) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, fmaf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `float` |  |
| `b` | `float` |  |
| `c` | `float` |  |

## Returns

`float`

## Details

Returns `a` \* `b` + `c`, performing an FP multiply + accumulate operation.

## Availability

- **C++ equivalent:** [`shz::fmaf`](https://sh4zam.com/api/cpp/#shzfmaf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:218`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L218)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_fmaxf

Source: https://sh4zam.com/api/scalar/shz_fmaxf/

```c
SHZ_INLINE float shz_fmaxf(float a, float b) SHZ_NOEXCEPT;
```

Returns the maximum value of two given floats.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `float` |  |
| `b` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::fmaxf`](https://sh4zam.com/api/cpp/#shzfmaxf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:53`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L53)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Comparisons"


---
# shz_fminf

Source: https://sh4zam.com/api/scalar/shz_fminf/

```c
SHZ_INLINE float shz_fminf(float a, float b) SHZ_NOEXCEPT;
```

Returns the minimum value of two given floats.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `float` |  |
| `b` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::fminf`](https://sh4zam.com/api/cpp/#shzfminf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:50`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L50)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Comparisons"


---
# shz_fmodf

Source: https://sh4zam.com/api/scalar/shz_fmodf/

> Replacement for the <math.h> routine, fmodf()

```c
SHZ_INLINE float shz_fmodf(float num, float denom) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, fmodf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `num` | `float` |  |
| `denom` | `float` |  |

## Returns

`float`

## Details

Returns the floating-point remainder of `num` divided by `denom`, rounded towards zero.

## Warnings

- This routine does not gracefully handle dividing by zero.

## Availability

- **C++ equivalent:** [`shz::fmodf`](https://sh4zam.com/api/cpp/#shzfmodf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:137`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L137)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Rounding"

## See also

[`shz_remainderf`](https://sh4zam.com/api/scalar/shz_remainderf/)


---
# shz_fractf

Source: https://sh4zam.com/api/scalar/shz_fractf/

> Returns the fractional part of x, equivalent to GLSL fract()

```c
SHZ_INLINE float shz_fractf(float x) SHZ_NOEXCEPT;
```

Returns the fractional part of `x`, equivalent to GLSL `fract()`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::fractf`](https://sh4zam.com/api/cpp/#shzfractf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:185`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L185)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Mapping"


---
# shz_hypotf

Source: https://sh4zam.com/api/scalar/shz_hypotf/

> Replacement for the <math.h> routine, hypotf()

```c
SHZ_INLINE float shz_hypotf(float x, float y) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, hypotf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |

## Returns

`float`

## Details

Returns the hypoteneuse of the right triangle with the given legs.

## Warnings

- Unlike hypotf(), this routine has no error or overflow handling.

## Availability

- **C++ equivalent:** [`shz::hypotf`](https://sh4zam.com/api/cpp/#shzhypotf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:237`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L237)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_inv_sqrtf_fsrra

Source: https://sh4zam.com/api/scalar/shz_inv_sqrtf_fsrra/

> Calculates 1.0f/sqrtf( x), using a fast approximation

```c
SHZ_INLINE float shz_inv_sqrtf_fsrra(float x) SHZ_NOEXCEPT;
```

Calculates 1.0f/sqrtf( `x`), using a fast approximation.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_fsrra`: Uses `FSRRA` (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::inv_sqrtf_fsrra`](https://sh4zam.com/api/cpp/#shzinv_sqrtf_fsrra)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:277`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L277)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FSRRA"


---
# shz_inv_sqrtf

Source: https://sh4zam.com/api/scalar/shz_inv_sqrtf/

> Calculates 1.0f/sqrtf( x ), using a fast approximation, while safely protecting against division-by-zero

```c
SHZ_INLINE float shz_inv_sqrtf(float x) SHZ_NOEXCEPT;
```

Calculates 1.0f/sqrtf( `x` ), using a fast approximation, while safely protecting against division-by-zero.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::inv_sqrtf`](https://sh4zam.com/api/cpp/#shzinv_sqrtf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:280`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L280)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FSRRA"


---
# shz_invf_fsrra

Source: https://sh4zam.com/api/scalar/shz_invf_fsrra/

> Takes the inverse of x using a very fast approximation, returning a positive result

```c
SHZ_INLINE float shz_invf_fsrra(float x) SHZ_NOEXCEPT;
```

Takes the inverse of `x` using a very fast approximation, returning a positive result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_fsrra`: Uses `FSRRA` (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::invf_fsrra`](https://sh4zam.com/api/cpp/#shzinvf_fsrra)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:289`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L289)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FSRRA"


---
# shz_invf

Source: https://sh4zam.com/api/scalar/shz_invf/

> Takes the inverse of x using a slighty faster approximation than doing a full division, safely handling negative values

```c
SHZ_INLINE float shz_invf(float x) SHZ_NOEXCEPT;
```

Takes the inverse of `x` using a slighty faster approximation than doing a full division, safely handling negative values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::invf`](https://sh4zam.com/api/cpp/#shzinvf), [`shz::operator/`](https://sh4zam.com/api/cpp/#shzoperator/), [`shz::quat::operator/=`](https://sh4zam.com/api/cpp/quat/)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:292`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L292)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FSRRA"


---
# shz_lerpf

Source: https://sh4zam.com/api/scalar/shz_lerpf/

> Returns a value that is linearly interpolated between a and b by the given ratio, t

```c
SHZ_INLINE float shz_lerpf(float a, float b, float t) SHZ_NOEXCEPT;
```

Returns a value that is linearly interpolated between `a` and `b` by the given ratio, `t`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `float` |  |
| `b` | `float` |  |
| `t` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::lerpf`](https://sh4zam.com/api/cpp/#shzlerpf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:246`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L246)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_log2f

Source: https://sh4zam.com/api/scalar/shz_log2f/

```c
SHZ_INLINE float shz_log2f(float x) SHZ_NOEXCEPT;
```

Fast approximation for C's log2f().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::log2f`](https://sh4zam.com/api/cpp/#shzlog2f)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:339`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L339)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Transcendental"


---
# shz_log10f

Source: https://sh4zam.com/api/scalar/shz_log10f/

```c
SHZ_INLINE float shz_log10f(float x) SHZ_NOEXCEPT;
```

Fast approximation for C's log10f().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::log10f`](https://sh4zam.com/api/cpp/#shzlog10f)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:345`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L345)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Transcendental"


---
# shz_logf

Source: https://sh4zam.com/api/scalar/shz_logf/

```c
SHZ_INLINE float shz_logf(float x) SHZ_NOEXCEPT;
```

Fast approximation for C's logf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::logf`](https://sh4zam.com/api/cpp/#shzlogf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:342`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L342)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Transcendental"


---
# shz_mag_sqr3f

Source: https://sh4zam.com/api/scalar/shz_mag_sqr3f/

```c
SHZ_INLINE float shz_mag_sqr3f(float x, float y, float z) SHZ_NOEXCEPT;
```

Takes a 3D vector as 3 floats and calculates its squared magnitude using a fast approximation.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::mag_sqr3f`](https://sh4zam.com/api/cpp/#shzmag_sqr3f)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:317`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L317)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FIPR"


---
# shz_mag_sqr4f

Source: https://sh4zam.com/api/scalar/shz_mag_sqr4f/

```c
SHZ_INLINE float shz_mag_sqr4f(float x, float y, float z, float w) SHZ_NOEXCEPT;
```

Takes a 4D vector as 4 floats and calculates its squared magnitude using a fast approximation.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |
| `w` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::mag_sqr4f`](https://sh4zam.com/api/cpp/#shzmag_sqr4f)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:320`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L320)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FIPR"


---
# shz_normalizef_fsrra

Source: https://sh4zam.com/api/scalar/shz_normalizef_fsrra/

> Maps a value within the given range from to to, to be within the range of 0.0f + 1.0f more quickly, provided to - from is a positive difference

```c
SHZ_INLINE float shz_normalizef_fsrra(float current, float from, float to) SHZ_NOEXCEPT;
```

Maps a value within the given range `from` to `to`, to be within the range of `0.0f + 1.0f` more quickly, provided `to` - `from` is a positive difference.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `current` | `float` |  |
| `from` | `float` |  |
| `to` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_fsrra`: Uses `FSRRA` (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::normalizef_fsrra`](https://sh4zam.com/api/cpp/#shznormalizef_fsrra)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:170`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L170)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Mapping"


---
# shz_normalizef

Source: https://sh4zam.com/api/scalar/shz_normalizef/

> Maps a value within the given range from to to, to be within the range of 0.0f += 1.0f

```c
SHZ_INLINE float shz_normalizef(float current, float from, float to) SHZ_NOEXCEPT;
```

Maps a value within the given range `from` to `to`, to be within the range of `0.0f += 1.0f`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `current` | `float` |  |
| `from` | `float` |  |
| `to` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::normalizef`](https://sh4zam.com/api/cpp/#shznormalizef)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:167`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L167)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Mapping"


---
# shz_pow2f

Source: https://sh4zam.com/api/scalar/shz_pow2f/

```c
SHZ_INLINE float shz_pow2f(float p) SHZ_NOEXCEPT;
```

Fast approximation for raising 2 to a floating-point power.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `p` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::pow2f`](https://sh4zam.com/api/cpp/#shzpow2f)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:330`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L330)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Transcendental"


---
# shz_pow10f

Source: https://sh4zam.com/api/scalar/shz_pow10f/

```c
SHZ_INLINE float shz_pow10f(float x) SHZ_NOEXCEPT;
```

Fast approximation of POSIX's pow10f().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::pow10f`](https://sh4zam.com/api/cpp/#shzpow10f)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:336`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L336)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Transcendental"


---
# shz_powf

Source: https://sh4zam.com/api/scalar/shz_powf/

```c
SHZ_INLINE float shz_powf(float x, float p) SHZ_NOEXCEPT;
```

Fast approximation for C's powf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `p` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::powf`](https://sh4zam.com/api/cpp/#shzpowf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:333`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L333)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Transcendental"


---
# shz_quadratic_roots

Source: https://sh4zam.com/api/scalar/shz_quadratic_roots/

> Uses the quadratic formula with the given coefficients to solve for the two roots, returning true if any real roots exist, and false if the roots are only..

```c
SHZ_INLINE bool shz_quadratic_roots(float a, float b, float c, float* root1, float* root2) SHZ_NOEXCEPT;
```

Uses the quadratic formula with the given coefficients to solve for the two roots, returning `true` if any real roots exist, and `false` if the roots are only imaginary.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `float` |  |
| `b` | `float` |  |
| `c` | `float` |  |
| `root1` | `float *` |  |
| `root2` | `float *` |  |

## Returns

`bool`

## Availability

- **C++ equivalent:** [`shz::quadratic_roots`](https://sh4zam.com/api/cpp/#shzquadratic_roots)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:252`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L252)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_randf_range

Source: https://sh4zam.com/api/scalar/shz_randf_range/

> Returns a random floating-point number between min and max, using and updating the given seed

```c
SHZ_INLINE float shz_randf_range(int* seed, float min, float max) SHZ_NOEXCEPT;
```

Returns a random floating-point number between `min` and `max`, using and updating the given seed.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `seed` | `int *` |  |
| `min` | `float` |  |
| `max` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::randf_range`](https://sh4zam.com/api/cpp/#shzrandf_range)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:258`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L258)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_randf

Source: https://sh4zam.com/api/scalar/shz_randf/

> Returns a random floating-point number between 0.0f and 1.0f, using and updating the given seed

```c
SHZ_INLINE float shz_randf(int* seed) SHZ_NOEXCEPT;
```

Returns a random floating-point number between `0.0f` and `1.0f`, using and updating the given seed.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `seed` | `int *` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::randf`](https://sh4zam.com/api/cpp/#shzrandf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:255`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L255)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_remainderf

Source: https://sh4zam.com/api/scalar/shz_remainderf/

> Replacement for the <math.h> routine, remainderf()

```c
SHZ_INLINE float shz_remainderf(float num, float denom) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, remainderf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `num` | `float` |  |
| `denom` | `float` |  |

## Returns

`float`

## Details

Returns the floating-point remainder of `num` divided by `denom`, rounded to the nearest integer (as a float).

## Warnings

- This routine does not gracefully handle dividing by zero, and it is only valid for the input range INT32_MIN \<= `num` / `denom` \<= INT32_MAX.

## Availability

- **C++ equivalent:** [`shz::remainderf`](https://sh4zam.com/api/cpp/#shzremainderf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:125`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L125)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Rounding"

## See also

[`shz_fmodf`](https://sh4zam.com/api/scalar/shz_fmodf/), [`shz_remquof`](https://sh4zam.com/api/scalar/shz_remquof/), [`shz_truncf`](https://sh4zam.com/api/scalar/shz_truncf/)


---
# shz_remapf_fsrra

Source: https://sh4zam.com/api/scalar/shz_remapf_fsrra/

> Maps a value within the given range inputStart to inputEnd, to be within the range of outputStart to outputEnd more quickly, provided the outputEnd -..

```c
SHZ_INLINE float shz_remapf_fsrra(float value, float inputStart, float inputEnd, float outputStart, float outputEnd) SHZ_NOEXCEPT;
```

Maps a value within the given range `inputStart` to `inputEnd`, to be within the range of `outputStart` to `outputEnd` more quickly, provided the `outputEnd` - `outputStart` is a positive difference.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` | `float` |  |
| `inputStart` | `float` |  |
| `inputEnd` | `float` |  |
| `outputStart` | `float` |  |
| `outputEnd` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_fsrra`: Uses `FSRRA` (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::remapf_fsrra`](https://sh4zam.com/api/cpp/#shzremapf_fsrra)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:176`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L176)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Mapping"


---
# shz_remapf

Source: https://sh4zam.com/api/scalar/shz_remapf/

> Maps a value within the given range inputStart to inputEnd, to be within the range of outputStart to outputEnd

```c
SHZ_INLINE float shz_remapf(float value, float inputStart, float inputEnd, float outputStart, float outputEnd) SHZ_NOEXCEPT;
```

Maps a value within the given range `inputStart` to `inputEnd`, to be within the range of `outputStart` to `outputEnd`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` | `float` |  |
| `inputStart` | `float` |  |
| `inputEnd` | `float` |  |
| `outputStart` | `float` |  |
| `outputEnd` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::remapf`](https://sh4zam.com/api/cpp/#shzremapf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:173`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L173)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Mapping"


---
# shz_remquof

Source: https://sh4zam.com/api/scalar/shz_remquof/

> (Sorta) Replacement for the <math.h> routine, remquof()

```c
SHZ_INLINE float shz_remquof(float num, float denom, float* quot) SHZ_NOEXCEPT;
```

(Sorta) Replacement for the \<math.h> routine, remquof().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `num` | `float` |  |
| `denom` | `float` |  |
| `quot` | `float *` |  |

## Returns

`float`

## Details

Returns the floating-point remainder of `num` divided by `denom`, rounded to the nearest integer (as a float). `quot` is set equal to the quotient which is used as part of the calculation.

## Notes

- `quot` is returning as a `float` rather than an `int` as with standard C. Simply cast to an `int` manually afterwards if that is the desired behavior.

## Warnings

- This routine does not gracefully handle dividing by zero.

## Availability

- **C++ equivalent:** [`shz::remquof`](https://sh4zam.com/api/cpp/#shzremquof)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:154`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L154)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Rounding"

## See also

[`shz_remainderf`](https://sh4zam.com/api/scalar/shz_remainderf/)


---
# shz_roundf

Source: https://sh4zam.com/api/scalar/shz_roundf/

> Replacement for the <math.h> routine, roundf()

```c
SHZ_INLINE float shz_roundf(float x) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, roundf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Details

Returns the value of `x` rounded to the nearest integer, as a float.

## Warnings

- This routine only returns valid values for the input range -UINT32_MAX \<= `x` \<= UINT32_MAX.

## Availability

- **C++ equivalent:** [`shz::roundf`](https://sh4zam.com/api/cpp/#shzroundf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:102`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L102)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Rounding"


---
# shz_saturatef

Source: https://sh4zam.com/api/scalar/shz_saturatef/

> Clamps x to the range [0.0f, 1.0f]

```c
SHZ_INLINE float shz_saturatef(float x) SHZ_NOEXCEPT;
```

Clamps `x` to the range \[0.0f, 1.0f\].

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::saturatef`](https://sh4zam.com/api/cpp/#shzsaturatef)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:191`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L191)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Mapping"


---
# shz_signf

Source: https://sh4zam.com/api/scalar/shz_signf/

> Returns -1.0f if x < 0, 0.0f if x == 0, or 1.0f if x > 0

```c
SHZ_INLINE float shz_signf(float x) SHZ_NOEXCEPT;
```

Returns -1.0f if `x` \< 0, 0.0f if `x` == 0, or 1.0f if `x` > 0.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::signf`](https://sh4zam.com/api/cpp/#shzsignf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:188`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L188)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Mapping"


---
# shz_smoothstepf_safe

Source: https://sh4zam.com/api/scalar/shz_smoothstepf_safe/

```c
SHZ_INLINE float shz_smoothstepf_safe(float x, float edge0, float edge1) SHZ_NOEXCEPT;
```

Returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. Accepts inverse edges.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `edge0` | `float` |  |
| `edge1` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::smoothstepf_safe`](https://sh4zam.com/api/cpp/#shzsmoothstepf_safe)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:267`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L267)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_smoothstepf

Source: https://sh4zam.com/api/scalar/shz_smoothstepf/

```c
SHZ_INLINE float shz_smoothstepf(float x, float edge0, float edge1) SHZ_NOEXCEPT;
```

Returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. edge0 must be less than edge1 or result is undefined.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `edge0` | `float` |  |
| `edge1` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::smoothstepf`](https://sh4zam.com/api/cpp/#shzsmoothstepf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:264`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L264)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_sqrtf_fsrra

Source: https://sh4zam.com/api/scalar/shz_sqrtf_fsrra/

> Returns the fast approximate square root of the given value, x

```c
SHZ_INLINE float shz_sqrtf_fsrra(float x) SHZ_NOEXCEPT;
```

Returns the fast approximate square root of the given value, `x`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_fsrra`: Uses `FSRRA` (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::sqrtf_fsrra`](https://sh4zam.com/api/cpp/#shzsqrtf_fsrra)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:283`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L283)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FSRRA"


---
# shz_sqrtf

Source: https://sh4zam.com/api/scalar/shz_sqrtf/

> Returns the fast approximate square root of the given value, x, safely returning 0.0f is x == 0.0f

```c
SHZ_INLINE float shz_sqrtf(float x) SHZ_NOEXCEPT;
```

Returns the fast approximate square root of the given value, `x`, safely returning `0.0f` is `x` == `0.0f`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::sqrtf`](https://sh4zam.com/api/cpp/#shzsqrtf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:286`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L286)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "FSRRA"


---
# shz_stepf

Source: https://sh4zam.com/api/scalar/shz_stepf/

> returns 0.0f if x < edge, otherwise 1.0f

```c
SHZ_INLINE float shz_stepf(float x, float edge) SHZ_NOEXCEPT;
```

returns 0.0f if x \< edge, otherwise 1.0f

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `edge` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::stepf`](https://sh4zam.com/api/cpp/#shzstepf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:261`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L261)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Miscellaneous"


---
# shz_truncf

Source: https://sh4zam.com/api/scalar/shz_truncf/

> Replacement for the <math.h> routine, truncf()

```c
SHZ_INLINE float shz_truncf(float x) SHZ_NOEXCEPT;
```

Replacement for the \<math.h> routine, truncf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Details

Returns the value of `with` its fractional component discarded.

## Warnings

- This routine only returns valid values for the input range INT32_MIN \<= `x` \<= INT32_MAX.

## Availability

- **C++ equivalent:** [`shz::truncf`](https://sh4zam.com/api/cpp/#shztruncf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:112`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L112)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Rounding"


---
# shz_wrapf_fsrra

Source: https://sh4zam.com/api/scalar/shz_wrapf_fsrra/

> Wraps the given value back to be within the range of min to max more quickly, provided max - min is a positive difference

```c
SHZ_INLINE float shz_wrapf_fsrra(float value, float min, float max) SHZ_NOEXCEPT;
```

Wraps the given `value` back to be within the range of `min` to `max` more quickly, provided `max` - `min` is a positive difference.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` | `float` |  |
| `min` | `float` |  |
| `max` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_fsrra`: Uses `FSRRA` (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::wrapf_fsrra`](https://sh4zam.com/api/cpp/#shzwrapf_fsrra)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:182`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L182)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Mapping"


---
# shz_wrapf

Source: https://sh4zam.com/api/scalar/shz_wrapf/

> Wraps the given value back to be within the range of min to max

```c
SHZ_INLINE float shz_wrapf(float value, float min, float max) SHZ_NOEXCEPT;
```

Wraps the given `value` back to be within the range of `min` to `max`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` | `float` |  |
| `min` | `float` |  |
| `max` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::wrapf`](https://sh4zam.com/api/cpp/#shzwrapf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_scalar.h:179`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_scalar.h#L179)
- **Module:** [Scalar](https://sh4zam.com/api/scalar/), section "Mapping"


---
# Trigonometry API

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

> Trig functions and utilities built around the SH4 FSCA instruction

The following API provides a series of routines implementing trigonometric functions. While some of these are specialized, many are meant to be drop-in replacements for the equivalent functions provided by `<math.h>`. The SH4 provides a single instruction, `FSCA`, for retrieving fast approximations of both the sine and cosine of a given angle, so when you need both values it is most efficient to grab them at once as a `shz_sincos_t` pair. Angles are in radians by default; `_deg` variants take degrees and `u16` variants take the 16-bit fixed-point angle that `FSCA` consumes natively.

- **C header:** `#include <sh4zam/shz_trig.h>`
- **C++ header:** `#include <sh4zam/shz_trig.hpp>`
- **C++ types:** [`shz::sincos`](https://sh4zam.com/api/cpp/sincos/)
- **Symbols:** 51

## Suffixes

Suffixes used in this module. The full list is in [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/).

- `_deg`: Angle argument is in degrees. The default is radians.
- `u16`: Angle is a 16-bit fixed-point value: 0..65535 maps to 0..2π, the native `FSCA` input format.
- `_fsrra`: Uses `FSRRA` (fast approximate 1/sqrt(x)). The argument or denominator must be positive. Faster, less precise.

## Sin/Cos Pairs

Routines involving precomputed sine + cosine pairs.

| Symbol | Description |
| --- | --- |
| [`shz_sincosu16`](https://sh4zam.com/api/trig/shz_sincosu16/) | Returns sinf()/cosf() pairs for the given unsigned 16-bit angle in radians. |
| [`shz_sincosf`](https://sh4zam.com/api/trig/shz_sincosf/) | Returns sinf()/cosf() pairs for the given floating-point angle in radians. |
| [`shz_sincosf_deg`](https://sh4zam.com/api/trig/shz_sincosf_deg/) | Returns sinf/cosf() pairs for the given floating-point angle in degrees. |
| [`shz_sincos_tanf`](https://sh4zam.com/api/trig/shz_sincos_tanf/) | Returns tanf() from the given pre-computed `sincos` pair. |
| [`shz_sincos_secf`](https://sh4zam.com/api/trig/shz_sincos_secf/) | Returns the floating-point secant (1.0f / cosf(x)) from the given pre-computed `sincos` pair. |
| [`shz_sincos_cscf`](https://sh4zam.com/api/trig/shz_sincos_cscf/) | Returns the floating-point cosecant (1.0f / sinf(x)) from the given pre-computed `sincos` pair. |
| [`shz_sincos_cotf`](https://sh4zam.com/api/trig/shz_sincos_cotf/) | Returns the floating-point cotangent (1.0f / tanf(x)) from the given pre-computed `sincos` pair. |

## Independent Functions

Routines providing single trigonometric functions.

| Symbol | Description |
| --- | --- |
| [`shz_sinf`](https://sh4zam.com/api/trig/shz_sinf/) | One-off routine for returning only sinf() from an angle in radians. |
| [`shz_sinf_deg`](https://sh4zam.com/api/trig/shz_sinf_deg/) | One-off routine for returning only sinf() from an angle in degrees. |
| [`shz_cosf`](https://sh4zam.com/api/trig/shz_cosf/) | One-off routine for returning only cosf() from an angle in radians. |
| [`shz_cosf_deg`](https://sh4zam.com/api/trig/shz_cosf_deg/) | One-off routine for returning only cosf() from an angle in degrees. |
| [`shz_tanf`](https://sh4zam.com/api/trig/shz_tanf/) | One-off routine for returning only tanf() from an angle in radians. |
| [`shz_tanf_deg`](https://sh4zam.com/api/trig/shz_tanf_deg/) | One-off routine for returning only tanf() from an angle in degrees. |
| [`shz_secf`](https://sh4zam.com/api/trig/shz_secf/) | One-off routine for returning only secant (1 / cos(x)) from an angle in radians. |
| [`shz_secf_deg`](https://sh4zam.com/api/trig/shz_secf_deg/) | One-off routine for returning only secant (1 / cos(x)) from an angle in degrees. |
| [`shz_cscf`](https://sh4zam.com/api/trig/shz_cscf/) | One-off routine for returning only cosecant (1 / sin(x)) from an angle in radians. |
| [`shz_cscf_deg`](https://sh4zam.com/api/trig/shz_cscf_deg/) | One-off routine for returning only cosecant (1 / sin(x)) from an angle in degrees. |
| [`shz_cotf`](https://sh4zam.com/api/trig/shz_cotf/) | One-off routine for returning only cotangent (1 / tan(x)) from an angle in radians. |
| [`shz_cotf_deg`](https://sh4zam.com/api/trig/shz_cotf_deg/) | One-off routine for returning only cotangent (1 / cot(x)) from an angle in degrees. |

## Inverse Functions

Routines providing inverse trigonometric functions.

| Symbol | Description |
| --- | --- |
| [`shz_asinf`](https://sh4zam.com/api/trig/shz_asinf/) | Fast arcsine approximation; equivalent to C's asinf(). |
| [`shz_acosf`](https://sh4zam.com/api/trig/shz_acosf/) | Fast arccosine approximation; equivalent to C's acosf(). |
| [`shz_atanf_unit`](https://sh4zam.com/api/trig/shz_atanf_unit/) | Fast arctangent approximation for unit values between `0.0f` and `1.0f`. |
| [`shz_atanf_q1`](https://sh4zam.com/api/trig/shz_atanf_q1/) | Fast arctangent approximation for values lying within the first quadrant (`>= 0.0f`). |
| [`shz_atanf`](https://sh4zam.com/api/trig/shz_atanf/) | Fast arctangent approximation; equvalent to C's atanf(). |
| [`shz_atan2f`](https://sh4zam.com/api/trig/shz_atan2f/) | Computes arctangent of `y / x`, using the signs of arguments to determine correct quadtrant. Equivalent to C's atan2f(). |
| [`shz_asecf`](https://sh4zam.com/api/trig/shz_asecf/) | Fast arcsecant/inverse secant approximation, taking units in radians. |
| [`shz_acscf`](https://sh4zam.com/api/trig/shz_acscf/) | Fast arccosecant/inverse cosecant approximation; taking units in radians. |
| [`shz_acotf`](https://sh4zam.com/api/trig/shz_acotf/) | Fast arccotangent/inverse cotangent approximation; taking units in radians. |

## Hyperbolic Functions

Trigonometric functions for hyperbolas

| Symbol | Description |
| --- | --- |
| [`shz_sinhf`](https://sh4zam.com/api/trig/shz_sinhf/) | Fast hyperbolic sine function. |
| [`shz_coshf`](https://sh4zam.com/api/trig/shz_coshf/) | Fast hyperbolic cosine function. |
| [`shz_tanhf`](https://sh4zam.com/api/trig/shz_tanhf/) | Fast hyperbolic tangent function. |
| [`shz_cschf`](https://sh4zam.com/api/trig/shz_cschf/) | Fast hyperbolic cosecant function. |
| [`shz_sechf`](https://sh4zam.com/api/trig/shz_sechf/) | Fast hyperbolic secant function. |
| [`shz_cothf`](https://sh4zam.com/api/trig/shz_cothf/) | Fast hyperbolic cotangent function. |

## Inverse Hyperbolic Functions

Inverse trigonometric functions for hyperbolas

| Symbol | Description |
| --- | --- |
| [`shz_asinhf`](https://sh4zam.com/api/trig/shz_asinhf/) | Fast hyperbolic arcsine function. |
| [`shz_acoshf`](https://sh4zam.com/api/trig/shz_acoshf/) | Fast hyperbolic arccosine function. |
| [`shz_atanhf`](https://sh4zam.com/api/trig/shz_atanhf/) | Fast hyperbolic arctangent function. |
| [`shz_acschf`](https://sh4zam.com/api/trig/shz_acschf/) | Fast hyperbolic arccosecant function. |
| [`shz_asechf`](https://sh4zam.com/api/trig/shz_asechf/) | Fast hyperbolic arcsecant function. |
| [`shz_acothf`](https://sh4zam.com/api/trig/shz_acothf/) | Fast hyperbolic arccotangent function. |

## Macros

| Symbol | Description |
| --- | --- |
| [`SHZ_F_PI`](https://sh4zam.com/api/trig/SHZ_F_PI/) | Single-precision floating-point PI approximation (do not use M_PI!). |
| [`SHZ_F_TAU`](https://sh4zam.com/api/trig/SHZ_F_TAU/) | Single-precision FP PI approximation times 2. |
| [`SHZ_F_PI_2`](https://sh4zam.com/api/trig/SHZ_F_PI_2/) | Single-precision FP PI approximation divided by 2. |
| [`SHZ_F_PI_4`](https://sh4zam.com/api/trig/SHZ_F_PI_4/) | Single-precision FP PI approximation divided by 4. |
| [`SHZ_FSCA_RAD_FACTOR`](https://sh4zam.com/api/trig/SHZ_FSCA_RAD_FACTOR/) | Multiplicative factor for passing the FSCA instruction angles in radians. |
| [`SHZ_FSCA_DEG_FACTOR`](https://sh4zam.com/api/trig/SHZ_FSCA_DEG_FACTOR/) | Multiplicative factor for passing the FSCA instrution angles in degrees. |
| [`SHZ_FSCA_ERROR_MAX`](https://sh4zam.com/api/trig/SHZ_FSCA_ERROR_MAX/) | Maximum FP error for FSCA instruction. |
| [`SHZ_DEG_TO_RAD`](https://sh4zam.com/api/trig/SHZ_DEG_TO_RAD/) | Converts the given angle in degrees to radians. |
| [`SHZ_RAD_TO_DEG`](https://sh4zam.com/api/trig/SHZ_RAD_TO_DEG/) | Converts the given angle in radians to degrees. |

## Types

| Symbol | Description |
| --- | --- |
| [`shz_sincos_t`](https://sh4zam.com/api/trig/shz_sincos_t/) | Pair representing the sine and cosine of a given angle. |
| [`shz_sincos`](https://sh4zam.com/api/trig/shz_sincos/) | Alternate C [`shz_sincos_t`](https://sh4zam.com/api/trig/shz_sincos_t/) typedef for those who hate POSIX style. |


---
# shz_acosf

Source: https://sh4zam.com/api/trig/shz_acosf/

```c
SHZ_INLINE float shz_acosf(float x) SHZ_NOEXCEPT;
```

Fast arccosine approximation; equivalent to C's acosf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::acosf`](https://sh4zam.com/api/cpp/#shzacosf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:145`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L145)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Functions"


---
# shz_acoshf

Source: https://sh4zam.com/api/trig/shz_acoshf/

```c
SHZ_INLINE float shz_acoshf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic arccosine function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::acoshf`](https://sh4zam.com/api/cpp/#shzacoshf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:204`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L204)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Hyperbolic Functions"


---
# shz_acotf

Source: https://sh4zam.com/api/trig/shz_acotf/

```c
SHZ_INLINE float shz_acotf(float x) SHZ_NOEXCEPT;
```

Fast arccotangent/inverse cotangent approximation; taking units in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::acotf`](https://sh4zam.com/api/cpp/#shzacotf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:166`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L166)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Functions"


---
# shz_acothf

Source: https://sh4zam.com/api/trig/shz_acothf/

```c
SHZ_INLINE float shz_acothf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic arccotangent function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::acothf`](https://sh4zam.com/api/cpp/#shzacothf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:216`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L216)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Hyperbolic Functions"


---
# shz_acscf

Source: https://sh4zam.com/api/trig/shz_acscf/

```c
SHZ_INLINE float shz_acscf(float x) SHZ_NOEXCEPT;
```

Fast arccosecant/inverse cosecant approximation; taking units in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::acscf`](https://sh4zam.com/api/cpp/#shzacscf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:163`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L163)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Functions"


---
# shz_acschf

Source: https://sh4zam.com/api/trig/shz_acschf/

```c
SHZ_INLINE float shz_acschf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic arccosecant function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::acschf`](https://sh4zam.com/api/cpp/#shzacschf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:210`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L210)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Hyperbolic Functions"


---
# shz_asecf

Source: https://sh4zam.com/api/trig/shz_asecf/

```c
SHZ_INLINE float shz_asecf(float x) SHZ_NOEXCEPT;
```

Fast arcsecant/inverse secant approximation, taking units in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::asecf`](https://sh4zam.com/api/cpp/#shzasecf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:160`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L160)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Functions"


---
# shz_asechf

Source: https://sh4zam.com/api/trig/shz_asechf/

```c
SHZ_INLINE float shz_asechf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic arcsecant function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::asechf`](https://sh4zam.com/api/cpp/#shzasechf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:213`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L213)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Hyperbolic Functions"


---
# shz_asinf

Source: https://sh4zam.com/api/trig/shz_asinf/

```c
SHZ_INLINE float shz_asinf(float x) SHZ_NOEXCEPT;
```

Fast arcsine approximation; equivalent to C's asinf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::asinf`](https://sh4zam.com/api/cpp/#shzasinf)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:142`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L142)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Functions"


---
# shz_asinhf

Source: https://sh4zam.com/api/trig/shz_asinhf/

```c
SHZ_INLINE float shz_asinhf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic arcsine function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::asinhf`](https://sh4zam.com/api/cpp/#shzasinhf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:201`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L201)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Hyperbolic Functions"


---
# shz_atan2f

Source: https://sh4zam.com/api/trig/shz_atan2f/

> Computes arctangent of y / x, using the signs of arguments to determine correct quadtrant. Equivalent to C's atan2f()

```c
SHZ_INLINE float shz_atan2f(float y, float x) SHZ_NOEXCEPT;
```

Computes arctangent of `y / x`, using the signs of arguments to determine correct quadtrant. Equivalent to C's atan2f().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `y` | `float` |  |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::atan2f`](https://sh4zam.com/api/cpp/#shzatan2f)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:157`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L157)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Functions"


---
# shz_atanf_q1

Source: https://sh4zam.com/api/trig/shz_atanf_q1/

> Fast arctangent approximation for values lying within the first quadrant (>= 0.0f)

```c
SHZ_INLINE float shz_atanf_q1(float x) SHZ_NOEXCEPT;
```

Fast arctangent approximation for values lying within the first quadrant (`>= 0.0f`).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::atanf_q1`](https://sh4zam.com/api/cpp/#shzatanf_q1)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:151`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L151)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Functions"


---
# shz_atanf_unit

Source: https://sh4zam.com/api/trig/shz_atanf_unit/

> Fast arctangent approximation for unit values between 0.0f and 1.0f

```c
SHZ_INLINE float shz_atanf_unit(float x) SHZ_NOEXCEPT;
```

Fast arctangent approximation for unit values between `0.0f` and `1.0f`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::atanf_unit`](https://sh4zam.com/api/cpp/#shzatanf_unit)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:148`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L148)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Functions"


---
# shz_atanf

Source: https://sh4zam.com/api/trig/shz_atanf/

```c
SHZ_INLINE float shz_atanf(float x) SHZ_NOEXCEPT;
```

Fast arctangent approximation; equvalent to C's atanf().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::atanf`](https://sh4zam.com/api/cpp/#shzatanf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:154`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L154)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Functions"


---
# shz_atanhf

Source: https://sh4zam.com/api/trig/shz_atanhf/

```c
SHZ_INLINE float shz_atanhf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic arctangent function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::atanhf`](https://sh4zam.com/api/cpp/#shzatanhf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:207`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L207)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Inverse Hyperbolic Functions"


---
# shz_cosf_deg

Source: https://sh4zam.com/api/trig/shz_cosf_deg/

```c
SHZ_INLINE float shz_cosf_deg(float degrees) SHZ_NOEXCEPT;
```

One-off routine for returning only cosf() from an angle in degrees.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `degrees` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_deg`: Angle argument is in degrees. The default is radians. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::cosf_deg`](https://sh4zam.com/api/cpp/#shzcosf_deg)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:108`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L108)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_cosf

Source: https://sh4zam.com/api/trig/shz_cosf/

```c
SHZ_INLINE float shz_cosf(float radians) SHZ_NOEXCEPT;
```

One-off routine for returning only cosf() from an angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::cosf`](https://sh4zam.com/api/cpp/#shzcosf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:105`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L105)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_coshf

Source: https://sh4zam.com/api/trig/shz_coshf/

```c
SHZ_INLINE float shz_coshf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic cosine function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::coshf`](https://sh4zam.com/api/cpp/#shzcoshf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:179`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L179)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Hyperbolic Functions"


---
# shz_cotf_deg

Source: https://sh4zam.com/api/trig/shz_cotf_deg/

```c
SHZ_INLINE float shz_cotf_deg(float degrees) SHZ_NOEXCEPT;
```

One-off routine for returning only cotangent (1 / cot(x)) from an angle in degrees.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `degrees` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_deg`: Angle argument is in degrees. The default is radians. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::cotf_deg`](https://sh4zam.com/api/cpp/#shzcotf_deg)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:132`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L132)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_cotf

Source: https://sh4zam.com/api/trig/shz_cotf/

```c
SHZ_INLINE float shz_cotf(float radians) SHZ_NOEXCEPT;
```

One-off routine for returning only cotangent (1 / tan(x)) from an angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::cotf`](https://sh4zam.com/api/cpp/#shzcotf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:129`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L129)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_cothf

Source: https://sh4zam.com/api/trig/shz_cothf/

```c
SHZ_INLINE float shz_cothf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic cotangent function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::cothf`](https://sh4zam.com/api/cpp/#shzcothf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:191`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L191)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Hyperbolic Functions"


---
# shz_cscf_deg

Source: https://sh4zam.com/api/trig/shz_cscf_deg/

```c
SHZ_INLINE float shz_cscf_deg(float degrees) SHZ_NOEXCEPT;
```

One-off routine for returning only cosecant (1 / sin(x)) from an angle in degrees.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `degrees` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_deg`: Angle argument is in degrees. The default is radians. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::cscf_deg`](https://sh4zam.com/api/cpp/#shzcscf_deg)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:126`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L126)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_cscf

Source: https://sh4zam.com/api/trig/shz_cscf/

```c
SHZ_INLINE float shz_cscf(float radians) SHZ_NOEXCEPT;
```

One-off routine for returning only cosecant (1 / sin(x)) from an angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::cscf`](https://sh4zam.com/api/cpp/#shzcscf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:123`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L123)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_cschf

Source: https://sh4zam.com/api/trig/shz_cschf/

```c
SHZ_INLINE float shz_cschf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic cosecant function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::cschf`](https://sh4zam.com/api/cpp/#shzcschf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:185`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L185)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Hyperbolic Functions"


---
# SHZ_DEG_TO_RAD

Source: https://sh4zam.com/api/trig/SHZ_DEG_TO_RAD/

```c
#define SHZ_DEG_TO_RAD(deg) ((deg) * SHZ_F_PI / 180.0f)
```

Converts the given angle in degrees to radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `deg` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_trig.h:42`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L42)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Macros"


---
# SHZ_F_PI_2

Source: https://sh4zam.com/api/trig/SHZ_F_PI_2/

```c
#define SHZ_F_PI_2 (SHZ_F_PI * 0.5f)
```

Single-precision FP PI approximation divided by 2.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_trig.h:31`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L31)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Macros"


---
# SHZ_F_PI_4

Source: https://sh4zam.com/api/trig/SHZ_F_PI_4/

```c
#define SHZ_F_PI_4 (SHZ_F_PI * 0.25f)
```

Single-precision FP PI approximation divided by 4.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_trig.h:33`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L33)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Macros"


---
# SHZ_F_PI

Source: https://sh4zam.com/api/trig/SHZ_F_PI/

```c
#define SHZ_F_PI 3.14159265359f
```

Single-precision floating-point PI approximation (do not use M_PI!).

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_trig.h:27`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L27)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Macros"


---
# SHZ_F_TAU

Source: https://sh4zam.com/api/trig/SHZ_F_TAU/

```c
#define SHZ_F_TAU (SHZ_F_PI * 2.0f)
```

Single-precision FP PI approximation times 2.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_trig.h:29`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L29)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Macros"


---
# SHZ_FSCA_DEG_FACTOR

Source: https://sh4zam.com/api/trig/SHZ_FSCA_DEG_FACTOR/

```c
#define SHZ_FSCA_DEG_FACTOR 182.04444443f
```

Multiplicative factor for passing the FSCA instrution angles in degrees.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_trig.h:37`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L37)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Macros"


---
# SHZ_FSCA_ERROR_MAX

Source: https://sh4zam.com/api/trig/SHZ_FSCA_ERROR_MAX/

```c
#define SHZ_FSCA_ERROR_MAX 4.76837158e-7
```

Maximum FP error for FSCA instruction.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_trig.h:39`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L39)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Macros"


---
# SHZ_FSCA_RAD_FACTOR

Source: https://sh4zam.com/api/trig/SHZ_FSCA_RAD_FACTOR/

```c
#define SHZ_FSCA_RAD_FACTOR 10430.37835f
```

Multiplicative factor for passing the FSCA instruction angles in radians.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_trig.h:35`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L35)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Macros"


---
# SHZ_RAD_TO_DEG

Source: https://sh4zam.com/api/trig/SHZ_RAD_TO_DEG/

```c
#define SHZ_RAD_TO_DEG(rad) ((rad) * 180.0f / SHZ_F_PI)
```

Converts the given angle in radians to degrees.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `rad` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_trig.h:44`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L44)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Macros"


---
# shz_secf_deg

Source: https://sh4zam.com/api/trig/shz_secf_deg/

```c
SHZ_INLINE float shz_secf_deg(float degrees) SHZ_NOEXCEPT;
```

One-off routine for returning only secant (1 / cos(x)) from an angle in degrees.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `degrees` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_deg`: Angle argument is in degrees. The default is radians. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::secf_deg`](https://sh4zam.com/api/cpp/#shzsecf_deg)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:120`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L120)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_secf

Source: https://sh4zam.com/api/trig/shz_secf/

```c
SHZ_INLINE float shz_secf(float radians) SHZ_NOEXCEPT;
```

One-off routine for returning only secant (1 / cos(x)) from an angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::secf`](https://sh4zam.com/api/cpp/#shzsecf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:117`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L117)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_sechf

Source: https://sh4zam.com/api/trig/shz_sechf/

```c
SHZ_INLINE float shz_sechf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic secant function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::sechf`](https://sh4zam.com/api/cpp/#shzsechf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:188`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L188)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Hyperbolic Functions"


---
# shz_sincos_cotf

Source: https://sh4zam.com/api/trig/shz_sincos_cotf/

> Returns the floating-point cotangent (1.0f / tanf(x)) from the given pre-computed sincos pair

```c
SHZ_INLINE float shz_sincos_cotf(shz_sincos_t sincos) SHZ_NOEXCEPT;
```

Returns the floating-point cotangent (1.0f / tanf(x)) from the given pre-computed `sincos` pair.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `sincos` | `shz_sincos_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::sincos::cotf`](https://sh4zam.com/api/cpp/sincos/#cotf), [`shz::sincos_cotf`](https://sh4zam.com/api/cpp/#shzsincos_cotf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:89`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L89)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Sin/Cos Pairs"


---
# shz_sincos_cscf

Source: https://sh4zam.com/api/trig/shz_sincos_cscf/

> Returns the floating-point cosecant (1.0f / sinf(x)) from the given pre-computed sincos pair

```c
SHZ_INLINE float shz_sincos_cscf(shz_sincos_t sincos) SHZ_NOEXCEPT;
```

Returns the floating-point cosecant (1.0f / sinf(x)) from the given pre-computed `sincos` pair.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `sincos` | `shz_sincos_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::sincos::cscf`](https://sh4zam.com/api/cpp/sincos/#cscf), [`shz::sincos_cscf`](https://sh4zam.com/api/cpp/#shzsincos_cscf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:86`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L86)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Sin/Cos Pairs"


---
# shz_sincos_secf

Source: https://sh4zam.com/api/trig/shz_sincos_secf/

> Returns the floating-point secant (1.0f / cosf(x)) from the given pre-computed sincos pair

```c
SHZ_INLINE float shz_sincos_secf(shz_sincos_t sincos) SHZ_NOEXCEPT;
```

Returns the floating-point secant (1.0f / cosf(x)) from the given pre-computed `sincos` pair.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `sincos` | `shz_sincos_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::sincos::secf`](https://sh4zam.com/api/cpp/sincos/#secf), [`shz::sincos_secf`](https://sh4zam.com/api/cpp/#shzsincos_secf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:83`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L83)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Sin/Cos Pairs"


---
# shz_sincos_t

Source: https://sh4zam.com/api/trig/shz_sincos_t/

```c
typedef struct shz_sincos {
    float sin;  //!< sinf() approximation for the angle
    float cos;  //!< cosf() approximation for the angle
} shz_sincos_t;
```

Pair representing the sine and cosine of a given angle.

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `sin` | `float` | sinf() approximation for the angle |
| `cos` | `float` | cosf() approximation for the angle |

## Details

The SH4 provides a single instruction, `FSCA`, for retrieving fast approximations of **both** the sine and cosine of a given angle. As such, when you need both values, it's most efficient to grab them both at once as a pair using this structure than it is to retrieve them separately.

## Availability

- **C++ equivalent:** [`shz::sincos`](https://sh4zam.com/api/cpp/sincos/)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_trig.h:57`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L57)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Types"

## See also

[`shz_sincosf`](https://sh4zam.com/api/trig/shz_sincosf/), [`shz_sincosf_deg`](https://sh4zam.com/api/trig/shz_sincosf_deg/)


---
# shz_sincos_tanf

Source: https://sh4zam.com/api/trig/shz_sincos_tanf/

> Returns tanf() from the given pre-computed sincos pair

```c
SHZ_INLINE float shz_sincos_tanf(shz_sincos_t sincos) SHZ_NOEXCEPT;
```

Returns tanf() from the given pre-computed `sincos` pair.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `sincos` | `shz_sincos_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::sincos::tanf`](https://sh4zam.com/api/cpp/sincos/#tanf), [`shz::sincos_tanf`](https://sh4zam.com/api/cpp/#shzsincos_tanf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:80`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L80)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Sin/Cos Pairs"


---
# shz_sincos

Source: https://sh4zam.com/api/trig/shz_sincos/

> Alternate C shz_sincos_t typedef for those who hate POSIX style

```c
typedef shz_sincos_t shz_sincos;
```

Alternate C [`shz_sincos_t`](https://sh4zam.com/api/trig/shz_sincos_t/) typedef for those who hate POSIX style.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_trig.h:63`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L63)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Types"


---
# shz_sincosf_deg

Source: https://sh4zam.com/api/trig/shz_sincosf_deg/

```c
SHZ_INLINE shz_sincos_t shz_sincosf_deg(float degrees) SHZ_NOEXCEPT;
```

Returns sinf/cosf() pairs for the given floating-point angle in degrees.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `degrees` | `float` |  |

## Returns

`shz_sincos_t`

## Naming and requirements

- `_deg`: Angle argument is in degrees. The default is radians. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::sincos::from_degrees`](https://sh4zam.com/api/cpp/sincos/#from_degrees), [`shz::sincosf_deg`](https://sh4zam.com/api/cpp/#shzsincosf_deg)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:77`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L77)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Sin/Cos Pairs"


---
# shz_sincosf

Source: https://sh4zam.com/api/trig/shz_sincosf/

```c
SHZ_INLINE shz_sincos_t shz_sincosf(float radians) SHZ_NOEXCEPT;
```

Returns sinf()/cosf() pairs for the given floating-point angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |

## Returns

`shz_sincos_t`

## Availability

- **C++ equivalent:** [`shz::sincosf`](https://sh4zam.com/api/cpp/#shzsincosf)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:74`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L74)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Sin/Cos Pairs"


---
# shz_sincosu16

Source: https://sh4zam.com/api/trig/shz_sincosu16/

```c
SHZ_INLINE shz_sincos_t shz_sincosu16(uint16_t radians16) SHZ_NOEXCEPT;
```

Returns sinf()/cosf() pairs for the given unsigned 16-bit angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians16` | `uint16_t` |  |

## Returns

`shz_sincos_t`

## Naming and requirements

- `u16`: Angle is a 16-bit fixed-point value: 0..65535 maps to 0..2π, the native `FSCA` input format. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::sincosu16`](https://sh4zam.com/api/cpp/#shzsincosu16)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:71`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L71)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Sin/Cos Pairs"


---
# shz_sinf_deg

Source: https://sh4zam.com/api/trig/shz_sinf_deg/

```c
SHZ_INLINE float shz_sinf_deg(float degrees) SHZ_NOEXCEPT;
```

One-off routine for returning only sinf() from an angle in degrees.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `degrees` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_deg`: Angle argument is in degrees. The default is radians. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::sinf_deg`](https://sh4zam.com/api/cpp/#shzsinf_deg)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:102`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L102)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_sinf

Source: https://sh4zam.com/api/trig/shz_sinf/

```c
SHZ_INLINE float shz_sinf(float radians) SHZ_NOEXCEPT;
```

One-off routine for returning only sinf() from an angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::sinf`](https://sh4zam.com/api/cpp/#shzsinf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:99`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L99)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_sinhf

Source: https://sh4zam.com/api/trig/shz_sinhf/

```c
SHZ_INLINE float shz_sinhf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic sine function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::sinhf`](https://sh4zam.com/api/cpp/#shzsinhf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:176`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L176)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Hyperbolic Functions"


---
# shz_tanf_deg

Source: https://sh4zam.com/api/trig/shz_tanf_deg/

```c
SHZ_INLINE float shz_tanf_deg(float degrees) SHZ_NOEXCEPT;
```

One-off routine for returning only tanf() from an angle in degrees.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `degrees` | `float` |  |

## Returns

`float`

## Naming and requirements

- `_deg`: Angle argument is in degrees. The default is radians. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::tanf_deg`](https://sh4zam.com/api/cpp/#shztanf_deg)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:114`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L114)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_tanf

Source: https://sh4zam.com/api/trig/shz_tanf/

```c
SHZ_INLINE float shz_tanf(float radians) SHZ_NOEXCEPT;
```

One-off routine for returning only tanf() from an angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::tanf`](https://sh4zam.com/api/cpp/#shztanf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:111`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L111)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Independent Functions"


---
# shz_tanhf

Source: https://sh4zam.com/api/trig/shz_tanhf/

```c
SHZ_INLINE float shz_tanhf(float x) SHZ_NOEXCEPT;
```

Fast hyperbolic tangent function.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::tanhf`](https://sh4zam.com/api/cpp/#shztanhf)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_trig.h:182`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_trig.h#L182)
- **Module:** [Trigonometry](https://sh4zam.com/api/trig/), section "Hyperbolic Functions"


---
# 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. |


---
# shz_vec_abs

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

```c
#define shz_vec_abs(vec)
```

C type-generic vector absolute value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:761`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L761)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_add

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

```c
#define shz_vec_add(vec1, vec2)
```

C type-generic vector addition.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Availability

- **C++ equivalent:** [`shz::operator+`](https://sh4zam.com/api/cpp/#shzoperator+)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:810`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L810)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_angle_between

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

```c
#define shz_vec_angle_between(vec1, vec2)
```

C type-generic angle between two vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Availability

- **C++ equivalent:** [`shz::vec4::angle_between`](https://sh4zam.com/api/cpp/vec4/#angle_between)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:969`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L969)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_angles

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

```c
#define shz_vec_angles(vec)
```

C type-generic angle-from-vector extraction.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** [`shz::vec4::angles`](https://sh4zam.com/api/cpp/vec4/#angles)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:963`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L963)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_ceil

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

```c
#define shz_vec_ceil(vec)
```

C type-generic component-wise ceil.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:989`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L989)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_clamp

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

```c
#define shz_vec_clamp(vec, min, max)
```

C type-generic vector minimum value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |
| `min` |  |  |
| `max` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:796`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L796)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_cross

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

```c
#define shz_vec_cross(vec1, vec2)
```

C type-generic vector cross-product.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:943`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L943)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_distance_sqr

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

```c
#define shz_vec_distance_sqr(vec1, vec2)
```

C type-generic vector squared distance.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:915`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L915)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_distance

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

```c
#define shz_vec_distance(vec1, vec2)
```

C type-generic vector distance.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:901`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L901)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_div

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

```c
#define shz_vec_div(vec1, vec2)
```

C type-generic vector division.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Availability

- **C++ equivalent:** [`shz::operator/`](https://sh4zam.com/api/cpp/#shzoperator/)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:831`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L831)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_dot

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

```c
#define shz_vec_dot(vec1, vec2)
```

C type-generic vector dot product.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:845`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L845)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_dot2

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

```c
#define shz_vec_dot2(l, r1, r2)
```

C type-generic vector chained double dot product.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `l` |  |  |
| `r1` |  |  |
| `r2` |  |  |

## Naming and requirements

- `dot2/dot3`: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined `FIPR` sequence. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:852`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L852)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_dot3

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

```c
#define shz_vec_dot3(l, r1, r2, r3)
```

C type-generic vector chained triple dot product.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `l` |  |  |
| `r1` |  |  |
| `r2` |  |  |
| `r3` |  |  |

## Naming and requirements

- `dot2/dot3`: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined `FIPR` sequence. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:859`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L859)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_equal

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

```c
#define shz_vec_equal(vec1, vec2)
```

C type-generic vector equals.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:803`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L803)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_floor

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

```c
#define shz_vec_floor(vec)
```

C type-generic component-wise floor.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:982`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L982)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_fract

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

```c
#define shz_vec_fract(vec)
```

C type-generic component-wise fract.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1003`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1003)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_inv_sqrtf

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

```c
#define shz_vec_inv_sqrtf(vec)
```

C type-generic inv_sqrtf.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1038`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1038)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_inv

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

```c
#define shz_vec_inv(vec)
```

C type-generic vector inversion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:775`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L775)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_lerp

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

```c
#define shz_vec_lerp(vec1, vec2, t)
```

C type-generic linear interpolation between two vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |
| `t` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:922`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L922)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_magnitude_inv

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

```c
#define shz_vec_magnitude_inv(vec)
```

C type-generic vector inverse magnitude.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:880`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L880)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_magnitude_sqr

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

```c
#define shz_vec_magnitude_sqr(vec)
```

C type-generic vector squared magnitude.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:866`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L866)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_magnitude

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

```c
#define shz_vec_magnitude(vec)
```

C type-generic vector magnitude.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:873`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L873)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_max

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

```c
#define shz_vec_max(vec)
```

C type-generic vector maximum value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:782`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L782)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_maxv

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

```c
#define shz_vec_maxv(a, b)
```

C type-generic pairwise maximum.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` |  |  |
| `b` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1031`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1031)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_min

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

```c
#define shz_vec_min(vec)
```

C type-generic vector minimum value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:789`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L789)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_minv

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

```c
#define shz_vec_minv(a, b)
```

C type-generic pairwise minimum.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` |  |  |
| `b` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1024`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1024)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_move

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

```c
#define shz_vec_move(vec, target, maxdist)
```

C type-generic vector move.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |
| `target` |  |  |
| `maxdist` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:908`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L908)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_mul

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

```c
#define shz_vec_mul(vec1, vec2)
```

C type-generic vector multiplication.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Availability

- **C++ equivalent:** [`shz::operator*`](https://sh4zam.com/api/cpp/#shzoperator*)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:824`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L824)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_neg

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

```c
#define shz_vec_neg(vec)
```

C type-generic vector negation.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:768`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L768)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_normalize_safe

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

```c
#define shz_vec_normalize_safe(vec)
```

C type-generic safe vector normalization.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:894`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L894)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_normalize

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

```c
#define shz_vec_normalize(vec)
```

C type-generic vector normalization.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:887`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L887)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_project_safe

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

```c
#define shz_vec_project_safe(vec1, vec2)
```

C type-generic safe vector projection.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:956`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L956)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_project

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

```c
#define shz_vec_project(vec1, vec2)
```

C type-generic vector projection.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:949`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L949)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_reflect

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

```c
#define shz_vec_reflect(incidence, normal)
```

C type-generic vector reflection.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `incidence` |  |  |
| `normal` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:929`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L929)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_refract

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

```c
#define shz_vec_refract(incidence, normal, eta)
```

C type-generic vector refraction.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `incidence` |  |  |
| `normal` |  |  |
| `eta` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:936`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L936)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_round

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

```c
#define shz_vec_round(vec)
```

C type-generic component-wise round.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:996`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L996)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_saturate

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

```c
#define shz_vec_saturate(vec)
```

C type-generic component-wise saturate.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1017`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1017)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_scale

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

```c
#define shz_vec_scale(vec, factor)
```

C type-generic vector scaling.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |
| `factor` |  |  |

## Availability

- **C++ equivalent:** [`shz::operator*`](https://sh4zam.com/api/cpp/#shzoperator*), [`shz::operator/`](https://sh4zam.com/api/cpp/#shzoperator/)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:838`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L838)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_sign

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

```c
#define shz_vec_sign(vec)
```

C type-generic component-wise sign.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1010`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1010)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_smoothstep_safe

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

```c
#define shz_vec_smoothstep_safe(vec, edge0, edge1)
```

C type-generic smoothstep_safe.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |
| `edge0` |  |  |
| `edge1` |  |  |

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1087`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1087)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_smoothstep

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

```c
#define shz_vec_smoothstep(vec, edge0, edge1)
```

C type-generic smoothstep.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |
| `edge0` |  |  |
| `edge1` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1073`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1073)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_smoothstepv_safe

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

```c
#define shz_vec_smoothstepv_safe(vec, edge0, edge1)
```

C type-generic component-wise smoothstep_safe.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |
| `edge0` |  |  |
| `edge1` |  |  |

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1080`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1080)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_smoothstepv

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

```c
#define shz_vec_smoothstepv(vec, edge0, edge1)
```

C type-generic component-wise smoothstep.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |
| `edge0` |  |  |
| `edge1` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1066`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1066)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_sqrtf

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

```c
#define shz_vec_sqrtf(vec)
```

C type-generic sqrtf.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1045`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1045)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_step

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

```c
#define shz_vec_step(vec, edge)
```

C type-generic step.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |
| `edge` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1059`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1059)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_stepv

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

```c
#define shz_vec_stepv(vec, edge)
```

C type-generic component-wise step.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |
| `edge` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:1052`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L1052)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_sub

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

```c
#define shz_vec_sub(vec1, vec2)
```

C type-generic vector subtraction.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` |  |  |
| `vec2` |  |  |

## Availability

- **C++ equivalent:** [`shz::operator-`](https://sh4zam.com/api/cpp/#shzoperator-)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:817`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L817)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec_swizzle

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

```c
#define shz_vec_swizzle(vec, ...)
```

C type-generic vector swizzling.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` |  |  |
| `...` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:975`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L975)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Type-Generic Routines"


---
# shz_vec2_abs

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_abs(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the absolute values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::abs`](https://sh4zam.com/api/cpp/vec2/#abs)
- **Type-generic form:** [`shz_vec_abs()`](https://sh4zam.com/api/vector/shz_vec_abs/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:138`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L138)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_add

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_add(shz_vec2_t vec1, shz_vec2_t vec2) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the sums of the given vectors' components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec2_t` |  |
| `vec2` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_add()`](https://sh4zam.com/api/vector/shz_vec_add/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:353`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L353)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec2_angle_between

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

```c
SHZ_INLINE float shz_vec2_angle_between(shz_vec2_t vec1, shz_vec2_t vec2) SHZ_NOEXCEPT;
```

Returns the angle formed between the given 2D vectors in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec2_t` |  |
| `vec2` | `shz_vec2_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec2::angle_between`](https://sh4zam.com/api/cpp/vec2/#angle_between)
- **Type-generic form:** [`shz_vec_angle_between()`](https://sh4zam.com/api/vector/shz_vec_angle_between/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:621`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L621)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"


---
# shz_vec2_angle

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

```c
SHZ_INLINE float shz_vec2_angle(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns the angle formed between the positive X axis and the given 2D vector, in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec2::angles`](https://sh4zam.com/api/cpp/vec2/#angles)
- **Type-generic form:** [`shz_vec_angles()`](https://sh4zam.com/api/vector/shz_vec_angles/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:627`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L627)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"


---
# shz_vec2_ceil

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_ceil(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the ceil of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::ceil`](https://sh4zam.com/api/cpp/vec2/#ceil)
- **Type-generic form:** [`shz_vec_ceil()`](https://sh4zam.com/api/vector/shz_vec_ceil/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:201`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L201)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_clamp

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

> Clamps the values of the given 2D vec between min and max, returning a new vector

```c
SHZ_INLINE shz_vec2_t shz_vec2_clamp(shz_vec2_t vec, float min, float max) SHZ_NOEXCEPT;
```

Clamps the values of the given 2D `vec` between `min` and `max`, returning a new vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `min` | `float` |  |
| `max` | `float` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::clamp`](https://sh4zam.com/api/cpp/vec2/#clamp)
- **Type-generic form:** [`shz_vec_clamp()`](https://sh4zam.com/api/vector/shz_vec_clamp/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:183`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L183)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_cross

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

```c
SHZ_INLINE float shz_vec2_cross(shz_vec2_t vec1, shz_vec2_t vec2) SHZ_NOEXCEPT;
```

Returns the cross product, as a scalar, between two 2D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec2_t` |  |
| `vec2` | `shz_vec2_t` |  |

## Returns

`float`

## Notes

- The definition of the cross-product is ambiguous in 2D space, but the geometric interpretation here is that the result is the magnitude of the orthogonal vector created from the given two along the Z-axis.

## Availability

- **C++ equivalent:** [`shz::vec2::cross`](https://sh4zam.com/api/cpp/vec2/#cross)
- **Type-generic form:** [`shz_vec_cross()`](https://sh4zam.com/api/vector/shz_vec_cross/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:553`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L553)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_deref

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

> Dereferences the given pointer to a sequence of 2 floats as a shz_vec2_t

```c
#define shz_vec2_deref(ptr) (*((SHZ_ALIASING shz_vec2_t*)(ptr)))
```

Dereferences the given pointer to a sequence of 2 floats as a [`shz_vec2_t`](https://sh4zam.com/api/vector/shz_vec2_t/).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ptr` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:725`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L725)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Adapters"


---
# shz_vec2_distance_sqr

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

```c
SHZ_INLINE float shz_vec2_distance_sqr(shz_vec2_t vec1, shz_vec2_t vec2) SHZ_NOEXCEPT;
```

Returns the squared-distance between the two given 2D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec2_t` |  |
| `vec2` | `shz_vec2_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec2::distance_sqr`](https://sh4zam.com/api/cpp/vec2/#distance_sqr)
- **Type-generic form:** [`shz_vec_distance_sqr()`](https://sh4zam.com/api/vector/shz_vec_distance_sqr/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:502`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L502)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_distance

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

```c
SHZ_INLINE float shz_vec2_distance(shz_vec2_t vec1, shz_vec2_t vec2) SHZ_NOEXCEPT;
```

Returns the distance between the two given 2D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec2_t` |  |
| `vec2` | `shz_vec2_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec2::distance`](https://sh4zam.com/api/cpp/vec2/#distance)
- **Type-generic form:** [`shz_vec_distance()`](https://sh4zam.com/api/vector/shz_vec_distance/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:493`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L493)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_div

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

> Returns a 2D vector whose component values are those of vec1 divided by vec2

```c
SHZ_INLINE shz_vec2_t shz_vec2_div(shz_vec2_t vec1, shz_vec2_t vec2) SHZ_NOEXCEPT;
```

Returns a 2D vector whose component values are those of `vec1` divided by `vec2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec2_t` |  |
| `vec2` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_div()`](https://sh4zam.com/api/vector/shz_vec_div/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:380`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L380)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec2_dot

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

```c
SHZ_INLINE float shz_vec2_dot(shz_vec2_t vec1, shz_vec2_t vec2) SHZ_NOEXCEPT;
```

Returns the dot product between the two given 2D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec2_t` |  |
| `vec2` | `shz_vec2_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_dot()`](https://sh4zam.com/api/vector/shz_vec_dot/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:466`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L466)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_dot2

Source: 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

```c
SHZ_INLINE shz_vec2_t shz_vec2_dot2(shz_vec2_t l, shz_vec2_t r1, shz_vec2_t r2) SHZ_NOEXCEPT;
```

Returns the two dot products taken between the 2D vector `l` and 2D vectors `r1` and `r2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `l` | `shz_vec2_t` |  |
| `r1` | `shz_vec2_t` |  |
| `r2` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Naming and requirements

- `dot2/dot3`: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined `FIPR` sequence. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_dot2()`](https://sh4zam.com/api/vector/shz_vec_dot2/)
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:469`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L469)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_dot3

Source: 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

```c
SHZ_INLINE shz_vec3_t shz_vec2_dot3(shz_vec2_t l, shz_vec2_t r1, shz_vec2_t r2, shz_vec2_t r3) SHZ_NOEXCEPT;
```

Returns the three dot products taken between the 2D vector `l` and 2D vectors `r1`, `r2`, and `r3`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `l` | `shz_vec2_t` |  |
| `r1` | `shz_vec2_t` |  |
| `r2` | `shz_vec2_t` |  |
| `r3` | `shz_vec2_t` |  |

## Returns

`shz_vec3_t`

## Naming and requirements

- `dot2/dot3`: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined `FIPR` sequence. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_dot3()`](https://sh4zam.com/api/vector/shz_vec_dot3/)
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:472`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L472)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_equal

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

```c
SHZ_INLINE bool shz_vec2_equal(shz_vec2_t a, shz_vec2_t b) SHZ_NOEXCEPT;
```

Returns true if the values of each element within the two 2D vectors are approximately equal based on relative or absolute tolerance.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec2_t` |  |
| `b` | `shz_vec2_t` |  |

## Returns

`bool`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_equal()`](https://sh4zam.com/api/vector/shz_vec_equal/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:264`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L264)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_fill

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

> Returns a 2D vector with the value of each component equal to v

```c
SHZ_INLINE shz_vec2_t shz_vec2_fill(float v) SHZ_NOEXCEPT;
```

Returns a 2D vector with the value of each component equal to `v`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `v` | `float` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:122`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L122)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Initializers"


---
# shz_vec2_floor

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_floor(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the floor of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::floor`](https://sh4zam.com/api/cpp/vec2/#floor)
- **Type-generic form:** [`shz_vec_floor()`](https://sh4zam.com/api/vector/shz_vec_floor/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:192`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L192)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_fract

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_fract(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the fractional parts of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::fract`](https://sh4zam.com/api/cpp/vec2/#fract)
- **Type-generic form:** [`shz_vec_fract()`](https://sh4zam.com/api/vector/shz_vec_fract/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:219`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L219)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_from_angle_deg

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_from_angle_deg(float degrees) SHZ_NOEXCEPT;
```

Returns the 2D unit vector representing a rotation from the positive X axis in degrees.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `degrees` | `float` |  |

## Returns

`shz_vec2_t`

## Naming and requirements

- `_deg`: Angle argument is in degrees. The default is radians. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::vec2::from_angle_deg`](https://sh4zam.com/api/cpp/vec2/#from_angle_deg)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:645`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L645)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"


---
# shz_vec2_from_angle

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_from_angle(float radians) SHZ_NOEXCEPT;
```

Returns the 2D unit vector representing a rotation from the positive X axis in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::from_angle`](https://sh4zam.com/api/cpp/vec2/#from_angle)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:639`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L639)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"


---
# shz_vec2_from_sincos

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_from_sincos(shz_sincos_t sincos) SHZ_NOEXCEPT;
```

Returns the 2D unit vector representing a rotation from the positive X axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `sincos` | `shz_sincos_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:633`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L633)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"


---
# shz_vec2_from

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

> Converts the given value or expression to the equivalent 2D SH4ZAM vector value

```c
#define shz_vec2_from(value) SHZ_CONVERT(shz_vec2_t, value)
```

Converts the given `value` or expression to the equivalent 2D SH4ZAM vector value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:734`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L734)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Adapters"


---
# shz_vec2_init

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

> Returns a 2D vector with the given x, and y coordinates

```c
SHZ_INLINE shz_vec2_t shz_vec2_init(float x, float y) SHZ_NOEXCEPT;
```

Returns a 2D vector with the given `x`, and `y` coordinates.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:113`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L113)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Initializers"


---
# shz_vec2_inv_sqrtf

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_inv_sqrtf(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the inverse square root of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::inv_sqrtf`](https://sh4zam.com/api/cpp/vec2/#inv_sqrtf)
- **Type-generic form:** [`shz_vec_inv_sqrtf()`](https://sh4zam.com/api/vector/shz_vec_inv_sqrtf/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:327`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L327)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_inv

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_inv(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns the 2D vector whose components have been inverted or reciprocated.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::inv`](https://sh4zam.com/api/cpp/vec2/#inv)
- **Type-generic form:** [`shz_vec_inv()`](https://sh4zam.com/api/vector/shz_vec_inv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:156`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L156)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_lerp

Source: 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

```c
SHZ_INLINE shz_vec2_t shz_vec2_lerp(shz_vec2_t a, shz_vec2_t b, float t) SHZ_NOEXCEPT;
```

Returns a 2D vector that is linearly interpolated from `a` to `b` by the given `0.0f-1.0f` factor, `t`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec2_t` |  |
| `b` | `shz_vec2_t` |  |
| `t` | `float` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::lerp`](https://sh4zam.com/api/cpp/vec2/#lerp)
- **Type-generic form:** [`shz_vec_lerp()`](https://sh4zam.com/api/vector/shz_vec_lerp/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:520`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L520)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_magnitude_inv

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

```c
SHZ_INLINE float shz_vec2_magnitude_inv(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns the inverse magnitude of the given 2D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec2::magnitude_inv`](https://sh4zam.com/api/cpp/vec2/#magnitude_inv)
- **Type-generic form:** [`shz_vec_magnitude_inv()`](https://sh4zam.com/api/vector/shz_vec_magnitude_inv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:423`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L423)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec2_magnitude_sqr

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

```c
SHZ_INLINE float shz_vec2_magnitude_sqr(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns the squared magnitude of the given 2D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec2::magnitude_sqr`](https://sh4zam.com/api/cpp/vec2/#magnitude_sqr)
- **Type-generic form:** [`shz_vec_magnitude_sqr()`](https://sh4zam.com/api/vector/shz_vec_magnitude_sqr/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:405`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L405)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec2_magnitude

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

```c
SHZ_INLINE float shz_vec2_magnitude(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns the magnitude of the given 2D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec2::magnitude`](https://sh4zam.com/api/cpp/vec2/#magnitude)
- **Type-generic form:** [`shz_vec_magnitude()`](https://sh4zam.com/api/vector/shz_vec_magnitude/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:414`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L414)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec2_max

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

```c
SHZ_INLINE float shz_vec2_max(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns the maximum value of both of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec2::max`](https://sh4zam.com/api/cpp/vec2/#max)
- **Type-generic form:** [`shz_vec_max()`](https://sh4zam.com/api/vector/shz_vec_max/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:165`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L165)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_maxv

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_maxv(shz_vec2_t a, shz_vec2_t b) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the pairwise maximums of the two given vectors' components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec2_t` |  |
| `b` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::maxv`](https://sh4zam.com/api/cpp/vec2/#maxv)
- **Type-generic form:** [`shz_vec_maxv()`](https://sh4zam.com/api/vector/shz_vec_maxv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:255`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L255)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_min

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

```c
SHZ_INLINE float shz_vec2_min(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Retuns the minimum value of both of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec2::min`](https://sh4zam.com/api/cpp/vec2/#min)
- **Type-generic form:** [`shz_vec_min()`](https://sh4zam.com/api/vector/shz_vec_min/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:174`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L174)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_minv

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_minv(shz_vec2_t a, shz_vec2_t b) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the pairwise minimums of the two given vectors' components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec2_t` |  |
| `b` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::minv`](https://sh4zam.com/api/cpp/vec2/#minv)
- **Type-generic form:** [`shz_vec_minv()`](https://sh4zam.com/api/vector/shz_vec_minv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:246`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L246)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_move

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

> Returns the given 2D vector, translated towards the target by the given max_distance

```c
SHZ_INLINE shz_vec2_t shz_vec2_move(shz_vec2_t vec, shz_vec2_t target, float max_distance) SHZ_NOEXCEPT;
```

Returns the given 2D vector, translated towards the `target` by the given `max_distance`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `target` | `shz_vec2_t` |  |
| `max_distance` | `float` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::move`](https://sh4zam.com/api/cpp/vec2/#move)
- **Type-generic form:** [`shz_vec_move()`](https://sh4zam.com/api/vector/shz_vec_move/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:511`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L511)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_mul

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

> Returns a 2D vector whose component values are those of vec1 times vec2

```c
SHZ_INLINE shz_vec2_t shz_vec2_mul(shz_vec2_t vec1, shz_vec2_t vec2) SHZ_NOEXCEPT;
```

Returns a 2D vector whose component values are those of `vec1` times `vec2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec2_t` |  |
| `vec2` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_mul()`](https://sh4zam.com/api/vector/shz_vec_mul/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:371`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L371)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec2_neg

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_neg(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the negative values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::neg`](https://sh4zam.com/api/cpp/vec2/#neg)
- **Type-generic form:** [`shz_vec_neg()`](https://sh4zam.com/api/vector/shz_vec_neg/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:147`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L147)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_normalize_safe

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_normalize_safe(shz_vec2_t vec) SHZ_NOEXCEPT;
```

SAFELY returns a normalized unit vector from the given 2D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Details

If the vector's magnitude is not `> 0.0f`, safely returns a zero vector.

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::vec2::direction_safe`](https://sh4zam.com/api/cpp/vec2/#direction_safe), [`shz::vec2::normalize_safe`](https://sh4zam.com/api/cpp/vec2/#normalize_safe), [`shz::vec2::normalized_safe`](https://sh4zam.com/api/cpp/vec2/#normalized_safe)
- **Type-generic form:** [`shz_vec_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec_normalize_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:444`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L444)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec2_normalize

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_normalize(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns a normalized unit vector from the given 2D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::direction`](https://sh4zam.com/api/cpp/vec2/#direction), [`shz::vec2::normalize`](https://sh4zam.com/api/cpp/vec2/#normalize), [`shz::vec2::normalized`](https://sh4zam.com/api/cpp/vec2/#normalized)
- **Type-generic form:** [`shz_vec_normalize()`](https://sh4zam.com/api/vector/shz_vec_normalize/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:432`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L432)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec2_project_safe

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_project_safe(shz_vec2_t vec, shz_vec2_t onto) SHZ_NOEXCEPT;
```

Returns the resulting vector from projecting the given 2D vector along the given (unit) axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `onto` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Notes

- This routine should safely return the zero vector when `vec` has a magnitude of 0.0f.

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::vec2::project_safe`](https://sh4zam.com/api/cpp/vec2/#project_safe)
- **Type-generic form:** [`shz_vec_project_safe()`](https://sh4zam.com/api/vector/shz_vec_project_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:572`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L572)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_project

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_project(shz_vec2_t vec, shz_vec2_t onto) SHZ_NOEXCEPT;
```

Returns the resulting vector from projecting the given 2D vector along the given (unit) axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `onto` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::project`](https://sh4zam.com/api/cpp/vec2/#project)
- **Type-generic form:** [`shz_vec_project()`](https://sh4zam.com/api/vector/shz_vec_project/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:559`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L559)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_reflect

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

> Reflects the given 2D incidence vector against a surface with the given normal, returning the result

```c
SHZ_INLINE shz_vec2_t shz_vec2_reflect(shz_vec2_t incidence, shz_vec2_t normal) SHZ_NOEXCEPT;
```

Reflects the given 2D `incidence` vector against a surface with the given `normal`, returning the result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `incidence` | `shz_vec2_t` |  |
| `normal` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::reflect`](https://sh4zam.com/api/cpp/vec2/#reflect)
- **Type-generic form:** [`shz_vec_reflect()`](https://sh4zam.com/api/vector/shz_vec_reflect/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:529`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L529)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_refract

Source: 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

```c
SHZ_INLINE shz_vec2_t shz_vec2_refract(shz_vec2_t incidence, shz_vec2_t normal, float eta) SHZ_NOEXCEPT;
```

Refracts the given 2D `incidence` vector against a surface with the given `normal` using the given refraction index ratio, `eta`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `incidence` | `shz_vec2_t` |  |
| `normal` | `shz_vec2_t` |  |
| `eta` | `float` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::refract`](https://sh4zam.com/api/cpp/vec2/#refract)
- **Type-generic form:** [`shz_vec_refract()`](https://sh4zam.com/api/vector/shz_vec_refract/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:538`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L538)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec2_rotate

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_rotate(shz_vec2_t vec, float radians) SHZ_NOEXCEPT;
```

Rotates the given 2D vector about the Z axis by the given angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `radians` | `float` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::rotate`](https://sh4zam.com/api/cpp/vec2/#rotate)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:651`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L651)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"


---
# shz_vec2_round

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_round(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the rounded values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::round`](https://sh4zam.com/api/cpp/vec2/#round)
- **Type-generic form:** [`shz_vec_round()`](https://sh4zam.com/api/vector/shz_vec_round/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:210`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L210)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_saturate

Source: 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

```c
SHZ_INLINE shz_vec2_t shz_vec2_saturate(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are saturated (clamped to \[0, 1\]) values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::saturate`](https://sh4zam.com/api/cpp/vec2/#saturate)
- **Type-generic form:** [`shz_vec_saturate()`](https://sh4zam.com/api/vector/shz_vec_saturate/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:237`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L237)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_scale

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_scale(shz_vec2_t vec, float factor) SHZ_NOEXCEPT;
```

Returns a 2D vector whose component values are those of the given vector multiplied by a factor.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `factor` | `float` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_scale()`](https://sh4zam.com/api/vector/shz_vec_scale/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:389`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L389)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec2_sign

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_sign(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the signs (-1, 0, or 1) of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::sign`](https://sh4zam.com/api/cpp/vec2/#sign)
- **Type-generic form:** [`shz_vec_sign()`](https://sh4zam.com/api/vector/shz_vec_sign/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:228`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L228)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_smoothstep_safe

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_smoothstep_safe(shz_vec2_t vec, float edge0, float edge1) SHZ_NOEXCEPT;
```

For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. Accepts inverse edges.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `edge0` | `float` |  |
| `edge1` | `float` |  |

## Returns

`shz_vec2_t`

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::vec2::smoothstep_safe`](https://sh4zam.com/api/cpp/vec2/#smoothstep_safe)
- **Type-generic form:** [`shz_vec_smoothstep_safe()`](https://sh4zam.com/api/vector/shz_vec_smoothstep_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:309`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L309)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_smoothstep

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_smoothstep(shz_vec2_t vec, float edge0, float edge1) SHZ_NOEXCEPT;
```

For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `edge0` | `float` |  |
| `edge1` | `float` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::smoothstep`](https://sh4zam.com/api/cpp/vec2/#smoothstep)
- **Type-generic form:** [`shz_vec_smoothstep()`](https://sh4zam.com/api/vector/shz_vec_smoothstep/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:291`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L291)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_smoothstepv_safe

Source: 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

```c
SHZ_INLINE shz_vec2_t shz_vec2_smoothstepv_safe(shz_vec2_t vec, shz_vec2_t edge0, shz_vec2_t edge1) SHZ_NOEXCEPT;
```

For each component: returns 0.0f at/below edge0\[i\], 1.0f at/above edge1\[i\], smoothly varying in-between. Accepts inverse edges.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `edge0` | `shz_vec2_t` |  |
| `edge1` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_smoothstepv_safe()`](https://sh4zam.com/api/vector/shz_vec_smoothstepv_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:318`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L318)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_smoothstepv

Source: 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

```c
SHZ_INLINE shz_vec2_t shz_vec2_smoothstepv(shz_vec2_t vec, shz_vec2_t edge0, shz_vec2_t edge1) SHZ_NOEXCEPT;
```

For each component: returns 0.0f at/below edge0\[i\], 1.0f at/above edge1\[i\], smoothly varying in-between.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `edge0` | `shz_vec2_t` |  |
| `edge1` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_smoothstepv()`](https://sh4zam.com/api/vector/shz_vec_smoothstepv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:300`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L300)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_sqrtf

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_sqrtf(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are the square root of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::sqrtf`](https://sh4zam.com/api/cpp/vec2/#sqrtf)
- **Type-generic form:** [`shz_vec_sqrtf()`](https://sh4zam.com/api/vector/shz_vec_sqrtf/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:336`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L336)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_step

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

> For each component: returns 0.0f if vec[i] < edge, otherwise 1.0f

```c
SHZ_INLINE shz_vec2_t shz_vec2_step(shz_vec2_t vec, float edge) SHZ_NOEXCEPT;
```

For each component: returns 0.0f if vec\[i\] \< edge, otherwise 1.0f.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `edge` | `float` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::step`](https://sh4zam.com/api/cpp/vec2/#step)
- **Type-generic form:** [`shz_vec_step()`](https://sh4zam.com/api/vector/shz_vec_step/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:282`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L282)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_stepv

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

> For each component: returns 0.0f if vec[i] < edge[i], otherwise 1.0f

```c
SHZ_INLINE shz_vec2_t shz_vec2_stepv( shz_vec2_t vec, shz_vec2_t edge) SHZ_NOEXCEPT;
```

For each component: returns 0.0f if vec\[i\] \< edge\[i\], otherwise 1.0f.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `edge` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_stepv()`](https://sh4zam.com/api/vector/shz_vec_stepv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:273`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L273)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec2_sub

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

> Returns a 2D vector whose components are equal to the values of vec1 minus vec2

```c
SHZ_INLINE shz_vec2_t shz_vec2_sub(shz_vec2_t vec1, shz_vec2_t vec2) SHZ_NOEXCEPT;
```

Returns a 2D vector whose components are equal to the values of `vec1` minus `vec2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec2_t` |  |
| `vec2` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_sub()`](https://sh4zam.com/api/vector/shz_vec_sub/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:362`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L362)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec2_swizzle

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

```c
SHZ_INLINE shz_vec2_t shz_vec2_swizzle(shz_vec2_t vec, unsigned x_idx, unsigned y_idx) SHZ_NOEXCEPT;
```

Returns a 2D vector whose elements are equal to the source vector's values at the given indices.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `x_idx` | `unsigned` |  |
| `y_idx` | `unsigned` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** [`shz::vec2::swizzle`](https://sh4zam.com/api/cpp/vec2/#swizzle)
- **Type-generic form:** [`shz_vec_swizzle()`](https://sh4zam.com/api/vector/shz_vec_swizzle/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:707`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L707)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Swizzling"


---
# shz_vec2_t

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

```c
typedef struct shz_vec2 {
    union {
        float e[2];  //!< <X, Y> coordinates as an array
        struct {
            float x; //!< X coordinate
            float y; //!< Y coordinate
        };
    };
} shz_vec2_t;
```

2D Vector type

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `e` | `float[2]` | \<X, Y> coordinates as an array |
| `x` | `float` | X coordinate. |
| `y` | `float` | Y coordinate. |

## Details

Structure for holding coordinates of a 2-dimensional vector.

## Availability

- **C++ equivalent:** [`shz::vec2`](https://sh4zam.com/api/cpp/vec2/)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:38`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L38)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Types"

## See also

[`shz_vec3_t`](https://sh4zam.com/api/vector/shz_vec3_t/), [`shz_vec4_t`](https://sh4zam.com/api/vector/shz_vec4_t/)


---
# shz_vec2_to

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

> Converts the given 2D vector into a value of the given type

```c
#define shz_vec2_to(type, vector) SHZ_CONVERT(type, vector)
```

Converts the given 2D `vector` into a value of the given `type`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `type` |  |  |
| `vector` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:743`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L743)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Adapters"


---
# shz_vec2_vec3

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

> Extends a 2D vector to 3D, using z as the value of the Z component

```c
SHZ_INLINE shz_vec3_t shz_vec2_vec3(shz_vec2_t vec, float z) SHZ_NOEXCEPT;
```

Extends a 2D vector to 3D, using `z` as the value of the Z component.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `z` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:691`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L691)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Extending"


---
# shz_vec2_vec4

Source: 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

```c
SHZ_INLINE shz_vec4_t shz_vec2_vec4(shz_vec2_t vec, float z, float w) SHZ_NOEXCEPT;
```

Extends a 2D vector to 4D, using `z` and `w` as the values of the Z and W components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |
| `z` | `float` |  |
| `w` | `float` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:694`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L694)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Extending"


---
# shz_vec2

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

> Alternate typedef for the shz_vec2 struct for those who hate POSIX-style

```c
typedef shz_vec2_t shz_vec2;
```

Alternate typedef for the [`shz_vec2`](https://sh4zam.com/api/vector/shz_vec2/) struct for those who hate POSIX-style.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:49`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L49)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Types"


---
# shz_vec3_abs

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_abs(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the absolute values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::abs`](https://sh4zam.com/api/cpp/vec3/#abs)
- **Type-generic form:** [`shz_vec_abs()`](https://sh4zam.com/api/vector/shz_vec_abs/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:141`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L141)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_add

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_add(shz_vec3_t vec1, shz_vec3_t vec2) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the sums of the given vectors' components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec3_t` |  |
| `vec2` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_add()`](https://sh4zam.com/api/vector/shz_vec_add/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:356`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L356)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec3_angle_between

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

```c
SHZ_INLINE float shz_vec3_angle_between(shz_vec3_t vec1, shz_vec3_t vec2) SHZ_NOEXCEPT;
```

Returns the angle formed between the given 3D vectors in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec3_t` |  |
| `vec2` | `shz_vec3_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec3::angle_between`](https://sh4zam.com/api/cpp/vec3/#angle_between)
- **Type-generic form:** [`shz_vec_angle_between()`](https://sh4zam.com/api/vector/shz_vec_angle_between/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:624`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L624)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"


---
# shz_vec3_angles

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_angles(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns the angles formed between the positive X axis and the given 3D vector, in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::angles`](https://sh4zam.com/api/cpp/vec3/#angles)
- **Type-generic form:** [`shz_vec_angles()`](https://sh4zam.com/api/vector/shz_vec_angles/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:630`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L630)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"


---
# shz_vec3_barycenter

Source: 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

```c
SHZ_INLINE shz_vec3_t shz_vec3_barycenter(shz_vec3_t p, shz_vec3_t a, shz_vec3_t b, shz_vec3_t c) SHZ_NOEXCEPT;
```

Computes barycentric coordinates `<u, v, w>` for point p, within the plane of the triangle with vertices `a`, `b`, and `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `p` | `shz_vec3_t` |  |
| `a` | `shz_vec3_t` |  |
| `b` | `shz_vec3_t` |  |
| `c` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::barycenter`](https://sh4zam.com/api/cpp/vec3/#barycenter)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:605`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L605)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Miscellaneous"


---
# shz_vec3_ceil

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_ceil(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the ceil of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::ceil`](https://sh4zam.com/api/cpp/vec3/#ceil)
- **Type-generic form:** [`shz_vec_ceil()`](https://sh4zam.com/api/vector/shz_vec_ceil/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:204`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L204)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_clamp

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

> Clamps the values of the given 3D vec between min and max, returning a new vector

```c
SHZ_INLINE shz_vec3_t shz_vec3_clamp(shz_vec3_t vec, float min, float max) SHZ_NOEXCEPT;
```

Clamps the values of the given 3D `vec` between `min` and `max`, returning a new vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `min` | `float` |  |
| `max` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::clamp`](https://sh4zam.com/api/cpp/vec3/#clamp)
- **Type-generic form:** [`shz_vec_clamp()`](https://sh4zam.com/api/vector/shz_vec_clamp/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:186`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L186)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_cross

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_cross(shz_vec3_t vec1, shz_vec3_t vec2) SHZ_NOEXCEPT;
```

Returns the vector produced by taking the cross-product of the two given 3D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec3_t` |  |
| `vec2` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::cross`](https://sh4zam.com/api/cpp/vec3/#cross)
- **Type-generic form:** [`shz_vec_cross()`](https://sh4zam.com/api/vector/shz_vec_cross/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:556`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L556)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_cubic_hermite

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_cubic_hermite(shz_vec3_t vec, shz_vec3_t tangent1, shz_vec3_t vec2, shz_vec3_t tangent2, float amounht) SHZ_NOEXCEPT;
```

Calculates the cubic hermite interpolation between two vectors and their tangents.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `tangent1` | `shz_vec3_t` |  |
| `vec2` | `shz_vec3_t` |  |
| `tangent2` | `shz_vec3_t` |  |
| `amounht` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::cubic_hermite`](https://sh4zam.com/api/cpp/vec3/#cubic_hermite)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:611`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L611)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Miscellaneous"


---
# shz_vec3_deref

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

> Dereferences the given pointer to a sequence of 3 floats as a shz_vec3_t

```c
#define shz_vec3_deref(ptr) (*((SHZ_ALIASING shz_vec3_t*)(ptr)))
```

Dereferences the given pointer to a sequence of 3 floats as a [`shz_vec3_t`](https://sh4zam.com/api/vector/shz_vec3_t/).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ptr` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:728`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L728)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Adapters"


---
# shz_vec3_distance_sqr

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

```c
SHZ_INLINE float shz_vec3_distance_sqr(shz_vec3_t vec1, shz_vec3_t vec2) SHZ_NOEXCEPT;
```

Returns the squared-distance between the two given 3D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec3_t` |  |
| `vec2` | `shz_vec3_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec3::distance_sqr`](https://sh4zam.com/api/cpp/vec3/#distance_sqr)
- **Type-generic form:** [`shz_vec_distance_sqr()`](https://sh4zam.com/api/vector/shz_vec_distance_sqr/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:505`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L505)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_distance

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

```c
SHZ_INLINE float shz_vec3_distance(shz_vec3_t vec1, shz_vec3_t vec2) SHZ_NOEXCEPT;
```

Returns the distance between the two given 3D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec3_t` |  |
| `vec2` | `shz_vec3_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec3::distance`](https://sh4zam.com/api/cpp/vec3/#distance)
- **Type-generic form:** [`shz_vec_distance()`](https://sh4zam.com/api/vector/shz_vec_distance/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:496`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L496)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_div

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

> Returns a 3D vector whose component values are those of vec1 divided by vec2

```c
SHZ_INLINE shz_vec3_t shz_vec3_div(shz_vec3_t vec1, shz_vec3_t vec2) SHZ_NOEXCEPT;
```

Returns a 3D vector whose component values are those of `vec1` divided by `vec2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec3_t` |  |
| `vec2` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_div()`](https://sh4zam.com/api/vector/shz_vec_div/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:383`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L383)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec3_dot

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

```c
SHZ_INLINE float shz_vec3_dot(shz_vec3_t vec1, shz_vec3_t vec2) SHZ_NOEXCEPT;
```

Returns the dot product between the two given 3D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec3_t` |  |
| `vec2` | `shz_vec3_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_dot()`](https://sh4zam.com/api/vector/shz_vec_dot/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:475`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L475)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_dot2

Source: 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

```c
SHZ_INLINE shz_vec2_t shz_vec3_dot2(shz_vec3_t l, shz_vec3_t r1, shz_vec3_t r2) SHZ_NOEXCEPT;
```

Returns the two dot products taken between the 3D vector `l` and 3D vectors `r1` and `r2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `l` | `shz_vec3_t` |  |
| `r1` | `shz_vec3_t` |  |
| `r2` | `shz_vec3_t` |  |

## Returns

`shz_vec2_t`

## Naming and requirements

- `dot2/dot3`: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined `FIPR` sequence. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_dot2()`](https://sh4zam.com/api/vector/shz_vec_dot2/)
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:478`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L478)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_dot3

Source: 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

```c
SHZ_INLINE shz_vec3_t shz_vec3_dot3(shz_vec3_t l, shz_vec3_t r1, shz_vec3_t r2, shz_vec3_t r3) SHZ_NOEXCEPT;
```

Returns the three dot products taken between the 3D vector `l` and 3D vectors `r1`, `r2`, and `r3`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `l` | `shz_vec3_t` |  |
| `r1` | `shz_vec3_t` |  |
| `r2` | `shz_vec3_t` |  |
| `r3` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Naming and requirements

- `dot2/dot3`: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined `FIPR` sequence. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_dot3()`](https://sh4zam.com/api/vector/shz_vec_dot3/)
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:481`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L481)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_equal

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

```c
SHZ_INLINE bool shz_vec3_equal(shz_vec3_t a, shz_vec3_t b) SHZ_NOEXCEPT;
```

Returns true if the values of each element within the two 3D vectors are approximately equal based on relative or absolute tolerance.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec3_t` |  |
| `b` | `shz_vec3_t` |  |

## Returns

`bool`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_equal()`](https://sh4zam.com/api/vector/shz_vec_equal/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:267`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L267)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_fill

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

> Returns a 3D vector with the value of each compoonent equal to v

```c
SHZ_INLINE shz_vec3_t shz_vec3_fill(float v) SHZ_NOEXCEPT;
```

Returns a 3D vector with the value of each compoonent equal to `v`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `v` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:125`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L125)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Initializers"


---
# shz_vec3_floor

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_floor(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the floor of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::floor`](https://sh4zam.com/api/cpp/vec3/#floor)
- **Type-generic form:** [`shz_vec_floor()`](https://sh4zam.com/api/vector/shz_vec_floor/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:195`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L195)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_fract

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_fract(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the fractional parts of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::fract`](https://sh4zam.com/api/cpp/vec3/#fract)
- **Type-generic form:** [`shz_vec_fract()`](https://sh4zam.com/api/vector/shz_vec_fract/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:222`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L222)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_from_angles_deg

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_from_angles_deg(float azimuth, float elevation) SHZ_NOEXCEPT;
```

Returns the 3D unit vector representing the given rotation angles relative to the positive X axis in degrees.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `azimuth` | `float` |  |
| `elevation` | `float` |  |

## Returns

`shz_vec3_t`

## Naming and requirements

- `_deg`: Angle argument is in degrees. The default is radians. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::vec3::from_angles_deg`](https://sh4zam.com/api/cpp/vec3/#from_angles_deg)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:648`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L648)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"


---
# shz_vec3_from_angles

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_from_angles(float azimuth, float elevation) SHZ_NOEXCEPT;
```

Returns the 3D unit vector representing the given rotation angles relative to the positive X axis in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `azimuth` | `float` |  |
| `elevation` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::from_angles`](https://sh4zam.com/api/cpp/vec3/#from_angles)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:642`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L642)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"


---
# shz_vec3_from_sincos

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_from_sincos(shz_sincos_t azimuth, shz_sincos_t elevation) SHZ_NOEXCEPT;
```

Returns the 3D unit vector representing the given rotation angles relative to the positive X axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `azimuth` | `shz_sincos_t` |  |
| `elevation` | `shz_sincos_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:636`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L636)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"


---
# shz_vec3_from

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

> Converts the given value or expression to the equivalent 3D SH4ZAM vector value

```c
#define shz_vec3_from(value) SHZ_CONVERT(shz_vec3_t, value)
```

Converts the given `value` or expression to the equivalent 3D SH4ZAM vector value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:737`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L737)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Adapters"


---
# shz_vec3_init

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

> Returns a 3D vector with the given x, y, and z coordinates

```c
SHZ_INLINE shz_vec3_t shz_vec3_init(float x, float y, float z) SHZ_NOEXCEPT;
```

Returns a 3D vector with the given `x`, `y`, and `z` coordinates.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:116`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L116)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Initializers"


---
# shz_vec3_inv_sqrtf

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_inv_sqrtf(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the inverse square root of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::inv_sqrtf`](https://sh4zam.com/api/cpp/vec3/#inv_sqrtf)
- **Type-generic form:** [`shz_vec_inv_sqrtf()`](https://sh4zam.com/api/vector/shz_vec_inv_sqrtf/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:330`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L330)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_inv

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_inv(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns the 3D vector whose components have been inverted or reciprocated.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::inv`](https://sh4zam.com/api/cpp/vec3/#inv)
- **Type-generic form:** [`shz_vec_inv()`](https://sh4zam.com/api/vector/shz_vec_inv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:159`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L159)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_lerp

Source: 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

```c
SHZ_INLINE shz_vec3_t shz_vec3_lerp(shz_vec3_t a, shz_vec3_t b, float t) SHZ_NOEXCEPT;
```

Returns a 3D vector that is linearly interpolated from `a` to `b` by the given `0.0f-1.0f` factor, `t`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec3_t` |  |
| `b` | `shz_vec3_t` |  |
| `t` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::lerp`](https://sh4zam.com/api/cpp/vec3/#lerp)
- **Type-generic form:** [`shz_vec_lerp()`](https://sh4zam.com/api/vector/shz_vec_lerp/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:523`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L523)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_magnitude_inv

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

```c
SHZ_INLINE float shz_vec3_magnitude_inv(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns the inverse magnitude of the given 3D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec3::magnitude_inv`](https://sh4zam.com/api/cpp/vec3/#magnitude_inv)
- **Type-generic form:** [`shz_vec_magnitude_inv()`](https://sh4zam.com/api/vector/shz_vec_magnitude_inv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:426`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L426)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec3_magnitude_sqr

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

```c
SHZ_INLINE float shz_vec3_magnitude_sqr(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns the squared magnitude of the given 3D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec3::magnitude_sqr`](https://sh4zam.com/api/cpp/vec3/#magnitude_sqr)
- **Type-generic form:** [`shz_vec_magnitude_sqr()`](https://sh4zam.com/api/vector/shz_vec_magnitude_sqr/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:411`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L411)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec3_magnitude

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

```c
SHZ_INLINE float shz_vec3_magnitude(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns the magnitude of the given 3D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec3::magnitude`](https://sh4zam.com/api/cpp/vec3/#magnitude)
- **Type-generic form:** [`shz_vec_magnitude()`](https://sh4zam.com/api/vector/shz_vec_magnitude/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:417`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L417)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec3_max

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

```c
SHZ_INLINE float shz_vec3_max(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns the maximum value of the given vector's 3 components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec3::max`](https://sh4zam.com/api/cpp/vec3/#max)
- **Type-generic form:** [`shz_vec_max()`](https://sh4zam.com/api/vector/shz_vec_max/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:168`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L168)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_maxv

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_maxv(shz_vec3_t a, shz_vec3_t b) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the pairwise maximums of the two given vectors' components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec3_t` |  |
| `b` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::maxv`](https://sh4zam.com/api/cpp/vec3/#maxv)
- **Type-generic form:** [`shz_vec_maxv()`](https://sh4zam.com/api/vector/shz_vec_maxv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:258`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L258)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_min

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

```c
SHZ_INLINE float shz_vec3_min(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns the minimum value of the given vector's 3 components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec3::min`](https://sh4zam.com/api/cpp/vec3/#min)
- **Type-generic form:** [`shz_vec_min()`](https://sh4zam.com/api/vector/shz_vec_min/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:177`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L177)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_minv

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_minv(shz_vec3_t a, shz_vec3_t b) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the pairwise minimums of the two given vectors' components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec3_t` |  |
| `b` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::minv`](https://sh4zam.com/api/cpp/vec3/#minv)
- **Type-generic form:** [`shz_vec_minv()`](https://sh4zam.com/api/vector/shz_vec_minv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:249`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L249)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_move

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

> Returns the given 3D vector, translated towards the target by the given max_distance

```c
SHZ_INLINE shz_vec3_t shz_vec3_move(shz_vec3_t vec, shz_vec3_t target, float max_distance) SHZ_NOEXCEPT;
```

Returns the given 3D vector, translated towards the `target` by the given `max_distance`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `target` | `shz_vec3_t` |  |
| `max_distance` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::move`](https://sh4zam.com/api/cpp/vec3/#move)
- **Type-generic form:** [`shz_vec_move()`](https://sh4zam.com/api/vector/shz_vec_move/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:514`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L514)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_mul

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

> Returns a 3D vector whose component values are those of vec1 times vec2

```c
SHZ_INLINE shz_vec3_t shz_vec3_mul(shz_vec3_t vec1, shz_vec3_t vec2) SHZ_NOEXCEPT;
```

Returns a 3D vector whose component values are those of `vec1` times `vec2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec3_t` |  |
| `vec2` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_mul()`](https://sh4zam.com/api/vector/shz_vec_mul/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:374`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L374)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec3_neg

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_neg(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the negative values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::neg`](https://sh4zam.com/api/cpp/vec3/#neg)
- **Type-generic form:** [`shz_vec_neg()`](https://sh4zam.com/api/vector/shz_vec_neg/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:150`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L150)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_normalize_safe

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_normalize_safe(shz_vec3_t vec) SHZ_NOEXCEPT;
```

SAFELY returns a normalized unit vector from the given 3D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Details

If the vector's magnitude is not `> 0.0f`, safely returns a zero vector.

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::vec3::direction_safe`](https://sh4zam.com/api/cpp/vec3/#direction_safe), [`shz::vec3::normalize_safe`](https://sh4zam.com/api/cpp/vec3/#normalize_safe), [`shz::vec3::normalized_safe`](https://sh4zam.com/api/cpp/vec3/#normalized_safe)
- **Type-generic form:** [`shz_vec_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec_normalize_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:450`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L450)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec3_normalize

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_normalize(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a normalized unit vector from the given 3D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::direction`](https://sh4zam.com/api/cpp/vec3/#direction), [`shz::vec3::normalize`](https://sh4zam.com/api/cpp/vec3/#normalize), [`shz::vec3::normalized`](https://sh4zam.com/api/cpp/vec3/#normalized)
- **Type-generic form:** [`shz_vec_normalize()`](https://sh4zam.com/api/vector/shz_vec_normalize/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:435`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L435)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec3_orthonormalize

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

```c
SHZ_INLINE void shz_vec3_orthonormalize(shz_vec3_t in1, shz_vec3_t in2, shz_vec3_t* out1, shz_vec3_t* out2) SHZ_NOEXCEPT;
```

Returns 2 3D vectors which are normalized and orthogonal to the two input vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `in1` | `shz_vec3_t` |  |
| `in2` | `shz_vec3_t` |  |
| `out1` | `shz_vec3_t *` |  |
| `out2` | `shz_vec3_t *` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::vec3::orthonormalize`](https://sh4zam.com/api/cpp/vec3/#orthonormalize)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:608`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L608)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Miscellaneous"


---
# shz_vec3_perp

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_perp(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a vector which is perpendicular to the given vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::perp`](https://sh4zam.com/api/cpp/vec3/#perp)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:602`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L602)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Miscellaneous"


---
# shz_vec3_project_safe

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_project_safe(shz_vec3_t vec, shz_vec3_t onto) SHZ_NOEXCEPT;
```

Returns the resulting vector from projecting the given 3D vector along the given (unit) axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `onto` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Notes

- This routine should safely return the zero vector when `vec` has a magnitude of 0.0f.

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::vec3::project_safe`](https://sh4zam.com/api/cpp/vec3/#project_safe)
- **Type-generic form:** [`shz_vec_project_safe()`](https://sh4zam.com/api/vector/shz_vec_project_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:579`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L579)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_project

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_project(shz_vec3_t vec, shz_vec3_t onto) SHZ_NOEXCEPT;
```

Returns the resulting vector from projecting the given 3D vector along the given (unit) axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `onto` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::project`](https://sh4zam.com/api/cpp/vec3/#project)
- **Type-generic form:** [`shz_vec_project()`](https://sh4zam.com/api/vector/shz_vec_project/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:562`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L562)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_reflect

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

> Reflects the given 3D incidence vector against a surface with the given normal, returning the result

```c
SHZ_INLINE shz_vec3_t shz_vec3_reflect(shz_vec3_t incidence, shz_vec3_t normal) SHZ_NOEXCEPT;
```

Reflects the given 3D `incidence` vector against a surface with the given `normal`, returning the result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `incidence` | `shz_vec3_t` |  |
| `normal` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::reflect`](https://sh4zam.com/api/cpp/vec3/#reflect)
- **Type-generic form:** [`shz_vec_reflect()`](https://sh4zam.com/api/vector/shz_vec_reflect/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:532`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L532)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_refract

Source: 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

```c
SHZ_INLINE shz_vec3_t shz_vec3_refract(shz_vec3_t incidence, shz_vec3_t normal, float eta) SHZ_NOEXCEPT;
```

Refracts the given 3D `incidence` vector against a surface with the given `normal` using the given refraction index ratio, `eta`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `incidence` | `shz_vec3_t` |  |
| `normal` | `shz_vec3_t` |  |
| `eta` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::refract`](https://sh4zam.com/api/cpp/vec3/#refract)
- **Type-generic form:** [`shz_vec_refract()`](https://sh4zam.com/api/vector/shz_vec_refract/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:541`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L541)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_reject

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

> Returns the rejection of the given vector, vec, onto another vector, onto

```c
SHZ_INLINE shz_vec3_t shz_vec3_reject(shz_vec3_t vec, shz_vec3_t onto) SHZ_NOEXCEPT;
```

Returns the rejection of the given vector, `vec`, onto another vector, `onto`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `onto` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::reject`](https://sh4zam.com/api/cpp/vec3/#reject)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:589`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L589)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec3_rotate_x

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_rotate_x(shz_vec3_t vec, float radians) SHZ_NOEXCEPT;
```

Rotates the given 3D vector about the X axis by the given angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `radians` | `float` |  |

## Returns

`shz_vec3_t`

## Warnings

- This routine should only be used for one-off rotations of a single vector. To rotate multiple vectors in a batch, use the XMTRX API.

## Availability

- **C++ equivalent:** [`shz::vec3::rotate_x`](https://sh4zam.com/api/cpp/vec3/#rotate_x)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:661`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L661)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"

## See also

[`shz_xmtrx_apply_rotation_x`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_x/)


---
# shz_vec3_rotate_y

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_rotate_y(shz_vec3_t vec, float radians) SHZ_NOEXCEPT;
```

Rotates the given 3D vector about the Y axis by the given angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `radians` | `float` |  |

## Returns

`shz_vec3_t`

## Warnings

- This routine should only be used for one-off rotations of a single vector. To rotate multiple vectors in a batch, use the XMTRX API.

## Availability

- **C++ equivalent:** [`shz::vec3::rotate_y`](https://sh4zam.com/api/cpp/vec3/#rotate_y)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:671`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L671)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"

## See also

[`shz_xmtrx_apply_rotation_y`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_y/)


---
# shz_vec3_rotate_z

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_rotate_z(shz_vec3_t vec, float radians) SHZ_NOEXCEPT;
```

Rotates the given 3D vector about the Z axis by the given angle in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `radians` | `float` |  |

## Returns

`shz_vec3_t`

## Warnings

- This routine should only be used for one-off rotations of a single vector. To rotate multiple vectors in a batch, use the XMTRX API.

## Availability

- **C++ equivalent:** [`shz::vec3::rotate_z`](https://sh4zam.com/api/cpp/vec3/#rotate_z)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:681`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L681)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Angles"

## See also

[`shz_xmtrx_apply_rotation_z`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_z/)


---
# shz_vec3_round

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_round(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the rounded values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::round`](https://sh4zam.com/api/cpp/vec3/#round)
- **Type-generic form:** [`shz_vec_round()`](https://sh4zam.com/api/vector/shz_vec_round/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:213`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L213)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_saturate

Source: 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

```c
SHZ_INLINE shz_vec3_t shz_vec3_saturate(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are saturated (clamped to \[0, 1\]) values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::saturate`](https://sh4zam.com/api/cpp/vec3/#saturate)
- **Type-generic form:** [`shz_vec_saturate()`](https://sh4zam.com/api/vector/shz_vec_saturate/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:240`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L240)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_scale

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_scale(shz_vec3_t vec, float factor) SHZ_NOEXCEPT;
```

Returns a 3D vector whose component values are those of the given vector multiplied by a factor.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `factor` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_scale()`](https://sh4zam.com/api/vector/shz_vec_scale/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:392`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L392)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec3_sign

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_sign(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the signs (-1, 0, or 1) of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::sign`](https://sh4zam.com/api/cpp/vec3/#sign)
- **Type-generic form:** [`shz_vec_sign()`](https://sh4zam.com/api/vector/shz_vec_sign/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:231`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L231)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_smoothstep_safe

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_smoothstep_safe(shz_vec3_t vec, float edge0, float edge1) SHZ_NOEXCEPT;
```

For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. Accepts inverse edges.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `edge0` | `float` |  |
| `edge1` | `float` |  |

## Returns

`shz_vec3_t`

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::vec3::smoothstep_safe`](https://sh4zam.com/api/cpp/vec3/#smoothstep_safe)
- **Type-generic form:** [`shz_vec_smoothstep_safe()`](https://sh4zam.com/api/vector/shz_vec_smoothstep_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:312`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L312)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_smoothstep

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_smoothstep(shz_vec3_t vec, float edge0, float edge1) SHZ_NOEXCEPT;
```

For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `edge0` | `float` |  |
| `edge1` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::smoothstep`](https://sh4zam.com/api/cpp/vec3/#smoothstep)
- **Type-generic form:** [`shz_vec_smoothstep()`](https://sh4zam.com/api/vector/shz_vec_smoothstep/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:294`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L294)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_smoothstepv_safe

Source: 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

```c
SHZ_INLINE shz_vec3_t shz_vec3_smoothstepv_safe(shz_vec3_t vec, shz_vec3_t edge0, shz_vec3_t edge1) SHZ_NOEXCEPT;
```

For each component i: returns 0.0f at/below edge0\[i\], 1.0f at/above edge1\[i\], smoothly varying in-between. Accepts inverse edges.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `edge0` | `shz_vec3_t` |  |
| `edge1` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_smoothstepv_safe()`](https://sh4zam.com/api/vector/shz_vec_smoothstepv_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:321`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L321)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_smoothstepv

Source: 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

```c
SHZ_INLINE shz_vec3_t shz_vec3_smoothstepv(shz_vec3_t vec, shz_vec3_t edge0, shz_vec3_t edge1) SHZ_NOEXCEPT;
```

For each component i: returns 0.0f at/below edge0\[i\], 1.0f at/above edge1\[i\], smoothly varying in-between.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `edge0` | `shz_vec3_t` |  |
| `edge1` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_smoothstepv()`](https://sh4zam.com/api/vector/shz_vec_smoothstepv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:303`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L303)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_sqrtf

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_sqrtf(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are the square root of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::sqrtf`](https://sh4zam.com/api/cpp/vec3/#sqrtf)
- **Type-generic form:** [`shz_vec_sqrtf()`](https://sh4zam.com/api/vector/shz_vec_sqrtf/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:339`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L339)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_step

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

> For each component: returns 0.0f if vec[i] < edge, otherwise 1.0f

```c
SHZ_INLINE shz_vec3_t shz_vec3_step(shz_vec3_t vec, float edge) SHZ_NOEXCEPT;
```

For each component: returns 0.0f if vec\[i\] \< edge, otherwise 1.0f.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `edge` | `float` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::step`](https://sh4zam.com/api/cpp/vec3/#step)
- **Type-generic form:** [`shz_vec_step()`](https://sh4zam.com/api/vector/shz_vec_step/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:285`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L285)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_stepv

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

> For each component: returns 0.0f if vec[i] < edge[i], otherwise 1.0f

```c
SHZ_INLINE shz_vec3_t shz_vec3_stepv(shz_vec3_t vec, shz_vec3_t edge) SHZ_NOEXCEPT;
```

For each component: returns 0.0f if vec\[i\] \< edge\[i\], otherwise 1.0f.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `edge` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_stepv()`](https://sh4zam.com/api/vector/shz_vec_stepv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:276`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L276)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec3_sub

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

> Returns a 3D vector whose components are equal to the values of vec1 minus vec2

```c
SHZ_INLINE shz_vec3_t shz_vec3_sub(shz_vec3_t vec1, shz_vec3_t vec2) SHZ_NOEXCEPT;
```

Returns a 3D vector whose components are equal to the values of `vec1` minus `vec2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec3_t` |  |
| `vec2` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_sub()`](https://sh4zam.com/api/vector/shz_vec_sub/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:365`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L365)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec3_swizzle

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

```c
SHZ_INLINE shz_vec3_t shz_vec3_swizzle(shz_vec3_t vec, unsigned x_idx, unsigned y_idx, unsigned z_idx) SHZ_NOEXCEPT;
```

Returns a 3D vector whose elements are equal to the source vector's values at the given indices.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `x_idx` | `unsigned` |  |
| `y_idx` | `unsigned` |  |
| `z_idx` | `unsigned` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::vec3::swizzle`](https://sh4zam.com/api/cpp/vec3/#swizzle)
- **Type-generic form:** [`shz_vec_swizzle()`](https://sh4zam.com/api/vector/shz_vec_swizzle/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:710`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L710)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Swizzling"


---
# shz_vec3_t

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

```c
typedef struct shz_vec3 {
    union {
        float e[3];              //!< <X, Y, Z> coordinates as an array
        struct {
            union {
                struct {
                    float x;     //!< X coordinate
                    float y;     //!< Y coordinate
                };
                shz_vec2_t xy;   //!< Inner 2D vector containing <X, Y> coords
            };
            float z;             //!< Z coordinate
        };
    };
} shz_vec3_t;
```

3D Vector type

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `e` | `float[3]` | \<X, Y, Z> coordinates as an array |
| `z` | `float` | Z coordinate. |
| `xy` | `shz_vec2_t` | Inner 2D vector containing \<X, Y> coords. |
| `x` | `float` | X coordinate. |
| `y` | `float` | Y coordinate. |

## Details

Structure for holding coordinates of a 3-dimensional vector.

## Availability

- **C++ equivalent:** [`shz::vec3`](https://sh4zam.com/api/cpp/vec3/)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:57`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L57)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Types"

## See also

[`shz_vec2_t`](https://sh4zam.com/api/vector/shz_vec2_t/), [`shz_vec4_t`](https://sh4zam.com/api/vector/shz_vec4_t/)


---
# shz_vec3_to

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

> Converts the given 3D vector into a value of the given type

```c
#define shz_vec3_to(type, vector) SHZ_CONVERT(type, vector)
```

Converts the given 3D `vector` into a value of the given `type`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `type` |  |  |
| `vector` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:746`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L746)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Adapters"


---
# shz_vec3_triple

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

> Returns the 3D vector "triple product" between vector's a, b, and c

```c
SHZ_INLINE float shz_vec3_triple(shz_vec3_t a, shz_vec3_t b, shz_vec3_t c) SHZ_NOEXCEPT;
```

Returns the 3D vector "triple product" between vector's `a`, `b`, and `c`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec3_t` |  |
| `b` | `shz_vec3_t` |  |
| `c` | `shz_vec3_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec3::triple`](https://sh4zam.com/api/cpp/vec3/#triple)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:599`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L599)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Miscellaneous"


---
# shz_vec3_vec4

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

> Extends a 3D vector to 4D, using w as the value of the W component

```c
SHZ_INLINE shz_vec4_t shz_vec3_vec4(shz_vec3_t vec, float w) SHZ_NOEXCEPT;
```

Extends a 3D vector to 4D, using `w` as the value of the W component.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |
| `w` | `float` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:697`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L697)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Extending"


---
# shz_vec3

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

> Alternate typedef for the shz_vec3 struct for those who hate POSIX-style

```c
typedef shz_vec3_t shz_vec3;
```

Alternate typedef for the [`shz_vec3`](https://sh4zam.com/api/vector/shz_vec3/) struct for those who hate POSIX-style.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:74`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L74)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Types"


---
# shz_vec4_abs

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_abs(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the absolute values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::abs`](https://sh4zam.com/api/cpp/vec4/#abs)
- **Type-generic form:** [`shz_vec_abs()`](https://sh4zam.com/api/vector/shz_vec_abs/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:144`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L144)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_add

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_add(shz_vec4_t vec1, shz_vec4_t vec2) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the sums of the given vectors' components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec4_t` |  |
| `vec2` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_add()`](https://sh4zam.com/api/vector/shz_vec_add/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: dedicated SPU implementation
- **Defined in:** [`sh4zam/shz_vector.h:359`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L359)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec4_ceil

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_ceil(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the ceil of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::ceil`](https://sh4zam.com/api/cpp/vec4/#ceil)
- **Type-generic form:** [`shz_vec_ceil()`](https://sh4zam.com/api/vector/shz_vec_ceil/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:207`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L207)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_clamp

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

> Clamps the values of the given 4D vec between min and max, returning a new vector

```c
SHZ_INLINE shz_vec4_t shz_vec4_clamp(shz_vec4_t vec, float min, float max) SHZ_NOEXCEPT;
```

Clamps the values of the given 4D `vec` between `min` and `max`, returning a new vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `min` | `float` |  |
| `max` | `float` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::clamp`](https://sh4zam.com/api/cpp/vec4/#clamp)
- **Type-generic form:** [`shz_vec_clamp()`](https://sh4zam.com/api/vector/shz_vec_clamp/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:189`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L189)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_deref

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

> Dereferences the given pointer to a sequence of 4 floats as a shz_vec4_t

```c
#define shz_vec4_deref(ptr) (*((SHZ_ALIASING shz_vec4_t*)(ptr)))
```

Dereferences the given pointer to a sequence of 4 floats as a [`shz_vec4_t`](https://sh4zam.com/api/vector/shz_vec4_t/).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ptr` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:731`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L731)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Adapters"


---
# shz_vec4_distance_sqr

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

```c
SHZ_INLINE float shz_vec4_distance_sqr(shz_vec4_t vec1, shz_vec4_t vec2) SHZ_NOEXCEPT;
```

Returns the squared-distance between the two given 4D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec4_t` |  |
| `vec2` | `shz_vec4_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec4::distance_sqr`](https://sh4zam.com/api/cpp/vec4/#distance_sqr)
- **Type-generic form:** [`shz_vec_distance_sqr()`](https://sh4zam.com/api/vector/shz_vec_distance_sqr/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:508`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L508)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec4_distance

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

```c
SHZ_INLINE float shz_vec4_distance(shz_vec4_t vec1, shz_vec4_t vec2) SHZ_NOEXCEPT;
```

Returns the distance between the two given 4D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec4_t` |  |
| `vec2` | `shz_vec4_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec4::distance`](https://sh4zam.com/api/cpp/vec4/#distance)
- **Type-generic form:** [`shz_vec_distance()`](https://sh4zam.com/api/vector/shz_vec_distance/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:499`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L499)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec4_div

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

> Returns a 4D vector whose component values are those of vec1 divided by vec2

```c
SHZ_INLINE shz_vec4_t shz_vec4_div(shz_vec4_t vec1, shz_vec4_t vec2) SHZ_NOEXCEPT;
```

Returns a 4D vector whose component values are those of `vec1` divided by `vec2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec4_t` |  |
| `vec2` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_div()`](https://sh4zam.com/api/vector/shz_vec_div/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: dedicated SPU implementation
- **Defined in:** [`sh4zam/shz_vector.h:386`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L386)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec4_dot

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

```c
SHZ_INLINE float shz_vec4_dot(shz_vec4_t vec1, shz_vec4_t vec2) SHZ_NOEXCEPT;
```

Returns the dot product between the two given 4D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec4_t` |  |
| `vec2` | `shz_vec4_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_dot()`](https://sh4zam.com/api/vector/shz_vec_dot/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:484`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L484)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec4_dot2

Source: 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

```c
SHZ_INLINE shz_vec2_t shz_vec4_dot2(shz_vec4_t l, shz_vec4_t r1, shz_vec4_t r2) SHZ_NOEXCEPT;
```

Returns the two dot products taken between the 4D vector `l` and 4D vectors `r1` and `r2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `l` | `shz_vec4_t` |  |
| `r1` | `shz_vec4_t` |  |
| `r2` | `shz_vec4_t` |  |

## Returns

`shz_vec2_t`

## Naming and requirements

- `dot2/dot3`: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined `FIPR` sequence. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_dot2()`](https://sh4zam.com/api/vector/shz_vec_dot2/)
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:487`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L487)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec4_dot3

Source: 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

```c
SHZ_INLINE shz_vec3_t shz_vec4_dot3(shz_vec4_t l, shz_vec4_t r1, shz_vec4_t r2, shz_vec4_t r3) SHZ_NOEXCEPT;
```

Returns the three dot products taken between the 4D vector `l` and 4D vectors `r1`, `r2`, and `r3`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `l` | `shz_vec4_t` |  |
| `r1` | `shz_vec4_t` |  |
| `r2` | `shz_vec4_t` |  |
| `r3` | `shz_vec4_t` |  |

## Returns

`shz_vec3_t`

## Naming and requirements

- `dot2/dot3`: Computes 2 or 3 dot products of one left-hand side against several right-hand sides in one pipelined `FIPR` sequence. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_dot3()`](https://sh4zam.com/api/vector/shz_vec_dot3/)
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:490`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L490)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec4_equal

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

```c
SHZ_INLINE bool shz_vec4_equal(shz_vec4_t a, shz_vec4_t b) SHZ_NOEXCEPT;
```

Returns true if the values of each element within the two 4D vectors are approximately equal based on relative or absolute tolerance.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec4_t` |  |
| `b` | `shz_vec4_t` |  |

## Returns

`bool`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_equal()`](https://sh4zam.com/api/vector/shz_vec_equal/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:270`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L270)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_fill

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

> Returns a 4D vector with the value of each component equal to v

```c
SHZ_INLINE shz_vec4_t shz_vec4_fill(float v) SHZ_NOEXCEPT;
```

Returns a 4D vector with the value of each component equal to `v`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `v` | `float` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: dedicated SPU implementation
- **Defined in:** [`sh4zam/shz_vector.h:128`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L128)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Initializers"


---
# shz_vec4_floor

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_floor(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the floor of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::floor`](https://sh4zam.com/api/cpp/vec4/#floor)
- **Type-generic form:** [`shz_vec_floor()`](https://sh4zam.com/api/vector/shz_vec_floor/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:198`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L198)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_fract

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_fract(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the fractional parts of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::fract`](https://sh4zam.com/api/cpp/vec4/#fract)
- **Type-generic form:** [`shz_vec_fract()`](https://sh4zam.com/api/vector/shz_vec_fract/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:225`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L225)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_from

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

> Converts the given value or expression to the equivalent 4D SH4ZAM vector value

```c
#define shz_vec4_from(value) SHZ_CONVERT(shz_vec4_t, value)
```

Converts the given `value` or expression to the equivalent 4D SH4ZAM vector value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:740`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L740)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Adapters"


---
# shz_vec4_init

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

> Returns a 4D vector with the given x, y, z, and w coordinates

```c
SHZ_INLINE shz_vec4_t shz_vec4_init(float x, float y, float z, float w) SHZ_NOEXCEPT;
```

Returns a 4D vector with the given `x`, `y`, `z`, and `w` coordinates.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |
| `w` | `float` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:119`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L119)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Initializers"


---
# shz_vec4_inv_sqrtf

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_inv_sqrtf(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the inverse square root of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::inv_sqrtf`](https://sh4zam.com/api/cpp/vec4/#inv_sqrtf)
- **Type-generic form:** [`shz_vec_inv_sqrtf()`](https://sh4zam.com/api/vector/shz_vec_inv_sqrtf/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: dedicated SPU implementation
- **Defined in:** [`sh4zam/shz_vector.h:333`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L333)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_inv

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_inv(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns the 4D vector whose components have been inverted or reciprocated.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::inv`](https://sh4zam.com/api/cpp/vec4/#inv)
- **Type-generic form:** [`shz_vec_inv()`](https://sh4zam.com/api/vector/shz_vec_inv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:162`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L162)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_lerp

Source: 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

```c
SHZ_INLINE shz_vec4_t shz_vec4_lerp(shz_vec4_t a, shz_vec4_t b, float t) SHZ_NOEXCEPT;
```

Returns a 4D vector that is linearly interpolated from `a` to `b` by the given `0.0f-1.0f` factor, `t`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec4_t` |  |
| `b` | `shz_vec4_t` |  |
| `t` | `float` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::lerp`](https://sh4zam.com/api/cpp/vec4/#lerp)
- **Type-generic form:** [`shz_vec_lerp()`](https://sh4zam.com/api/vector/shz_vec_lerp/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:526`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L526)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec4_magnitude_inv

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

```c
SHZ_INLINE float shz_vec4_magnitude_inv(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns the inverse magnitude of the given 4D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec4::magnitude_inv`](https://sh4zam.com/api/cpp/vec4/#magnitude_inv)
- **Type-generic form:** [`shz_vec_magnitude_inv()`](https://sh4zam.com/api/vector/shz_vec_magnitude_inv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:429`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L429)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec4_magnitude_sqr

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

```c
SHZ_INLINE float shz_vec4_magnitude_sqr(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns the squared magnitude of the given 4D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec4::magnitude_sqr`](https://sh4zam.com/api/cpp/vec4/#magnitude_sqr)
- **Type-generic form:** [`shz_vec_magnitude_sqr()`](https://sh4zam.com/api/vector/shz_vec_magnitude_sqr/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:408`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L408)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec4_magnitude

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

```c
SHZ_INLINE float shz_vec4_magnitude(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns the magnitude of the given 4D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec4::magnitude`](https://sh4zam.com/api/cpp/vec4/#magnitude)
- **Type-generic form:** [`shz_vec_magnitude()`](https://sh4zam.com/api/vector/shz_vec_magnitude/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:420`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L420)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec4_max

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

```c
SHZ_INLINE float shz_vec4_max(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns the maximum value of the given vector's 4 componetns.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec4::max`](https://sh4zam.com/api/cpp/vec4/#max)
- **Type-generic form:** [`shz_vec_max()`](https://sh4zam.com/api/vector/shz_vec_max/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:171`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L171)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_maxv

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_maxv(shz_vec4_t a, shz_vec4_t b) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the pairwise maximums of the two given vectors' components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec4_t` |  |
| `b` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::maxv`](https://sh4zam.com/api/cpp/vec4/#maxv)
- **Type-generic form:** [`shz_vec_maxv()`](https://sh4zam.com/api/vector/shz_vec_maxv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:261`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L261)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_min

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

```c
SHZ_INLINE float shz_vec4_min(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns the minimum value of the given vector's 4 components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::vec4::min`](https://sh4zam.com/api/cpp/vec4/#min)
- **Type-generic form:** [`shz_vec_min()`](https://sh4zam.com/api/vector/shz_vec_min/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:180`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L180)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_minv

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_minv(shz_vec4_t a, shz_vec4_t b) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the pairwise minimums of the two given vectors' components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `shz_vec4_t` |  |
| `b` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::minv`](https://sh4zam.com/api/cpp/vec4/#minv)
- **Type-generic form:** [`shz_vec_minv()`](https://sh4zam.com/api/vector/shz_vec_minv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:252`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L252)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_move

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

> Returns the given 4D vector, translated towards the target by the given max_distance

```c
SHZ_INLINE shz_vec4_t shz_vec4_move(shz_vec4_t vec, shz_vec4_t target, float max_distance) SHZ_NOEXCEPT;
```

Returns the given 4D vector, translated towards the `target` by the given `max_distance`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `target` | `shz_vec4_t` |  |
| `max_distance` | `float` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::move`](https://sh4zam.com/api/cpp/vec4/#move)
- **Type-generic form:** [`shz_vec_move()`](https://sh4zam.com/api/vector/shz_vec_move/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:517`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L517)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec4_mul

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

> Returns a 4D vector whose component values are those of vec1 times vec2

```c
SHZ_INLINE shz_vec4_t shz_vec4_mul(shz_vec4_t vec1, shz_vec4_t vec2) SHZ_NOEXCEPT;
```

Returns a 4D vector whose component values are those of `vec1` times `vec2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec4_t` |  |
| `vec2` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_mul()`](https://sh4zam.com/api/vector/shz_vec_mul/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: dedicated SPU implementation
- **Defined in:** [`sh4zam/shz_vector.h:377`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L377)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec4_neg

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_neg(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the negative values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::neg`](https://sh4zam.com/api/cpp/vec4/#neg)
- **Type-generic form:** [`shz_vec_neg()`](https://sh4zam.com/api/vector/shz_vec_neg/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:153`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L153)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_normalize_safe

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_normalize_safe(shz_vec4_t vec) SHZ_NOEXCEPT;
```

SAFELY returns a normalized unit vector from the given 4D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Details

If the vector's magnitude is not `> 0.0f`, safely returns a zero vector.

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::vec4::direction_safe`](https://sh4zam.com/api/cpp/vec4/#direction_safe), [`shz::vec4::normalize_safe`](https://sh4zam.com/api/cpp/vec4/#normalize_safe), [`shz::vec4::normalized_safe`](https://sh4zam.com/api/cpp/vec4/#normalized_safe)
- **Type-generic form:** [`shz_vec_normalize_safe()`](https://sh4zam.com/api/vector/shz_vec_normalize_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:456`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L456)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec4_normalize

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_normalize(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns a normalized unit vector from the given 4D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::direction`](https://sh4zam.com/api/cpp/vec4/#direction), [`shz::vec4::normalize`](https://sh4zam.com/api/cpp/vec4/#normalize), [`shz::vec4::normalized`](https://sh4zam.com/api/cpp/vec4/#normalized)
- **Type-generic form:** [`shz_vec_normalize()`](https://sh4zam.com/api/vector/shz_vec_normalize/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:438`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L438)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Magnitude"


---
# shz_vec4_project_safe

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_project_safe(shz_vec4_t vec, shz_vec4_t onto) SHZ_NOEXCEPT;
```

Returns the resulting vector from projecting the given 4D vector along the given (unit) axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `onto` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Notes

- This routine should safely return the zero vector when `vec` has a magnitude of 0.0f.

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::vec4::project_safe`](https://sh4zam.com/api/cpp/vec4/#project_safe)
- **Type-generic form:** [`shz_vec_project_safe()`](https://sh4zam.com/api/vector/shz_vec_project_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:586`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L586)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec4_project

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_project(shz_vec4_t vec, shz_vec4_t onto) SHZ_NOEXCEPT;
```

Returns the resulting vector from projecting the given 4D vector along the given (unit) axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `onto` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::project`](https://sh4zam.com/api/cpp/vec4/#project)
- **Type-generic form:** [`shz_vec_project()`](https://sh4zam.com/api/vector/shz_vec_project/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:565`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L565)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec4_reflect

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

> Reflects the given 4D incidence vector against a surface with the given normal, returning the result

```c
SHZ_INLINE shz_vec4_t shz_vec4_reflect(shz_vec4_t incidence, shz_vec4_t normal) SHZ_NOEXCEPT;
```

Reflects the given 4D `incidence` vector against a surface with the given `normal`, returning the result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `incidence` | `shz_vec4_t` |  |
| `normal` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::reflect`](https://sh4zam.com/api/cpp/vec4/#reflect)
- **Type-generic form:** [`shz_vec_reflect()`](https://sh4zam.com/api/vector/shz_vec_reflect/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:535`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L535)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec4_refract

Source: 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

```c
SHZ_INLINE shz_vec4_t shz_vec4_refract(shz_vec4_t incidence, shz_vec4_t normal, float eta) SHZ_NOEXCEPT;
```

Refracts the given 4D `incidence` vector against a surface with the given `normal` using the given refraction index ratio, `eta`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `incidence` | `shz_vec4_t` |  |
| `normal` | `shz_vec4_t` |  |
| `eta` | `float` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::refract`](https://sh4zam.com/api/cpp/vec4/#refract)
- **Type-generic form:** [`shz_vec_refract()`](https://sh4zam.com/api/vector/shz_vec_refract/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:544`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L544)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Binary Operations"


---
# shz_vec4_round

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_round(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the rounded values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::round`](https://sh4zam.com/api/cpp/vec4/#round)
- **Type-generic form:** [`shz_vec_round()`](https://sh4zam.com/api/vector/shz_vec_round/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:216`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L216)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_saturate

Source: 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

```c
SHZ_INLINE shz_vec4_t shz_vec4_saturate(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are saturated (clamped to \[0, 1\]) values of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::saturate`](https://sh4zam.com/api/cpp/vec4/#saturate)
- **Type-generic form:** [`shz_vec_saturate()`](https://sh4zam.com/api/vector/shz_vec_saturate/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:243`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L243)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_scale

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_scale(shz_vec4_t vec, float factor) SHZ_NOEXCEPT;
```

Returns a 4D vector whose component values are those of the given vector multiplied by a factor.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `factor` | `float` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_scale()`](https://sh4zam.com/api/vector/shz_vec_scale/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:395`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L395)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec4_sign

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_sign(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the signs (-1, 0, or 1) of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::sign`](https://sh4zam.com/api/cpp/vec4/#sign)
- **Type-generic form:** [`shz_vec_sign()`](https://sh4zam.com/api/vector/shz_vec_sign/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:234`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L234)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_smoothstep_safe

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_smoothstep_safe(shz_vec4_t vec, float edge0, float edge1) SHZ_NOEXCEPT;
```

For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. Accepts inverse edges.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `edge0` | `float` |  |
| `edge1` | `float` |  |

## Returns

`shz_vec4_t`

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::vec4::smoothstep_safe`](https://sh4zam.com/api/cpp/vec4/#smoothstep_safe)
- **Type-generic form:** [`shz_vec_smoothstep_safe()`](https://sh4zam.com/api/vector/shz_vec_smoothstep_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:315`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L315)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_smoothstep

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_smoothstep(shz_vec4_t vec, float edge0, float edge1) SHZ_NOEXCEPT;
```

For each component: returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `edge0` | `float` |  |
| `edge1` | `float` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::smoothstep`](https://sh4zam.com/api/cpp/vec4/#smoothstep)
- **Type-generic form:** [`shz_vec_smoothstep()`](https://sh4zam.com/api/vector/shz_vec_smoothstep/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:297`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L297)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_smoothstepv_safe

Source: 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

```c
SHZ_INLINE shz_vec4_t shz_vec4_smoothstepv_safe(shz_vec4_t vec, shz_vec4_t edge0, shz_vec4_t edge1) SHZ_NOEXCEPT;
```

For each component i: returns 0.0f at/below edge0\[i\], 1.0f at/above edge1\[i\], smoothly varying in-between. Accepts inverse edges.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `edge0` | `shz_vec4_t` |  |
| `edge1` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Naming and requirements

- `_safe`: Guards degenerate input (zero-length vectors, zero denominators) at a small cost. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_smoothstepv_safe()`](https://sh4zam.com/api/vector/shz_vec_smoothstepv_safe/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:324`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L324)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_smoothstepv

Source: 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

```c
SHZ_INLINE shz_vec4_t shz_vec4_smoothstepv(shz_vec4_t vec, shz_vec4_t edge0, shz_vec4_t edge1) SHZ_NOEXCEPT;
```

For each component i: returns 0.0f at/below edge0\[i\], 1.0f at/above edge1\[i\], smoothly varying in-between.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `edge0` | `shz_vec4_t` |  |
| `edge1` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_smoothstepv()`](https://sh4zam.com/api/vector/shz_vec_smoothstepv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:306`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L306)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_sqrtf

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_sqrtf(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are the square root of the given vector's components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::sqrtf`](https://sh4zam.com/api/cpp/vec4/#sqrtf)
- **Type-generic form:** [`shz_vec_sqrtf()`](https://sh4zam.com/api/vector/shz_vec_sqrtf/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:342`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L342)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_step

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

> For each component: returns 0.0f if vec[i] < edge, otherwise 1.0f

```c
SHZ_INLINE shz_vec4_t shz_vec4_step(shz_vec4_t vec, float edge) SHZ_NOEXCEPT;
```

For each component: returns 0.0f if vec\[i\] \< edge, otherwise 1.0f.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `edge` | `float` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::step`](https://sh4zam.com/api/cpp/vec4/#step)
- **Type-generic form:** [`shz_vec_step()`](https://sh4zam.com/api/vector/shz_vec_step/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:288`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L288)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_stepv

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

> For each component: returns 0.0f if vec[i] < edge[i], otherwise 1.0f

```c
SHZ_INLINE shz_vec4_t shz_vec4_stepv(shz_vec4_t vec, shz_vec4_t edge) SHZ_NOEXCEPT;
```

For each component: returns 0.0f if vec\[i\] \< edge\[i\], otherwise 1.0f.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `edge` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_stepv()`](https://sh4zam.com/api/vector/shz_vec_stepv/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:279`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L279)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Component-wise Operations"


---
# shz_vec4_sub

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

> Returns a 4D vector whose components are equal to the values of vec1 minus vec2

```c
SHZ_INLINE shz_vec4_t shz_vec4_sub(shz_vec4_t vec1, shz_vec4_t vec2) SHZ_NOEXCEPT;
```

Returns a 4D vector whose components are equal to the values of `vec1` minus `vec2`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec1` | `shz_vec4_t` |  |
| `vec2` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** [`shz_vec_sub()`](https://sh4zam.com/api/vector/shz_vec_sub/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: dedicated SPU implementation
- **Defined in:** [`sh4zam/shz_vector.h:368`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L368)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Arithmetic"


---
# shz_vec4_swizzle

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

```c
SHZ_INLINE shz_vec4_t shz_vec4_swizzle(shz_vec4_t vec, unsigned x_idx, unsigned y_idx, unsigned z_idx, unsigned w_idx) SHZ_NOEXCEPT;
```

Returns a new 2D vector whose elements are equal to the source vector's values at the given indices.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |
| `x_idx` | `unsigned` |  |
| `y_idx` | `unsigned` |  |
| `z_idx` | `unsigned` |  |
| `w_idx` | `unsigned` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::vec4::swizzle`](https://sh4zam.com/api/cpp/vec4/#swizzle)
- **Type-generic form:** [`shz_vec_swizzle()`](https://sh4zam.com/api/vector/shz_vec_swizzle/)
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_vector.h:713`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L713)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Swizzling"


---
# shz_vec4_t

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

```c
typedef struct shz_vec4 {
    union {
        float e SHZ_SIMD(16);                 //!< <X, Y, Z, W> coordinates as an array.
        struct {
            union {
                struct {
                    float x;        //!< X coordinate
                    float y;        //!< Y coordinate
                    float z;        //!< Z coordinate
                };
                shz_vec3_t xyz;     //!< <X, Y, Z> coordinates as a 3D vector
            };
            float w;                //!< W coordinate
        };
        struct {
            shz_vec2_t xy;          //!< <X, Y> coordinates as a 2D vector
            shz_vec2_t zw;          //!< <Z, W> coordinates as a 2D vector
        };
    };
} shz_vec4_t;
```

4D Vector type

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `w` | `float` | W coordinate. |
| `xyz` | `shz_vec3_t` | \<X, Y, Z> coordinates as a 3D vector |
| `x` | `float` | X coordinate. |
| `y` | `float` | Y coordinate. |
| `z` | `float` | Z coordinate. |
| `xy` | `shz_vec2_t` | \<X, Y> coordinates as a 2D vector |
| `zw` | `shz_vec2_t` | \<Z, W> coordinates as a 2D vector |

## Details

Structure for holding coordinates of a 4-dimensional vector.

## Availability

- **C++ equivalent:** [`shz::vec4`](https://sh4zam.com/api/cpp/vec4/)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:82`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L82)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Types"

## See also

[`shz_vec2_t`](https://sh4zam.com/api/vector/shz_vec2_t/), [`shz_vec3_t`](https://sh4zam.com/api/vector/shz_vec3_t/)


---
# shz_vec4_to

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

> Converts the given 4D vector into a value of the given type

```c
#define shz_vec4_to(type, vector) SHZ_CONVERT(type, vector)
```

Converts the given 4D `vector` into a value of the given `type`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `type` |  |  |
| `vector` |  |  |

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:749`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L749)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Adapters"


---
# shz_vec4

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

> Alternate typedef for the shz_vec4 struct for those who hate POSIX-style

```c
typedef shz_vec4_t shz_vec4;
```

Alternate typedef for the [`shz_vec4`](https://sh4zam.com/api/vector/shz_vec4/) struct for those who hate POSIX-style.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_vector.h:105`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_vector.h#L105)
- **Module:** [Vector](https://sh4zam.com/api/vector/), section "Types"


---
# Version API

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

> Compile-time and link-time version checking of the SH4ZAM library

This file provides the utility macros and constants needed for implementing compile/link-time version checking of the SH4ZAM library. `SHZ_VERSION_INIT()` packs major, minor and patch fields into a single unsigned 32-bit value that can be compared for equality or inequality. `shz_version_linked()` returns the version of the library you actually linked against, so it can be checked against the headers you compiled with.

- **C header:** `#include <sh4zam/shz_version.h>`
- **C++ header:** `#include <sh4zam/shz_version.hpp>`
- **C++ types:** [`shz::version`](https://sh4zam.com/api/cpp/version/)
- **Symbols:** 9

## Compile-Time Utilities

Constants and methods for checking the compile-time SH4ZAM version.

| Symbol | Description |
| --- | --- |
| [`SHZ_VERSION_MAJOR`](https://sh4zam.com/api/version/SHZ_VERSION_MAJOR/) | Compile-time SH4ZAM major version. |
| [`SHZ_VERSION_MINOR`](https://sh4zam.com/api/version/SHZ_VERSION_MINOR/) | Compile-time SH4ZAM minor version. |
| [`SHZ_VERSION_PATCH`](https://sh4zam.com/api/version/SHZ_VERSION_PATCH/) | Compile-time Sh4ZAM patch version. |
| [`SHZ_VERSION`](https://sh4zam.com/api/version/SHZ_VERSION/) | Current SH4ZAM full compile-time version identifier, integer-compatible. |
| [`SHZ_VERSION_INIT`](https://sh4zam.com/api/version/SHZ_VERSION_INIT/) | Packs values of individual version components into a SH4ZAM full version value. |

## Link-Time Utilities

Methods for checking the link-time SH4ZAM version.

| Symbol | Description |
| --- | --- |
| [`shz_version_t`](https://sh4zam.com/api/version/shz_version_t/) | Integer-compatible value type containing a full SH4ZAM version. |
| [`shz_version`](https://sh4zam.com/api/version/shz_version-typedef/) | Version typedef for those who hate POSIX-style. |
| [`shz_version_linked`](https://sh4zam.com/api/version/shz_version_linked/) | Returns the full version of SH4ZAM that was linked against. |
| [`shz_version_fields`](https://sh4zam.com/api/version/shz_version_fields/) | Extracts the individual version component values from a full version. |


---
# shz_version_fields

Source: https://sh4zam.com/api/version/shz_version_fields/

```c
void shz_version_fields(shz_version_t version, uint8_t* major, uint16_t* minor, uint8_t* patch);
```

Extracts the individual version component values from a full version.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `version` | `shz_version_t` |  |
| `major` | `uint8_t *` |  |
| `minor` | `uint16_t *` |  |
| `patch` | `uint8_t *` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_version.h:64`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_version.h#L64)
- **Module:** [Version](https://sh4zam.com/api/version/), section "Link-Time Utilities"


---
# SHZ_VERSION_INIT

Source: https://sh4zam.com/api/version/SHZ_VERSION_INIT/

```c
#define SHZ_VERSION_INIT(major, minor, patch)
```

Packs values of individual version components into a SH4ZAM full version value.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `major` |  | Unsigned 8-bit field representing major version value. |
| `minor` |  | Unsigned 16-bit field representing minor version value. |
| `patch` |  | Unsigned 8-bit field representing patch version value. |

## Details

Combines values from individual version components into a single unsigned 32-bit integer which can be compared to other version values for equality or inequality.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_version.h:44`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_version.h#L44)
- **Module:** [Version](https://sh4zam.com/api/version/), section "Compile-Time Utilities"


---
# shz_version_linked

Source: https://sh4zam.com/api/version/shz_version_linked/

```c
shz_version_t shz_version_linked(void);
```

Returns the full version of SH4ZAM that was linked against.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

`shz_version_t`

## Availability

- **C++ equivalent:** [`shz::version::linked`](https://sh4zam.com/api/cpp/version/#linked)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_version.h:61`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_version.h#L61)
- **Module:** [Version](https://sh4zam.com/api/version/), section "Link-Time Utilities"


---
# SHZ_VERSION_MAJOR

Source: https://sh4zam.com/api/version/SHZ_VERSION_MAJOR/

```c
#define SHZ_VERSION_MAJOR 0
```

Compile-time SH4ZAM major version.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_version.h:25`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_version.h#L25)
- **Module:** [Version](https://sh4zam.com/api/version/), section "Compile-Time Utilities"


---
# SHZ_VERSION_MINOR

Source: https://sh4zam.com/api/version/SHZ_VERSION_MINOR/

```c
#define SHZ_VERSION_MINOR 9
```

Compile-time SH4ZAM minor version.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_version.h:26`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_version.h#L26)
- **Module:** [Version](https://sh4zam.com/api/version/), section "Compile-Time Utilities"


---
# SHZ_VERSION_PATCH

Source: https://sh4zam.com/api/version/SHZ_VERSION_PATCH/

```c
#define SHZ_VERSION_PATCH 1
```

Compile-time Sh4ZAM patch version.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_version.h:27`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_version.h#L27)
- **Module:** [Version](https://sh4zam.com/api/version/), section "Compile-Time Utilities"


---
# shz_version_t

Source: https://sh4zam.com/api/version/shz_version_t/

```c
typedef uint32_t shz_version_t;
```

Integer-compatible value type containing a full SH4ZAM version.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_version.h:55`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_version.h#L55)
- **Module:** [Version](https://sh4zam.com/api/version/), section "Link-Time Utilities"


---
# shz_version

Source: https://sh4zam.com/api/version/shz_version-typedef/

```c
typedef shz_version_t shz_version;
```

Version typedef for those who hate POSIX-style.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_version.h:58`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_version.h#L58)
- **Module:** [Version](https://sh4zam.com/api/version/), section "Link-Time Utilities"


---
# SHZ_VERSION

Source: https://sh4zam.com/api/version/SHZ_VERSION/

```c
#define SHZ_VERSION
```

Current SH4ZAM full compile-time version identifier, integer-compatible.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_version.h:30`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_version.h#L30)
- **Module:** [Version](https://sh4zam.com/api/version/), section "Compile-Time Utilities"


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


---
# shz_xmtrx_abs

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_abs/

```c
SHZ_INLINE void shz_xmtrx_abs(void) SHZ_NOEXCEPT;
```

Takes the absolute value of each element held within XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::abs`](https://sh4zam.com/api/cpp/xmtrx/#abs)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:839`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L839)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Miscellaneous"


---
# shz_xmtrx_add_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_add_4x4/

> Adds each element within mat to each element within XMTRX, storing the result in XMTRX

```c
SHZ_INLINE void shz_xmtrx_add_4x4(const shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Adds each element within `mat` to each element within XMTRX, storing the result in XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::xmtrx::add`](https://sh4zam.com/api/cpp/xmtrx/#add)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:820`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L820)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Component-Wise Matrix Operations"


---
# shz_xmtrx_apply_2x2

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_2x2/

```c
SHZ_INLINE void shz_xmtrx_apply_2x2(const shz_mat2x2_t* matrix) SHZ_NOEXCEPT;
```

Multiplies and accumulates the given 2x2 matrix onto XMTRX, not modifying other elements.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat2x2_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:447`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L447)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_3x3

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x3/

```c
SHZ_INLINE void shz_xmtrx_apply_3x3(const shz_mat3x3_t* matrix) SHZ_NOEXCEPT;
```

Multiplies and accumulates the given 3x3 matrix onto XMTRX, not modifying other elements.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat3x3_t *` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:441`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L441)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_3x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x4/

```c
SHZ_INLINE void shz_xmtrx_apply_3x4(const shz_mat3x4_t* matrix) SHZ_NOEXCEPT;
```

Multiplies and accumulates the given 3x4 matrix onto XMTRX, not modifying other elements.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat3x4_t *` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:429`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L429)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_4x4/

```c
SHZ_INLINE void shz_xmtrx_apply_4x4(const shz_mat4x4_t* matrix) SHZ_NOEXCEPT;
```

Multiplies and accumulates the given 4x4 matrix onto XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:405`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L405)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_frustum

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_frustum/

```c
SHZ_INLINE void shz_xmtrx_apply_frustum(float left, float right, float bottom, float top, float znear, float zfar) SHZ_NOEXCEPT;
```

Applies a frustum projection matrix onto XMTRX, equivalent to glFrustum().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `left` | `float` |  |
| `right` | `float` |  |
| `bottom` | `float` |  |
| `top` | `float` |  |
| `znear` | `float` |  |
| `zfar` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_frustum`](https://sh4zam.com/api/cpp/xmtrx/#apply_frustum)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:521`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L521)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_lookat

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_lookat/

```c
SHZ_INLINE void shz_xmtrx_apply_lookat(shz_vec3_t eye, shz_vec3_t center, shz_vec3_t up) SHZ_NOEXCEPT;
```

Applies the 3D "lookAt" matrix constructed with the given vector components onto XMTRX. Equivalent to gluLookAt().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `eye` | `shz_vec3_t` |  |
| `center` | `shz_vec3_t` |  |
| `up` | `shz_vec3_t` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_lookat`](https://sh4zam.com/api/cpp/xmtrx/#apply_lookat)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:515`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L515)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_ortho

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_ortho/

```c
SHZ_INLINE void shz_xmtrx_apply_ortho(float left, float right, float bottom, float top, float znear, float zfar) SHZ_NOEXCEPT;
```

Applies a 2D orthographic projection matrix onto XMTRX, equivalent to glOrtho().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `left` | `float` |  |
| `right` | `float` |  |
| `bottom` | `float` |  |
| `top` | `float` |  |
| `znear` | `float` |  |
| `zfar` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_ortho`](https://sh4zam.com/api/cpp/xmtrx/#apply_ortho)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:518`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L518)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_permutation_wxyz

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_permutation_wxyz/

```c
SHZ_INLINE void shz_xmtrx_apply_permutation_wxyz(void) SHZ_NOEXCEPT;
```

Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in WXYZ order.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_permutation_wxyz`](https://sh4zam.com/api/cpp/xmtrx/#apply_permutation_wxyz)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:549`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L549)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_permutation_wzyx

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_permutation_wzyx/

```c
SHZ_INLINE void shz_xmtrx_apply_permutation_wzyx(void) SHZ_NOEXCEPT;
```

Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in WZYX order.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_permutation_wzyx`](https://sh4zam.com/api/cpp/xmtrx/#apply_permutation_wzyx)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:555`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L555)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_permutation_yzwx

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_permutation_yzwx/

```c
SHZ_INLINE void shz_xmtrx_apply_permutation_yzwx(void) SHZ_NOEXCEPT;
```

Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in YZWX order.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_permutation_yzwx`](https://sh4zam.com/api/cpp/xmtrx/#apply_permutation_yzwx)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:552`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L552)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_perspective

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_perspective/

```c
SHZ_INLINE void shz_xmtrx_apply_perspective(float fov, float aspect, float znear) SHZ_NOEXCEPT;
```

Multiplies and accumulates the perspective matrix constructed from the given values onto XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `fov` | `float` |  |
| `aspect` | `float` |  |
| `znear` | `float` |  |

## Returns

Nothing (`void`).

## Details

| fr\[n + 0\] | fr\[n + 4\] | fr\[n + 8\] | fr\[n + 12\] |
| --- | --- | --- | --- |
| cot(f)/a | 0.0f | 0.0f | 0.0f |
| 0.0f | cot(f) | 0.0f | 0.0f |
| 0.0f | 0.0f | 0.0f | nz |
| 0.0f | 0.0f | -1.0f | 0.0f |

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_perspective`](https://sh4zam.com/api/cpp/xmtrx/#apply_perspective)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:532`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L532)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_reverse_3x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_3x4/

> Multiplies and accumulates XMTRX onto matrix, storing the result as XMTRX

```c
SHZ_INLINE void shz_xmtrx_apply_reverse_3x4(const shz_mat3x4_t* mat) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX onto `matrix`, storing the result as XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat3x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_reverse`: Reversed multiplication order (pre-multiply instead of post-multiply). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:435`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L435)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_reverse_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_4x4/

> Multiplies and accumulates XMTRX onto matrix, storing the result as XMTRX

```c
SHZ_INLINE void shz_xmtrx_apply_reverse_4x4(const shz_mat4x4_t* matrix) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX onto `matrix`, storing the result as XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_reverse`: Reversed multiplication order (pre-multiply instead of post-multiply). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:417`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L417)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_reverse_transpose_3x4

Source: 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

```c
SHZ_INLINE void shz_xmtrx_apply_reverse_transpose_3x4(const shz_mat3x4_t* mat) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX onto the transpose of `matrix`, storing the result as XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat3x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `_reverse`: Reversed multiplication order (pre-multiply instead of post-multiply). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:438`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L438)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_reverse_transpose_4x4

Source: 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

```c
SHZ_INLINE void shz_xmtrx_apply_reverse_transpose_4x4(const shz_mat4x4_t* matrix) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX onto the transpose of `matrix`, storing the result as XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `_reverse`: Reversed multiplication order (pre-multiply instead of post-multiply). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:423`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L423)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_reverse_transpose_unaligned_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_transpose_unaligned_4x4/

```c
SHZ_INLINE void shz_xmtrx_apply_reverse_transpose_unaligned_4x4(const float matrix[16]) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX onto the transpose of the given float array as a 4x4 matrix, storing the result as XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `_reverse`: Reversed multiplication order (pre-multiply instead of post-multiply). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:426`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L426)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_reverse_unaligned_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_reverse_unaligned_4x4/

```c
SHZ_INLINE void shz_xmtrx_apply_reverse_unaligned_4x4(const float matrix[16]) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX onto the given float array as a 4x4 matrix, storing the result as XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `_reverse`: Reversed multiplication order (pre-multiply instead of post-multiply). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:420`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L420)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_rotation_quat

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_quat/

```c
SHZ_INLINE void shz_xmtrx_apply_rotation_quat(shz_quat_t quat) SHZ_NOEXCEPT;
```

Transforms the values of the inner 3x3 matrix by the rotation matrix represented by the given quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `quat` | `shz_quat_t` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_rotation_quat`](https://sh4zam.com/api/cpp/xmtrx/#apply_rotation_quat)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:512`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L512)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_rotation_x

Source: 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

```c
SHZ_INLINE void shz_xmtrx_apply_rotation_x(float x) SHZ_NOEXCEPT;
```

Transforms the values of the inner 3x3 matrix by a rotation matrix of `x` radians about the X axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_rotation_x`](https://sh4zam.com/api/cpp/xmtrx/#apply_rotation_x)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:456`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L456)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_rotation_xyz

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_xyz/

```c
SHZ_INLINE void shz_xmtrx_apply_rotation_xyz(float xAngle, float yAngle, float zAngle) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by a 3D X-Y-Z rotation matrix, with the corresponding angles given in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `xAngle` | `float` |  |
| `yAngle` | `float` |  |
| `zAngle` | `float` |  |

## Returns

Nothing (`void`).

## Details

The transform is applied to the inner 3x3 values within XMTRX, preserving the translational components.

## Notes

- The given angles are represented as Tait-Bryan angles, representing an extrinsic rotation.

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_rotation_xyz`](https://sh4zam.com/api/cpp/xmtrx/#apply_rotation_xyz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:473`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L473)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"

## See also

[`shz_xmtrx_apply_rotation_zyx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_zyx/), [`shz_xmtrx_apply_rotation_yxz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_yxz/)


---
# shz_xmtrx_apply_rotation_y

Source: 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

```c
SHZ_INLINE void shz_xmtrx_apply_rotation_y(float y) SHZ_NOEXCEPT;
```

Transforms the values of the inner 3x3 matrix by a rotation matrix of `y` radians about the Y axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `y` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_rotation_y`](https://sh4zam.com/api/cpp/xmtrx/#apply_rotation_y)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:459`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L459)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_rotation_yxz

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_yxz/

```c
SHZ_INLINE void shz_xmtrx_apply_rotation_yxz(float yAngle, float xAngle, float zAngle) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by a 3D Y-X-Z rotation matrix, with the corresponding angles given in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `yAngle` | `float` |  |
| `xAngle` | `float` |  |
| `zAngle` | `float` |  |

## Returns

Nothing (`void`).

## Details

The transform is applied to the inner 3x3 values within XMTRX, preserving the translational components.

## Notes

- The given angles are represented as Tait-Bryan angles, representing an extrinsic rotation.

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_rotation_yxz`](https://sh4zam.com/api/cpp/xmtrx/#apply_rotation_yxz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:506`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L506)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"

## See also

[`shz_xmtrx_apply_rotation_xyz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_xyz/), [`shz_xmtrx_apply_rotation_zyx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_zyx/)


---
# shz_xmtrx_apply_rotation_z

Source: 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

```c
SHZ_INLINE void shz_xmtrx_apply_rotation_z(float z) SHZ_NOEXCEPT;
```

Transforms the values of the inner 3x3 matrix by a rotation matrix of `z` radians about the Z axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_rotation_z`](https://sh4zam.com/api/cpp/xmtrx/#apply_rotation_z)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:462`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L462)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_rotation_zxy

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_zxy/

```c
SHZ_INLINE void shz_xmtrx_apply_rotation_zxy(float zAngle, float xAngle, float yAngle) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by a 3D Z-X-Y rotation matrix, with the corresponding angles given in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `zAngle` | `float` |  |
| `xAngle` | `float` |  |
| `yAngle` | `float` |  |

## Returns

Nothing (`void`).

## Details

The transform is applied to the inner 3x3 values within XMTRX, preserving the translational components.

## Notes

- The given angles are represented as Tait-Bryan angles, representing an extrinsic rotation.

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_rotation_zxy`](https://sh4zam.com/api/cpp/xmtrx/#apply_rotation_zxy)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:495`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L495)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"

## See also

[`shz_xmtrx_apply_rotation_zyx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_zyx/), [`shz_xmtrx_apply_rotation_yxz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_yxz/)


---
# shz_xmtrx_apply_rotation_zyx

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_zyx/

```c
SHZ_INLINE void shz_xmtrx_apply_rotation_zyx(float zAngle, float yAngle, float xAngle) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by a 3D Z-Y-X rotation matrix, with the corresponding angles given in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `zAngle` | `float` |  |
| `yAngle` | `float` |  |
| `xAngle` | `float` |  |

## Returns

Nothing (`void`).

## Details

The transform is applied to the inner 3x3 values within XMTRX, preserving the translational components.

## Notes

- The given angles are represented as Tait-Bryan angles, representing an extrinsic rotation.

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_rotation_zyx`](https://sh4zam.com/api/cpp/xmtrx/#apply_rotation_zyx)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:484`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L484)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"

## See also

[`shz_xmtrx_apply_rotation_xyz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_xyz/), [`shz_xmtrx_apply_rotation_yxz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_rotation_yxz/)


---
# shz_xmtrx_apply_rotation

Source: 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

```c
SHZ_INLINE void shz_xmtrx_apply_rotation(float angle, float x, float y, float z) SHZ_NOEXCEPT;
```

Transforms the values of the inner 3x3 matrix by a rotation matrix of `angle` radians about the axis with the given components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `angle` | `float` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_rotation`](https://sh4zam.com/api/cpp/xmtrx/#apply_rotation)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:509`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L509)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_scale

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_scale/

```c
SHZ_INLINE void shz_xmtrx_apply_scale(float x, float y, float z) SHZ_NOEXCEPT;
```

Multiplies the values of the inner 3x3 matrix by the given 3D scaling terms.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_scale`](https://sh4zam.com/api/cpp/xmtrx/#apply_scale)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:453`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L453)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_screen

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_screen/

```c
SHZ_INLINE void shz_xmtrx_apply_screen(float width, float height) SHZ_NOEXCEPT;
```

Multiplies and accumulates the viewport matrix created with the given components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `width` | `float` |  |
| `height` | `float` |  |

## Returns

Nothing (`void`).

## Details

| fr\[n + 0\] | fr\[n + 4\] | fr\[n + 8\] | fr\[n + 12\] |
| --- | --- | --- | --- |
| w\*0.5f | 0.0f | 0.0f | w\*0.5f |
| 0.0f | -h\*0.5f | 0.0f | h\*0.5f |
| 0.0f | 0.0f | 1.0f | 0.0f |
| 0.0f | 0.0f | 0.0f | 1.0f |

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_screen`](https://sh4zam.com/api/cpp/xmtrx/#apply_screen)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:543`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L543)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_self

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_self/

```c
SHZ_INLINE void shz_xmtrx_apply_self(void) SHZ_NOEXCEPT;
```

Multiplies and accumulatse the XMTRX matrix by itself, squaring it.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_self`](https://sh4zam.com/api/cpp/xmtrx/#apply_self)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:558`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L558)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_store_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_store_4x4/

> Multiplies XMTRX by the matrix, in, storing the result within the matrix, out

```c
SHZ_INLINE void shz_xmtrx_apply_store_4x4(shz_mat4x4_t* out, const shz_mat4x4_t* in) SHZ_NOEXCEPT;
```

Multiplies XMTRX by the matrix, `in`, storing the result within the matrix, `out`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `out` | `shz_mat4x4_t *` |  |
| `in` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Details

This routine is roughly equivalent to: [`shz_xmtrx_apply_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_4x4/)(in); [`shz_xmtrx_store_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_4x4/)(out);

However, it has been optimized and pipelined for performing the multiply and store in parallel.

## Notes

- This is useful for when you want to multiply a batch of matrices by the same matrix, held within XMTRX.

## Warnings

- The result of the multiplication is not stored within XMTRX, despite it getting clobbered.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:658`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L658)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Compound Operations"

## See also

[`shz_xmtrx_apply_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_4x4/), [`shz_xmtrx_store_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_4x4/), [`shz_xmtrx_apply_store_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_store_unaligned_4x4/)


---
# shz_xmtrx_apply_store_unaligned_4x4

Source: 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

```c
SHZ_INLINE void shz_xmtrx_apply_store_unaligned_4x4(float out[16], const float in[16]) SHZ_NOEXCEPT;
```

Multiplies XMTRX by the unaligned matrix, `in`, storing the result within the unaligned matrix, `out`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `out` | `float [16]` |  |
| `in` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Details

This routine is roughly equivalent to: [`shz_xmtrx_apply_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_unaligned_4x4/)(in); [`shz_xmtrx_store_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_unaligned_4x4/)(out);

However, it has been optimized and pipelined for performing the multiply and store in parallel.

## Notes

- This is useful for when you want to multiply a batch of matrices by the same matrix, held within XMTRX.

## Warnings

- The result of the multiplication is not stored within XMTRX, despite it getting clobbered.

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:677`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L677)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Compound Operations"

## See also

[`shz_xmtrx_apply_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_unaligned_4x4/), [`shz_xmtrx_store_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_unaligned_4x4/), [`shz_xmtrx_apply_store_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_store_4x4/)


---
# shz_xmtrx_apply_symmetric_skew

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_symmetric_skew/

```c
SHZ_INLINE void shz_xmtrx_apply_symmetric_skew(float x, float y, float z) SHZ_NOEXCEPT;
```

Multiplies and accumulates the 3D symmetric skew matrix with the given components onto XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_symmetric_skew`](https://sh4zam.com/api/cpp/xmtrx/#apply_symmetric_skew)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:546`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L546)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_translation

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_translation/

```c
SHZ_INLINE void shz_xmtrx_apply_translation(float x, float y, float z) SHZ_NOEXCEPT;
```

Adds the values of the given 3 components to the 3D translation components of XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::apply_translation`](https://sh4zam.com/api/cpp/xmtrx/#apply_translation)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:450`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L450)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_transpose_3x3

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_3x3/

```c
SHZ_INLINE void shz_xmtrx_apply_transpose_3x3(const shz_mat3x3_t* matrix) SHZ_NOEXCEPT;
```

Multiplies and accumulates the transpose of the given 3x3 matrix onto XMTRX, not modifying other elements.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat3x3_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:444`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L444)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_transpose_3x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_3x4/

```c
SHZ_INLINE void shz_xmtrx_apply_transpose_3x4(const shz_mat3x4_t* matrix) SHZ_NOEXCEPT;
```

Multiplies and accumulates the transpose of the given 3x4 matrix onto XMTRX, not modifying other elements.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat3x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:432`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L432)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_transpose_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_4x4/

```c
SHZ_INLINE void shz_xmtrx_apply_transpose_4x4(const shz_mat4x4_t* matrix) SHZ_NOEXCEPT;
```

Multiplies and accumulates the transpose of the given 4x4 matrix onto XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:411`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L411)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_transpose_unaligned_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_transpose_unaligned_4x4/

```c
SHZ_INLINE void shz_xmtrx_apply_transpose_unaligned_4x4(const float matrix[16]) SHZ_NOEXCEPT;
```

Multiplies and accumulates the transpose of the given 16-entry float array as a 4x4 matrix onto XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:414`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L414)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_apply_unaligned_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_unaligned_4x4/

```c
SHZ_INLINE void shz_xmtrx_apply_unaligned_4x4(const float matrix[16]) SHZ_NOEXCEPT;
```

Multiplies and accumulates the given 16-entry float array as a 4x4 matrix onto XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:408`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L408)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Apply Operation"


---
# shz_xmtrx_blend_3x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_blend_3x4/

```c
SHZ_INLINE void shz_xmtrx_blend_3x4(const shz_mat3x4_t* matrix, float weight) SHZ_NOEXCEPT;
```

Adds and accumulates a scaled 3x4 matrix onto XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat3x4_t *` | 3x4 matrix to multiply and accumulate onto XMTRX. |
| `weight` | `float` | Factor each element in `matrix` gets scaled by. |

## Returns

Nothing (`void`).

## Details

Each component of `joint_matrix` will be multiplied by `weight`, with the result being added to the existing value of that component of XMTRX.

This is useful for accumulating weighted joint matrices onto an initially zeroed-out XMTRX. This allows for in-place construction of a skin matrix, which can then be directly used to transform the vertices of a mesh against for animation.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:897`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L897)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Miscellaneous"

## See also

[`shz_xmtrx_init_zero`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_zero/), [`shz_xmtrx_blend_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_blend_4x4/)


---
# shz_xmtrx_blend_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_blend_4x4/

```c
SHZ_INLINE void shz_xmtrx_blend_4x4(const shz_mat4x4_t* matrix, float weight) SHZ_NOEXCEPT;
```

Adds and accumulates a scaled 4x4 matrix onto XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat4x4_t *` | 4x4 matrix to multiply and accumulate onto XMTRX. |
| `weight` | `float` | Factor each element in `matrix` gets scaled by. |

## Returns

Nothing (`void`).

## Details

Each component of `joint_matrix` will be multiplied by `weight`, with the result being added to the existing value of that component of XMTRX.

This is useful for accumulating weighted joint matrices onto an initially zeroed-out XMTRX. This allows for in-place construction of a skin matrix, which can then be directly used to transform the vertices of a mesh against for animation.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:881`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L881)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Miscellaneous"

## See also

[`shz_xmtrx_init_zero`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_zero/), [`shz_xmtrx_blend_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_blend_3x4/)


---
# shz_xmtrx_blend

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_blend/

```c
SHZ_INLINE void shz_xmtrx_blend(const shz_mat4x4_t* matrix, float weight) SHZ_NOEXCEPT;
```

Deprecated way to add and accumulate a scaled 4x4 matrix onto XMTRX.

**Deprecated:** This routine has been renamed to `shz_xmtrx_blend_4x4()`, as support is being added to blend matrices of different dimensions onto XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat4x4_t *` |  |
| `weight` | `float` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:865`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L865)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Miscellaneous"

## See also

[`shz_xmtrx_blend_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_blend_4x4/)


---
# shz_xmtrx_determinant

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_determinant/

```c
float shz_xmtrx_determinant(void) SHZ_NOEXCEPT;
```

Returns the determinant of XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** [`shz::xmtrx::determinant`](https://sh4zam.com/api/cpp/xmtrx/#determinant)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:845`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L845)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Miscellaneous"


---
# shz_xmtrx_get_scale

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_get_scale/

```c
SHZ_INLINE shz_vec3_t shz_xmtrx_get_scale(void) SHZ_NOEXCEPT;
```

Returns the scaling components from the inner 3x3 matrix of XMTRX, as a 3D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

`shz_vec3_t`

## Warnings

- This routine assumes XMTRX is a standard TRS-style transform matrix, without shearing or reflection.

## Availability

- **C++ equivalent:** [`shz::xmtrx::get_scale`](https://sh4zam.com/api/cpp/xmtrx/#get_scale)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:810`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L810)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Getters"


---
# shz_xmtrx_get_translation

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_get_translation/

```c
SHZ_INLINE shz_vec3_t shz_xmtrx_get_translation(void) SHZ_NOEXCEPT;
```

Returns the translational components from the last column of XMTRX, as a 3D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** [`shz::xmtrx::get_translation`](https://sh4zam.com/api/cpp/xmtrx/#get_translation)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:803`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L803)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Getters"


---
# shz_xmtrx_init_diagonal

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_diagonal/

```c
SHZ_INLINE void shz_xmtrx_init_diagonal(float x, float y, float z, float w) SHZ_NOEXCEPT;
```

Initializes XMTRX to be a diagonal matrix with the given diagonal values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |
| `w` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_diagonal`](https://sh4zam.com/api/cpp/xmtrx/#init_diagonal)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:332`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L332)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_fill

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_fill/

> Initializes XMTRX to contain the given value for each element

```c
SHZ_INLINE void shz_xmtrx_init_fill(float value) SHZ_NOEXCEPT;
```

Initializes XMTRX to contain the given `value` for each element.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_fill`](https://sh4zam.com/api/cpp/xmtrx/#init_fill)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:258`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L258)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_frustum

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_frustum/

```c
SHZ_INLINE void shz_xmtrx_init_frustum(float left, float right, float bottom, float top, float znear, float zfar) SHZ_NOEXCEPT;
```

Initializes XMTRX to a frustum projection matrix, equivalent to glFrustum().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `left` | `float` |  |
| `right` | `float` |  |
| `bottom` | `float` |  |
| `top` | `float` |  |
| `znear` | `float` |  |
| `zfar` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers any previous XMTRX contents.

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_frustum`](https://sh4zam.com/api/cpp/xmtrx/#init_frustum)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:382`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L382)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_identity_safe

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_identity_safe/

```c
SHZ_INLINE void shz_xmtrx_init_identity_safe(void) SHZ_NOEXCEPT;
```

Safely initializes XMTRX to be a 4D identity matrix.

**Deprecated:** `shz_xmtrx_init_identity()` is already safe now by default. This routine simply calls directly into it and should not be used.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:249`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L249)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"

## See also

[`shz_xmtrx_init_identity`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_identity/)


---
# shz_xmtrx_init_identity

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_identity/

```c
SHZ_INLINE void shz_xmtrx_init_identity(void) SHZ_NOEXCEPT;
```

Initializes XMTRX to the 4x4 identity matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_identity`](https://sh4zam.com/api/cpp/xmtrx/#init_identity), [`shz::xmtrx::init_identity_safe`](https://sh4zam.com/api/cpp/xmtrx/#init_identity_safe)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:238`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L238)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_lookat

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_lookat/

```c
SHZ_INLINE void shz_xmtrx_init_lookat(shz_vec3_t eye, shz_vec3_t center, shz_vec3_t up) SHZ_NOEXCEPT;
```

Initializes XMTRX to a "lookAt" view matrix, equivalent to gluLookAt().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `eye` | `shz_vec3_t` |  |
| `center` | `shz_vec3_t` |  |
| `up` | `shz_vec3_t` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers any previous XMTRX contents.

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_lookat`](https://sh4zam.com/api/cpp/xmtrx/#init_lookat)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:370`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L370)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_lower_triangular

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_lower_triangular/

```c
SHZ_INLINE void shz_xmtrx_init_lower_triangular(shz_vec4_t col1, shz_vec3_t col2, shz_vec2_t col3, float col4) SHZ_NOEXCEPT;
```

Initializes XMTRX to be a lower triangular matrix with the given column values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `col1` | `shz_vec4_t` |  |
| `col2` | `shz_vec3_t` |  |
| `col3` | `shz_vec2_t` |  |
| `col4` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_lower_triangular`](https://sh4zam.com/api/cpp/xmtrx/#init_lower_triangular)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:338`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L338)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_one

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_one/

```c
SHZ_INLINE void shz_xmtrx_init_one(void) SHZ_NOEXCEPT;
```

Initializes XMTRX to contain the value of 1.0f for each element.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_one`](https://sh4zam.com/api/cpp/xmtrx/#init_one)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:255`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L255)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_ortho

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_ortho/

```c
SHZ_INLINE void shz_xmtrx_init_ortho(float left, float right, float bottom, float top, float znear, float zfar) SHZ_NOEXCEPT;
```

Initializes XMTRX to an orthographic projection matrix, equivalent to glOrtho().

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `left` | `float` |  |
| `right` | `float` |  |
| `bottom` | `float` |  |
| `top` | `float` |  |
| `znear` | `float` |  |
| `zfar` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers any previous XMTRX contents.

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_ortho`](https://sh4zam.com/api/cpp/xmtrx/#init_ortho)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:376`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L376)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_outer_product

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_outer_product/

```c
SHZ_INLINE void shz_xmtrx_init_outer_product(shz_vec4_t x, shz_vec4_t y) SHZ_NOEXCEPT;
```

Initializes XMTRX to the 4D matrix resulting from taking the outer product of the two 4D vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `shz_vec4_t` |  |
| `y` | `shz_vec4_t` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_outer_product`](https://sh4zam.com/api/cpp/xmtrx/#init_outer_product)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:344`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L344)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_permutation_wxyz

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_permutation_wxyz/

```c
SHZ_INLINE void shz_xmtrx_init_permutation_wxyz(void) SHZ_NOEXCEPT;
```

Initializes XMTRX to a permutation matrix, which reorders the components of transformed vectors to be in WXYZ order.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_permutation_wxyz`](https://sh4zam.com/api/cpp/xmtrx/#init_permutation_wxyz)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:347`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L347)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_permutation_wzyx

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_permutation_wzyx/

```c
SHZ_INLINE void shz_xmtrx_init_permutation_wzyx(void) SHZ_NOEXCEPT;
```

Initializes XMTRX to a permutation matrix, which reorders the components of transformed vectors to be in WZYX order.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_permutation_wzyx`](https://sh4zam.com/api/cpp/xmtrx/#init_permutation_wzyx)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:353`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L353)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_permutation_yzwx

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_permutation_yzwx/

```c
SHZ_INLINE void shz_xmtrx_init_permutation_yzwx(void) SHZ_NOEXCEPT;
```

Initializes XMTRX to a permutation matrix, which reorders the components of transformed vectors to be in YZWX order.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_permutation_yzwx`](https://sh4zam.com/api/cpp/xmtrx/#init_permutation_yzwx)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:350`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L350)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_perspective

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_perspective/

```c
SHZ_INLINE void shz_xmtrx_init_perspective(float fov, float aspect, float znear) SHZ_NOEXCEPT;
```

Initializes XMTRX to a perspective projection matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `fov` | `float` |  |
| `aspect` | `float` |  |
| `znear` | `float` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers any previous XMTRX contents.

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_perspective`](https://sh4zam.com/api/cpp/xmtrx/#init_perspective)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:388`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L388)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_rotation_dir

Source: 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

```c
SHZ_INLINE void shz_xmtrx_init_rotation_dir(float angle, float x, float y, float z) SHZ_NOEXCEPT;
```

Initializes XMTRX to contain a 3D rotation matrix of `angle` radians about the given `axis`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `angle` | `float` |  |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Details

This is a faster version of `shz_xmtrx_init_rotation()` or glRotatef() which requires being passed a unit vector for the rotation axis.

## Warnings

- The vector components representing the axis of rotation must be prenormalized!

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_rotation_dir`](https://sh4zam.com/api/cpp/xmtrx/#init_rotation_dir)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:329`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L329)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"

## See also

[`shz_xmtrx_init_rotation`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation/)


---
# shz_xmtrx_init_rotation_quat

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_quat/

```c
void shz_xmtrx_init_rotation_quat(shz_quat_t q) SHZ_NOEXCEPT;
```

Initializes XMTRX to a 3D rotation matrix with its orientation given by a quaternion.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `q` | `shz_quat_t` |  |

## Returns

Nothing (`void`).

## Warnings

- This routine clobbers any previous XMTRX contents.
- This routine is out-of-line.

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_rotation_quat`](https://sh4zam.com/api/cpp/xmtrx/#init_rotation_quat)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:395`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L395)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_rotation_x

Source: 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

```c
SHZ_INLINE void shz_xmtrx_init_rotation_x(float x) SHZ_NOEXCEPT;
```

Initializes XMTRX to be a 3D rotation matrix by `x` radians about the X axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_rotation_x`](https://sh4zam.com/api/cpp/xmtrx/#init_rotation_x)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:267`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L267)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_rotation_xyz

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_xyz/

```c
SHZ_INLINE void shz_xmtrx_init_rotation_xyz(float xAngle, float yAngle, float zAngle) SHZ_NOEXCEPT;
```

Initializes XMTRX to be a 3D X-Y-Z rotation matrix, with the corresponding angles given in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `xAngle` | `float` |  |
| `yAngle` | `float` |  |
| `zAngle` | `float` |  |

## Returns

Nothing (`void`).

## Notes

- The given angles are represented as Tait-Bryan angles, representing an extrinsic rotation.

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_rotation_xyz`](https://sh4zam.com/api/cpp/xmtrx/#init_rotation_xyz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:282`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L282)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"

## See also

[`shz_xmtrx_init_rotation_zyx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_zyx/), [`shz_xmtrx_init_rotation_yxz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_yxz/)


---
# shz_xmtrx_init_rotation_y

Source: 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

```c
SHZ_INLINE void shz_xmtrx_init_rotation_y(float y) SHZ_NOEXCEPT;
```

Initializes XMTRX to be a 3D rotation matrix by `y` radians about the Y axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `y` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_rotation_y`](https://sh4zam.com/api/cpp/xmtrx/#init_rotation_y)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:270`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L270)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_rotation_yxz

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_yxz/

```c
SHZ_INLINE void shz_xmtrx_init_rotation_yxz(float yAngle, float xAngle, float zAngle) SHZ_NOEXCEPT;
```

Initializes XMTRX to be a 3D Y-X-Z rotation matrix, with the corresponding angles given in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `yAngle` | `float` |  |
| `xAngle` | `float` |  |
| `zAngle` | `float` |  |

## Returns

Nothing (`void`).

## Notes

- The given angles are represented as Tait-Bryan angles, representing an extrinsic rotation.

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_rotation_yxz`](https://sh4zam.com/api/cpp/xmtrx/#init_rotation_yxz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:309`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L309)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"

## See also

[`shz_xmtrx_init_rotation_xyz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_xyz/)


---
# shz_xmtrx_init_rotation_z

Source: 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

```c
SHZ_INLINE void shz_xmtrx_init_rotation_z(float z) SHZ_NOEXCEPT;
```

Initializes XMTRX to be a 3D rotation matrix by `z` radians about the Z axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_rotation_z`](https://sh4zam.com/api/cpp/xmtrx/#init_rotation_z)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:273`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L273)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_rotation_zxy

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_zxy/

```c
SHZ_INLINE void shz_xmtrx_init_rotation_zxy(float zAngle, float xAngle, float yAngle) SHZ_NOEXCEPT;
```

Initializes XMTRX to be a 3D Z-X-Y rotation matrix, with the corresponding angles given in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `zAngle` | `float` |  |
| `xAngle` | `float` |  |
| `yAngle` | `float` |  |

## Returns

Nothing (`void`).

## Notes

- The given angles are represented as Tait-Bryan angles, representing an extrinsic rotation.

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_rotation_zxy`](https://sh4zam.com/api/cpp/xmtrx/#init_rotation_zxy)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:300`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L300)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"

## See also

[`shz_xmtrx_init_rotation_zyx`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_zyx/), [`shz_xmtrx_init_rotation_yxz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_yxz/)


---
# shz_xmtrx_init_rotation_zyx

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_zyx/

```c
SHZ_INLINE void shz_xmtrx_init_rotation_zyx(float zAngle, float yAngle, float xAngle) SHZ_NOEXCEPT;
```

Initializes XMTRX to be a 3D Z-Y-X rotation matrix, with the corresponding angles given in radians.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `zAngle` | `float` |  |
| `yAngle` | `float` |  |
| `xAngle` | `float` |  |

## Returns

Nothing (`void`).

## Notes

- The given angles are represented as Tait-Bryan angles, representing an extrinsic rotation.

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_rotation_zyx`](https://sh4zam.com/api/cpp/xmtrx/#init_rotation_zyx)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:291`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L291)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"

## See also

[`shz_xmtrx_init_rotation_xyz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_xyz/), [`shz_xmtrx_init_rotation_yxz`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_yxz/)


---
# shz_xmtrx_init_rotation

Source: 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

```c
SHZ_INLINE void shz_xmtrx_init_rotation(float angle, float xAxis, float yAxis, float zAxis) SHZ_NOEXCEPT;
```

Initializes XMTRX to a 3D rotation matrix of `angle` radians about the vector with the given components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `angle` | `float` |  |
| `xAxis` | `float` |  |
| `yAxis` | `float` |  |
| `zAxis` | `float` |  |

## Returns

Nothing (`void`).

## Notes

- This routine works similarly to glRotatef() applied to an identitiy matrix. The given axis will automatically be normalized internally.

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_rotation`](https://sh4zam.com/api/cpp/xmtrx/#init_rotation)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:318`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L318)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"

## See also

[`shz_xmtrx_init_rotation_dir`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_dir/)


---
# shz_xmtrx_init_scale

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_scale/

```c
SHZ_INLINE void shz_xmtrx_init_scale(float x, float y, float z) SHZ_NOEXCEPT;
```

Initializes XMTRX to be a 3D scale matrix with the given dimensions.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_scale`](https://sh4zam.com/api/cpp/xmtrx/#init_scale)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:264`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L264)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_screen

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_screen/

```c
SHZ_INLINE void shz_xmtrx_init_screen(float width, float height) SHZ_NOEXCEPT;
```

Initializes XMTRX to the viewport matrix with the given dimensions.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `width` | `float` |  |
| `height` | `float` |  |

## Returns

Nothing (`void`).

## Details

| fr\[n + 0\] | fr\[n + 4\] | fr\[n + 8\] | fr\[n + 12\] |
| --- | --- | --- | --- |
| w\*0.5f | 0.0f | 0.0f | w\*0.5f |
| 0.0f | -h\*0.5f | 0.0f | h\*0.5f |
| 0.0f | 0.0f | 1.0f | 0.0f |
| 0.0f | 0.0f | 0.0f | 1.0f |

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_screen`](https://sh4zam.com/api/cpp/xmtrx/#init_screen)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:364`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L364)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_symmetric_skew

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_symmetric_skew/

```c
SHZ_INLINE void shz_xmtrx_init_symmetric_skew(float x, float y, float z) SHZ_NOEXCEPT;
```

Initializes XMTRX to be the 3D symmetric skew matrix formed from the given vector components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_symmetric_skew`](https://sh4zam.com/api/cpp/xmtrx/#init_symmetric_skew)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:341`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L341)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_translation

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_translation/

```c
SHZ_INLINE void shz_xmtrx_init_translation(float x, float y, float z) SHZ_NOEXCEPT;
```

Initializes XMTRX to be a 3D translation matrix to the given coordinates.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_translation`](https://sh4zam.com/api/cpp/xmtrx/#init_translation)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:261`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L261)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_upper_triangular

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_upper_triangular/

```c
SHZ_INLINE void shz_xmtrx_init_upper_triangular(float col1, shz_vec2_t col2, shz_vec3_t col3, shz_vec4_t col4) SHZ_NOEXCEPT;
```

Initializes XMTRX to be an upper triangular matrix with the given column values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `col1` | `float` |  |
| `col2` | `shz_vec2_t` |  |
| `col3` | `shz_vec3_t` |  |
| `col4` | `shz_vec4_t` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_upper_triangular`](https://sh4zam.com/api/cpp/xmtrx/#init_upper_triangular)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:335`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L335)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_init_zero

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_init_zero/

```c
SHZ_INLINE void shz_xmtrx_init_zero(void) SHZ_NOEXCEPT;
```

Initializes XMTRX to contain the value of 0.0f for each element.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::init_zero`](https://sh4zam.com/api/cpp/xmtrx/#init_zero)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:252`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L252)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Initialization"


---
# shz_xmtrx_invert

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_invert/

```c
void shz_xmtrx_invert(void) SHZ_NOEXCEPT;
```

Inverts XMTRX in-place.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Details

Stores XMTRX to memory, computes the inverse via `shz_mat4x4_inverse()`, and reloads the result.

## Warnings

- This routine is out-of-line.

## Availability

- **C++ equivalent:** [`shz::xmtrx::invert`](https://sh4zam.com/api/cpp/xmtrx/#invert)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:854`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L854)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Miscellaneous"


---
# shz_xmtrx_load_2x2

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_2x2/

```c
SHZ_INLINE void shz_xmtrx_load_2x2(const shz_mat2x2_t* matrix) SHZ_NOEXCEPT;
```

Loads the given 2x2 matrix into XMTRX, initializing its remaining elements to identity.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat2x2_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:194`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L194)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_load_3x3

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x3/

```c
SHZ_INLINE void shz_xmtrx_load_3x3(const shz_mat3x3_t* matrix) SHZ_NOEXCEPT;
```

Loads the given 3x3 matrix into XMTRX, initalizing its remaining elements to identity.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat3x3_t *` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:188`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L188)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_load_3x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x4/

```c
SHZ_INLINE void shz_xmtrx_load_3x4(const shz_mat3x4_t* matrix) SHZ_NOEXCEPT;
```

Loads the given 3x4 matrix into XMTRX, initializing its remaining elements to identity.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat3x4_t *` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:151`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L151)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_load_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_4x4/

```c
SHZ_INLINE void shz_xmtrx_load_4x4(const shz_mat4x4_t* matrix) SHZ_NOEXCEPT;
```

Loads the given 4x4 matrix as XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:124`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L124)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_load_apply_3x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_3x4/

> Loads XMTRX with the result of applying matrix2 onto matrix1

```c
SHZ_INLINE void shz_xmtrx_load_apply_3x4(const shz_mat3x4_t* matrix1, const shz_mat3x4_t* matrix2) SHZ_NOEXCEPT;
```

Loads XMTRX with the result of applying `matrix2` onto `matrix1`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix1` | `const shz_mat3x4_t *` |  |
| `matrix2` | `const shz_mat3x4_t *` |  |

## Returns

Nothing (`void`).

## Details

This operation is equivalent to: [`shz_xmtrx_load_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x4/)(matrix1); [`shz_xmtrx_apply_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x4/)(matrix2);

However, it has been optimized and pipelined for performing the load and multiply in parallel.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:719`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L719)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Compound Operations"

## See also

[`shz_xmtrx_load_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x4/), [`shz_xmtrx_apply_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x4/), [`shz_xmtrx_load_apply_store_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_3x4/)


---
# shz_xmtrx_load_apply_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_4x4/

> Loads XMTRX with the result of applying matrix2 onto matrix1

```c
SHZ_INLINE void shz_xmtrx_load_apply_4x4(const shz_mat4x4_t* matrix1, const shz_mat4x4_t* matrix2) SHZ_NOEXCEPT;
```

Loads XMTRX with the result of applying `matrix2` onto `matrix1`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix1` | `const shz_mat4x4_t *` |  |
| `matrix2` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Details

This operation is equivalent to: [`shz_xmtrx_load_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_4x4/)(matrix1); [`shz_xmtrx_apply_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_4x4/)(matrix2);

However, it has been optimized and pipelined for performing the load and multiply in parallel.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:628`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L628)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Compound Operations"

## See also

[`shz_xmtrx_load_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_4x4/), [`shz_xmtrx_apply_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_4x4/), [`shz_xmtrx_load_apply_store_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_4x4/)


---
# shz_xmtrx_load_apply_store_3x3

Source: 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

```c
SHZ_INLINE void shz_xmtrx_load_apply_store_3x3(shz_mat3x3_t* out, const shz_mat3x3_t* matrix1, const shz_mat3x3_t* matrix2) SHZ_NOEXCEPT;
```

Loads XMTRX with the 3x3 result of applying `matrix2` onto `matrix1`, storing the result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `out` | `shz_mat3x3_t *` |  |
| `matrix1` | `const shz_mat3x3_t *` |  |
| `matrix2` | `const shz_mat3x3_t *` |  |

## Returns

Nothing (`void`).

## Details

This operation is equivalent to: [`shz_xmtrx_load_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x3/)(matrix1); [`shz_xmtrx_apply_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x3/)(matrix2); [`shz_xmtrx_store_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_3x3/)(out);

However, it has been optimized and pipelined for performing the loads, multiplies, and stores in parallel.

## Notes

- The resulting matrix does not get stored within XMTRX, despite it getting clobbered.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:756`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L756)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Compound Operations"

## See also

[`shz_xmtrx_load_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x3/), [`shz_xmtrx_apply_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x3/), [`shz_xmtrx_store_3x3`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_3x3/)


---
# shz_xmtrx_load_apply_store_3x4

Source: 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

```c
SHZ_INLINE void shz_xmtrx_load_apply_store_3x4(shz_mat3x4_t* out, const shz_mat3x4_t* matrix1, const shz_mat3x4_t* matrix2) SHZ_NOEXCEPT;
```

Loads XMTRX with the 3x4 result of applying `matrix2` onto `matrix1`, storing the result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `out` | `shz_mat3x4_t *` |  |
| `matrix1` | `const shz_mat3x4_t *` |  |
| `matrix2` | `const shz_mat3x4_t *` |  |

## Returns

Nothing (`void`).

## Details

This operation is equivalent to: [`shz_xmtrx_load_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x4/)(matrix1); [`shz_xmtrx_apply_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x4/)(matrix2); [`shz_xmtrx_store_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_3x4/)(out);

However, it has been optimized and pipelined for performing the loads, multiplies, and stores in parallel.

## Notes

- The resulting matrix does not get stored within XMTRX, despite it getting clobbered.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:737`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L737)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Compound Operations"

## See also

[`shz_xmtrx_load_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_3x4/), [`shz_xmtrx_apply_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_3x4/), [`shz_xmtrx_store_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_3x4/)


---
# shz_xmtrx_load_apply_store_4x4

Source: 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

```c
SHZ_INLINE void shz_xmtrx_load_apply_store_4x4(shz_mat4x4_t* out, const shz_mat4x4_t* matrix1, const shz_mat4x4_t* matrix2) SHZ_NOEXCEPT;
```

Loads XMTRX with the 4x4 result of applying `matrix2` onto `matrix1`, storing the result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `out` | `shz_mat4x4_t *` |  |
| `matrix1` | `const shz_mat4x4_t *` |  |
| `matrix2` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Details

This operation is equivalent to: [`shz_xmtrx_load_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_4x4/)(matrix1); [`shz_xmtrx_apply_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_4x4/)(matrix2); [`shz_xmtrx_store_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_4x4/)(out);

However, it has been optimized and pipelined for performing the loads, multiplies, and stores in parallel.

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:692`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L692)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Compound Operations"

## See also

[`shz_xmtrx_load_apply_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_4x4/), [`shz_xmtrx_load_apply_store_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_unaligned_4x4/)


---
# shz_xmtrx_load_apply_store_unaligned_4x4

Source: 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

```c
SHZ_INLINE void shz_xmtrx_load_apply_store_unaligned_4x4(float out[16], const float matrix1[16], const float matrix2[16]) SHZ_NOEXCEPT;
```

Loads XMTRX with the result of applying unaligned `matrix2` onto unaligned `matrix1`, storing the result.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `out` | `float [16]` |  |
| `matrix1` | `const float [16]` |  |
| `matrix2` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Details

This routine is equivalent to `shz_xmtrx_load_apply_store_4x4()`, except that the three operand matrices do not require 8-byte alignment and can simply be 16-element single-precision float arrays.

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:704`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L704)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Compound Operations"

## See also

[`shz_xmtrx_load_apply_store_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_store_4x4/)


---
# shz_xmtrx_load_apply_unaligned_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_unaligned_4x4/

> Loads XMTRX with the result of applying unaligned matrix2 onto matrix1

```c
SHZ_INLINE void shz_xmtrx_load_apply_unaligned_4x4(const float matrix1[16], const float matrix2[16]) SHZ_NOEXCEPT;
```

Loads XMTRX with the result of applying unaligned `matrix2` onto `matrix1`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix1` | `const float [16]` |  |
| `matrix2` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Details

This routine is equivalent to `shz_xmtrx_load_apply_4x4()`, except that the two operand matrices do not require 8-byte alignment and can simply be 16-element single-precision float arrays.

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:639`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L639)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Compound Operations"

## See also

[`shz_xmtrx_load_apply_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_4x4/)


---
# shz_xmtrx_load_cols_3x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_cols_3x4/

```c
SHZ_INLINE void shz_xmtrx_load_cols_3x4(const shz_vec3_t* c1, const shz_vec3_t* c2, const shz_vec3_t* c3, const shz_vec3_t* c4) SHZ_NOEXCEPT;
```

Loads the 3x4 matrix formed from the given 4 3D column vectors into XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c1` | `const shz_vec3_t *` |  |
| `c2` | `const shz_vec3_t *` |  |
| `c3` | `const shz_vec3_t *` |  |
| `c4` | `const shz_vec3_t *` |  |

## Returns

Nothing (`void`).

## Details

All remaining elements are initialized to identity matrix values.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:182`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L182)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"

## See also

[`shz_xmtrx_load_rows_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_rows_3x4/)


---
# shz_xmtrx_load_cols_4x3

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_cols_4x3/

```c
SHZ_INLINE void shz_xmtrx_load_cols_4x3(const shz_vec4_t* c1, const shz_vec4_t* c2, const shz_vec4_t* c3) SHZ_NOEXCEPT;
```

Loads the 3x4 matrix formed from the given 3 4D column vectors into XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c1` | `const shz_vec4_t *` |  |
| `c2` | `const shz_vec4_t *` |  |
| `c3` | `const shz_vec4_t *` |  |

## Returns

Nothing (`void`).

## Details

All remaining elements are initialized to identity matrix values.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:162`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L162)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"

## See also

[`shz_xmtrx_load_rows_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_rows_3x4/)


---
# shz_xmtrx_load_cols_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_cols_4x4/

```c
SHZ_INLINE void shz_xmtrx_load_cols_4x4(const shz_vec4_t* c1, const shz_vec4_t* c2, const shz_vec4_t* c3, const shz_vec4_t* c4) SHZ_NOEXCEPT;
```

Sets XMTRX equal to the 4x4 matrix created from the 4 given 4D column vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `c1` | `const shz_vec4_t *` |  |
| `c2` | `const shz_vec4_t *` |  |
| `c3` | `const shz_vec4_t *` |  |
| `c4` | `const shz_vec4_t *` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:133`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L133)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_load_rows_3x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_rows_3x4/

```c
SHZ_INLINE void shz_xmtrx_load_rows_3x4(const shz_vec4_t* r1, const shz_vec4_t* r2, const shz_vec4_t* r3) SHZ_NOEXCEPT;
```

Loads the 3x4 matrix formed from the given 3 4D row vectors into XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `r1` | `const shz_vec4_t *` |  |
| `r2` | `const shz_vec4_t *` |  |
| `r3` | `const shz_vec4_t *` |  |

## Returns

Nothing (`void`).

## Details

All remaining elements are initialized to identity matrix values.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:172`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L172)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"

## See also

[`shz_xmtrx_load_cols_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_cols_3x4/)


---
# shz_xmtrx_load_rows_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_rows_4x4/

```c
SHZ_INLINE void shz_xmtrx_load_rows_4x4(const shz_vec4_t* r1, const shz_vec4_t* r2, const shz_vec4_t* r3, const shz_vec4_t* r4) SHZ_NOEXCEPT;
```

Sets XMTRX equal to the 4x4 matrix created from the 4 given 4D row vectors.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `r1` | `const shz_vec4_t *` |  |
| `r2` | `const shz_vec4_t *` |  |
| `r3` | `const shz_vec4_t *` |  |
| `r4` | `const shz_vec4_t *` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:139`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L139)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_load_transpose_3x3

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_3x3/

```c
SHZ_INLINE void shz_xmtrx_load_transpose_3x3(const shz_mat3x3_t* matrix) SHZ_NOEXCEPT;
```

Loads the transpose of the given 3x3 matrix into XMTRX, initializing its remaining elements to identity.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat3x3_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:191`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L191)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_load_transpose_3x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_3x4/

```c
SHZ_INLINE void shz_xmtrx_load_transpose_3x4(const shz_mat3x4_t* matrix) SHZ_NOEXCEPT;
```

Loads XMTRX with the transpose of the given 3x4 matrix, initializing the bottom row to identity.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat3x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:154`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L154)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_load_transpose_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_4x4/

```c
SHZ_INLINE void shz_xmtrx_load_transpose_4x4(const shz_mat4x4_t* matrix) SHZ_NOEXCEPT;
```

Loads XMTRX with the transpose of the given 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:145`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L145)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_load_transpose_unaligned_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_transpose_unaligned_4x4/

```c
SHZ_INLINE void shz_xmtrx_load_transpose_unaligned_4x4(const float matrix[16]) SHZ_NOEXCEPT;
```

Loads XMTRX with the transpose of the 4x4 matrix created from the given unaligned array of 16 floats.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:148`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L148)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_load_unaligned_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_unaligned_4x4/

```c
SHZ_INLINE void shz_xmtrx_load_unaligned_4x4(const float matrix[16]) SHZ_NOEXCEPT;
```

Loads the given array of unaligned 16 float values as the 4x4 XMTRX matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const float [16]` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:130`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L130)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_load_wxyz_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_load_wxyz_4x4/

```c
SHZ_INLINE void shz_xmtrx_load_wxyz_4x4(const shz_mat4x4_t* matrix) SHZ_NOEXCEPT;
```

Loads the given 4x4 matrix as XMTRX, with the 4th column for translation being loaded as the first column.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_wxyz`: Register/column permutation so that `FTRV` yields W first (cycle 4 instead of 7), which helps perspective division. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::xmtrx::load_wxyz`](https://sh4zam.com/api/cpp/xmtrx/#load_wxyz)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:127`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L127)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Loading"


---
# shz_xmtrx_negate

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_negate/

```c
SHZ_INLINE void shz_xmtrx_negate(void) SHZ_NOEXCEPT;
```

Negates each element held within XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::negate`](https://sh4zam.com/api/cpp/xmtrx/#negate)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:836`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L836)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Miscellaneous"


---
# shz_xmtrx_read_col

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_read_col/

> Returns the values at the given column index, as a 4D vector

```c
SHZ_INLINE shz_vec4_t shz_xmtrx_read_col(unsigned int index) SHZ_NOEXCEPT;
```

Returns the values at the given column `index`, as a 4D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `index` | `unsigned int` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::xmtrx::read_col`](https://sh4zam.com/api/cpp/xmtrx/#read_col)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:102`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L102)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Accessors"


---
# shz_xmtrx_read_row

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_read_row/

> Returns the values at the the given row index, as a 4D vector

```c
SHZ_INLINE shz_vec4_t shz_xmtrx_read_row(unsigned int index) SHZ_NOEXCEPT;
```

Returns the values at the the given row `index`, as a 4D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `index` | `unsigned int` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** [`shz::xmtrx::read_row`](https://sh4zam.com/api/cpp/xmtrx/#read_row)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:99`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L99)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Accessors"


---
# shz_xmtrx_read

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_read/

```c
SHZ_INLINE float shz_xmtrx_read(shz_xmtrx_reg_t xf) SHZ_NOEXCEPT;
```

Returns the floating-point value held within the given XMTRX register.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `xf` | `shz_xmtrx_reg_t` |  |

## Returns

`float`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:93`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L93)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Accessors"


---
# shz_xmtrx_reg

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_reg/

```c
typedef enum shz_xmtrx_reg {
    SHZ_XMTRX_XF0,  //!< FP register `xf0`.
    SHZ_XMTRX_XF1,  //!< FP register `xf1`.
    SHZ_XMTRX_XF2,  //!< FP register `xf2`.
    SHZ_XMTRX_XF3,  //!< FP register `xf3`.
    SHZ_XMTRX_XF4,  //!< FP register `xf4`.
    SHZ_XMTRX_XF5,  //!< FP register `xf5`.
    SHZ_XMTRX_XF6,  //!< FP register `xf6`.
    SHZ_XMTRX_XF7,  //!< FP register `xf7`.
    SHZ_XMTRX_XF8,  //!< FP register `xf8`.
    SHZ_XMTRX_XF9,  //!< FP register `xf9`.
    SHZ_XMTRX_XF10, //!< FP register `xf10`.
    SHZ_XMTRX_XF11, //!< FP register `xf11`.
    SHZ_XMTRX_XF12, //!< FP register `xf12`.
    SHZ_XMTRX_XF13, //!< FP register `xf13`.
    SHZ_XMTRX_XF14, //!< FP register `xf14`.
    SHZ_XMTRX_XF15  //!< FP register `xf15`.
} shz_xmtrx_reg_t, shz_xmtrx_reg;
```

Registers comprising XMTRX, in the FPU back-bank.

## Values

- `SHZ_XMTRX_XF0`: FP register `xf0`.
- `SHZ_XMTRX_XF1`: FP register `xf1`.
- `SHZ_XMTRX_XF2`: FP register `xf2`.
- `SHZ_XMTRX_XF3`: FP register `xf3`.
- `SHZ_XMTRX_XF4`: FP register `xf4`.
- `SHZ_XMTRX_XF5`: FP register `xf5`.
- `SHZ_XMTRX_XF6`: FP register `xf6`.
- `SHZ_XMTRX_XF7`: FP register `xf7`.
- `SHZ_XMTRX_XF8`: FP register `xf8`.
- `SHZ_XMTRX_XF9`: FP register `xf9`.
- `SHZ_XMTRX_XF10`: FP register `xf10`.
- `SHZ_XMTRX_XF11`: FP register `xf11`.
- `SHZ_XMTRX_XF12`: FP register `xf12`.
- `SHZ_XMTRX_XF13`: FP register `xf13`.
- `SHZ_XMTRX_XF14`: FP register `xf14`.
- `SHZ_XMTRX_XF15`: FP register `xf15`.

## Availability

- **C++ equivalent:** none (usable from C++ as is)
- **Back-ends:** n/a (not a function)
- **Defined in:** [`sh4zam/shz_xmtrx.h:68`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L68)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Enumerations"


---
# shz_xmtrx_rotate_x

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_x/

```c
SHZ_INLINE void shz_xmtrx_rotate_x(float radians) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by a 3D rotation matrix about the X axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::rotate_x`](https://sh4zam.com/api/cpp/xmtrx/#rotate_x)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:574`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L574)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "GL Transformations"


---
# shz_xmtrx_rotate_xyz

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_xyz/

```c
SHZ_INLINE void shz_xmtrx_rotate_xyz(float xRadians, float yRadians, float zRadians) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by 3D rotation matrices about the X then Y then Z axes.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `xRadians` | `float` |  |
| `yRadians` | `float` |  |
| `zRadians` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::rotate_xyz`](https://sh4zam.com/api/cpp/xmtrx/#rotate_xyz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:583`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L583)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "GL Transformations"


---
# shz_xmtrx_rotate_y

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_y/

```c
SHZ_INLINE void shz_xmtrx_rotate_y(float radians) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by a 3D rotation matrix about the Y axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::rotate_y`](https://sh4zam.com/api/cpp/xmtrx/#rotate_y)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:577`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L577)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "GL Transformations"


---
# shz_xmtrx_rotate_yxz

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_yxz/

```c
SHZ_INLINE void shz_xmtrx_rotate_yxz(float yRadians, float xRadians, float zRadians) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by 3D rotation matrices about the Y then X then Z axes.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `yRadians` | `float` |  |
| `xRadians` | `float` |  |
| `zRadians` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::rotate_yxz`](https://sh4zam.com/api/cpp/xmtrx/#rotate_yxz)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:592`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L592)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "GL Transformations"


---
# shz_xmtrx_rotate_z

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_z/

```c
SHZ_INLINE void shz_xmtrx_rotate_z(float radians) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by a 3D rotation matrix about the Z axis.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::rotate_z`](https://sh4zam.com/api/cpp/xmtrx/#rotate_z)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:580`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L580)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "GL Transformations"


---
# shz_xmtrx_rotate_zxy

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_zxy/

```c
SHZ_INLINE void shz_xmtrx_rotate_zxy(float zRadians, float xRadians, float yRadians) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by 3D rotation matrices about the Z then X then Y axes.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `zRadians` | `float` |  |
| `xRadians` | `float` |  |
| `yRadians` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::rotate_zxy`](https://sh4zam.com/api/cpp/xmtrx/#rotate_zxy)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:589`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L589)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "GL Transformations"


---
# shz_xmtrx_rotate_zyx

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate_zyx/

```c
SHZ_INLINE void shz_xmtrx_rotate_zyx(float zRadians, float yRadians, float xRadians) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by 3D rotation matrices about the Z then Y then X axes.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `zRadians` | `float` |  |
| `yRadians` | `float` |  |
| `xRadians` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::rotate_zyx`](https://sh4zam.com/api/cpp/xmtrx/#rotate_zyx)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:586`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L586)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "GL Transformations"


---
# shz_xmtrx_rotate

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_rotate/

```c
SHZ_INLINE void shz_xmtrx_rotate(float radians, float xAxis, float yAxis, float zAxis) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by the 3D rotation matrix formed by the given axis and angle (glRotatef equivalent).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `radians` | `float` |  |
| `xAxis` | `float` |  |
| `yAxis` | `float` |  |
| `zAxis` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::rotate`](https://sh4zam.com/api/cpp/xmtrx/#rotate)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:595`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L595)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "GL Transformations"


---
# shz_xmtrx_scale_reverse

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_scale_reverse/

```c
SHZ_INLINE void shz_xmtrx_scale_reverse(float x, float y, float z) SHZ_NOEXCEPT;
```

Pre-multiplies and accumulates XMTRX onto the 3D scaling matrix with the given components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_reverse`: Reversed multiplication order (pre-multiply instead of post-multiply). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::xmtrx::scale_reverse`](https://sh4zam.com/api/cpp/xmtrx/#scale_reverse)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:608`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L608)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Reverse GL Transformations"


---
# shz_xmtrx_scale

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_scale/

```c
SHZ_INLINE void shz_xmtrx_scale(float x, float y, float z) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by a 3D scaling matrix with the given components (glScalef() equivalent).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::scale`](https://sh4zam.com/api/cpp/xmtrx/#scale)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:571`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L571)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "GL Transformations"


---
# shz_xmtrx_set_scale

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_set_scale/

```c
SHZ_INLINE void shz_xmtrx_set_scale(float x, float y, float z) SHZ_NOEXCEPT;
```

Sets only the inner 3x3 submatrix of XMTRX to be a scaling matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::set_scale`](https://sh4zam.com/api/cpp/xmtrx/#set_scale)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:793`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L793)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Setters"


---
# shz_xmtrx_set_translation

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_set_translation/

```c
SHZ_INLINE void shz_xmtrx_set_translation(float x, float y, float z) SHZ_NOEXCEPT;
```

Sets only the translational components of XMTRX to the given values.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::set_translation`](https://sh4zam.com/api/cpp/xmtrx/#set_translation)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:790`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L790)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Setters"


---
# shz_xmtrx_store_2x2

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_store_2x2/

```c
SHZ_INLINE void shz_xmtrx_store_2x2(shz_mat2x2_t* matrix) SHZ_NOEXCEPT;
```

Stores the top-left 2x2 values currently held within XMTRX into the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `shz_mat2x2_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:228`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L228)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Storing"


---
# shz_xmtrx_store_3x3

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_store_3x3/

```c
SHZ_INLINE void shz_xmtrx_store_3x3(shz_mat3x3_t* matrix) SHZ_NOEXCEPT;
```

Stores the top-left 3x3 values currently held within XMTRX into the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `shz_mat3x3_t *` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:222`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L222)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Storing"


---
# shz_xmtrx_store_3x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_store_3x4/

```c
SHZ_INLINE void shz_xmtrx_store_3x4(shz_mat3x4_t* matrix) SHZ_NOEXCEPT;
```

Stores the top-left 3x4 values currently held within XMTRX into the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `shz_mat3x4_t *` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:216`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L216)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Storing"


---
# shz_xmtrx_store_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_store_4x4/

```c
SHZ_INLINE void shz_xmtrx_store_4x4(shz_mat4x4_t* matrix) SHZ_NOEXCEPT;
```

Stores the current values held within XMTRX into the given 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:204`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L204)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Storing"


---
# shz_xmtrx_store_transpose_3x3

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_3x3/

```c
SHZ_INLINE void shz_xmtrx_store_transpose_3x3(shz_mat3x3_t* matrix) SHZ_NOEXCEPT;
```

Stores the transpose of the top-left 3x3 values currently held within XMTRX into the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `shz_mat3x3_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:225`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L225)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Storing"


---
# shz_xmtrx_store_transpose_3x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_3x4/

```c
SHZ_INLINE void shz_xmtrx_store_transpose_3x4(shz_mat3x4_t* matrix) SHZ_NOEXCEPT;
```

Stores the transpose of the top-left 3x4 values currently held within XMTRX into the given matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `shz_mat3x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:219`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L219)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Storing"


---
# shz_xmtrx_store_transpose_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_4x4/

```c
SHZ_INLINE void shz_xmtrx_store_transpose_4x4(shz_mat4x4_t* matrix) SHZ_NOEXCEPT;
```

Stores the transpose of the current values held within XMTRX into the given 4x4 matrix.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:210`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L210)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Storing"


---
# shz_xmtrx_store_transpose_unaligned_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_store_transpose_unaligned_4x4/

```c
SHZ_INLINE void shz_xmtrx_store_transpose_unaligned_4x4(float matrix[16]) SHZ_NOEXCEPT;
```

Stores the transpose of the the current values held within XMTRX into the given 16-element float array.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `float [16]` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))
- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:213`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L213)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Storing"


---
# shz_xmtrx_store_unaligned_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_store_unaligned_4x4/

```c
SHZ_INLINE void shz_xmtrx_store_unaligned_4x4(float matrix[16]) SHZ_NOEXCEPT;
```

Stores the current values held within XMTRX into the given unaligned 16-float array.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `matrix` | `float [16]` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_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. ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:207`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L207)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Storing"


---
# shz_xmtrx_sub_4x4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_sub_4x4/

> Subtracts each element within mat from each element within XMTRX, storing the result in XMTRX

```c
SHZ_INLINE void shz_xmtrx_sub_4x4(const shz_mat4x4_t* mat) SHZ_NOEXCEPT;
```

Subtracts each element within `mat` from each element within XMTRX, storing the result in XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `mat` | `const shz_mat4x4_t *` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `shz_mat4x4_t` and `shz_mat2x2_t` arguments must be 8-byte aligned. Unaligned data goes through the `float[16]` parameters of the `_unaligned` routines.

## Availability

- **C++ equivalent:** [`shz::xmtrx::sub`](https://sh4zam.com/api/cpp/xmtrx/#sub)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:823`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L823)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Component-Wise Matrix Operations"


---
# shz_xmtrx_swap_cols

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_swap_cols/

```c
SHZ_INLINE void shz_xmtrx_swap_cols(unsigned int index1, unsigned int index2) SHZ_NOEXCEPT;
```

Swaps the values of the columns with the given indices.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `index1` | `unsigned int` |  |
| `index2` | `unsigned int` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::swap_cols`](https://sh4zam.com/api/cpp/xmtrx/#swap_cols)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:114`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L114)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Accessors"


---
# shz_xmtrx_swap_rows

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_swap_rows/

```c
SHZ_INLINE void shz_xmtrx_swap_rows(unsigned int index1, unsigned int index2) SHZ_NOEXCEPT;
```

Swaps the values of the rows with the given indices.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `index1` | `unsigned int` |  |
| `index2` | `unsigned int` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::swap_rows`](https://sh4zam.com/api/cpp/xmtrx/#swap_rows)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:111`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L111)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Accessors"


---
# shz_xmtrx_to_quat

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_to_quat/

```c
shz_quat_t shz_xmtrx_to_quat(void) SHZ_NOEXCEPT;
```

Constructs a quaternion from the 3D rotation matrix within XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

`shz_quat_t`

## Availability

- **C++ equivalent:** [`shz::xmtrx::to_quat`](https://sh4zam.com/api/cpp/xmtrx/#to_quat)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:842`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L842)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Miscellaneous"


---
# shz_xmtrx_transform_point2

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_point2/

> Returns the 2D point that is the result of transforming pt by XMTRX

```c
SHZ_INLINE shz_vec2_t shz_xmtrx_transform_point2(shz_vec2_t pt) SHZ_NOEXCEPT;
```

Returns the 2D point that is the result of transforming `pt` by XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `pt` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:777`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L777)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Transformations"


---
# shz_xmtrx_transform_point3

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_point3/

> Returns the 3D point that is the result of transforming pt by XMTRX

```c
SHZ_INLINE shz_vec3_t shz_xmtrx_transform_point3(shz_vec3_t pt) SHZ_NOEXCEPT;
```

Returns the 3D point that is the result of transforming `pt` by XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `pt` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:780`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L780)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Transformations"


---
# shz_xmtrx_transform_vec2

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec2/

> Returns the 2D vector that is the result of transforming vec by XMTRX

```c
SHZ_INLINE shz_vec2_t shz_xmtrx_transform_vec2(shz_vec2_t vec) SHZ_NOEXCEPT;
```

Returns the 2D vector that is the result of transforming `vec` by XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec2_t` |  |

## Returns

`shz_vec2_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:774`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L774)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Transformations"


---
# shz_xmtrx_transform_vec3

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec3/

> Returns the 3D vector that is the result of transforming vec by XMTRX

```c
SHZ_INLINE shz_vec3_t shz_xmtrx_transform_vec3(shz_vec3_t vec) SHZ_NOEXCEPT;
```

Returns the 3D vector that is the result of transforming `vec` by XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec3_t` |  |

## Returns

`shz_vec3_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: shared C implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:771`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L771)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Transformations"


---
# shz_xmtrx_transform_vec4

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec4/

> Returns the 4D vector that is the result of transforming vec by XMTRX

```c
SHZ_INLINE shz_vec4_t shz_xmtrx_transform_vec4(shz_vec4_t vec) SHZ_NOEXCEPT;
```

Returns the 4D vector that is the result of transforming `vec` by XMTRX.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `vec` | `shz_vec4_t` |  |

## Returns

`shz_vec4_t`

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:768`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L768)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Transformations"


---
# shz_xmtrx_translate_reverse

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_translate_reverse/

```c
SHZ_INLINE void shz_xmtrx_translate_reverse(float x, float y, float z) SHZ_NOEXCEPT;
```

Pre-multiplies and accumulates XMTRX onto the 3D translation matrix with the given components.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_reverse`: Reversed multiplication order (pre-multiply instead of post-multiply). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::xmtrx::translate_reverse`](https://sh4zam.com/api/cpp/xmtrx/#translate_reverse)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:605`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L605)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Reverse GL Transformations"


---
# shz_xmtrx_translate

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_translate/

```c
SHZ_INLINE void shz_xmtrx_translate(float x, float y, float z) SHZ_NOEXCEPT;
```

Multiplies and accumulates XMTRX by a 3D translation matrix with the given components (glTranslatef() equivalent).

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `x` | `float` |  |
| `y` | `float` |  |
| `z` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::translate`](https://sh4zam.com/api/cpp/xmtrx/#translate)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:568`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L568)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "GL Transformations"


---
# shz_xmtrx_transpose

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_transpose/

```c
SHZ_INLINE void shz_xmtrx_transpose(void) SHZ_NOEXCEPT;
```

Transposes the elements within XMTRX, in-place.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `` | `void` |  |

## Returns

Nothing (`void`).

## Naming and requirements

- `_transpose`: Operates with the transposed matrix (row-major input, or inverse-rotation use). ([Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/))

## Availability

- **C++ equivalent:** [`shz::xmtrx::transpose`](https://sh4zam.com/api/cpp/xmtrx/#transpose)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:833`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L833)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Miscellaneous"


---
# shz_xmtrx_write_col

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_write_col/

> Sets the values at the given column index to the given 4D vector

```c
SHZ_INLINE void shz_xmtrx_write_col(unsigned int index, shz_vec4_t vector) SHZ_NOEXCEPT;
```

Sets the values at the given column `index` to the given 4D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `index` | `unsigned int` |  |
| `vector` | `shz_vec4_t` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::write_col`](https://sh4zam.com/api/cpp/xmtrx/#write_col)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:108`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L108)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Accessors"


---
# shz_xmtrx_write_row

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_write_row/

> Sets the values at the given row index to the given 4D vector

```c
SHZ_INLINE void shz_xmtrx_write_row(unsigned int index, shz_vec4_t vector) SHZ_NOEXCEPT;
```

Sets the values at the given row `index` to the given 4D vector.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `index` | `unsigned int` |  |
| `vector` | `shz_vec4_t` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** [`shz::xmtrx::write_row`](https://sh4zam.com/api/cpp/xmtrx/#write_row)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:105`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L105)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Accessors"


---
# shz_xmtrx_write

Source: https://sh4zam.com/api/xmtrx/shz_xmtrx_write/

> Sets the floating-point value held within the given XMTRX register to value

```c
SHZ_INLINE void shz_xmtrx_write(shz_xmtrx_reg_t xf, float value) SHZ_NOEXCEPT;
```

Sets the floating-point value held within the given XMTRX register to `value`.

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `xf` | `shz_xmtrx_reg_t` |  |
| `value` | `float` |  |

## Returns

Nothing (`void`).

## Availability

- **C++ equivalent:** none (call the C function from C++)
- **Type-generic form:** none
- **Back-ends:** SH4: dedicated SH4 implementation · SW: portable C · SPU: shared C implementation
- **Defined in:** [`sh4zam/shz_xmtrx.h:96`](https://github.com/gyrovorbis/sh4zam/blob/ba1e30c88d49df0311870b229e1dd860ef26c477/include/sh4zam/shz_xmtrx.h#L96)
- **Module:** [XMTRX](https://sh4zam.com/api/xmtrx/), section "Accessors"


---
# Changelog

Source: https://sh4zam.com/changelog/

> SH4ZAM release notes - v0.9.1, v0.9.0 and earlier

Release notes summarized from the upstream tags and release commits. The full history is on [GitHub](https://github.com/gyrovorbis/sh4zam/commits/master); tagged releases are listed under [tags](https://github.com/gyrovorbis/sh4zam/tags).

## Since v0.9.1 (unreleased)

- Initial Cell Broadband Engine SPU back-end (`SHZ_BACKEND=SHZ_SPU`), vector routines only, added to CMake and to `SHZ_TLS_MODEL` auto-detection.
- `shz_vec_inv_sqrtf()` and `shz_vec_sqrtf()` added to the type-generic routines and the C++ wrappers.
- XMTRX, `shz_fmodf()` and `shz_memcpyN()` bug fixes; fixes to `load_apply_store_4x4` and `store_aligned32_4x4`.
- Build fixes for the KOS + SH toolchain stable versions and for Clang.

## v0.9.1 (2026-09-25): XMTRX gainz, bug fixes, SW back-end on SH4

- **CMake:** a configuration option chooses the back-end rather than deciding by architecture. The software back-end is now built for all targets, so a Dreamcast project can switch between the accelerated and software back-ends without rebuilding `libsh4zam.a`.
- **Makefile:** `SHZ_BACKEND` variable to pick the SW or SH4 back-end.
- **XMTRX:** faster SH4 versions of `load_transpose_3x3`, `load_2x2`, `store_3x3`, `store_transpose_3x3`, `init_one`, `init_rotation_x/y/z`, `apply_translation`, `apply_scale`, `apply_rotation_x` and `init_screen`. Software back-end fixes in `apply_3x3`, `apply_transpose_3x3`, `apply_rotation_x/y/z`, `apply_rotation`, `apply_rotation_quat` and `rotate`. New C++ wrappers for loading, storing and applying 2x2 and 3x3 matrices.
- **Memory:** `shz_sq_memcpy32()` and `shz_sq_memcpy32_1()` software versions now work on real Dreamcast store queues.
- **cdefs:** `SHZ_TARGET` is decoupled from `SHZ_BACKEND`, since any target can use either back-end; every major architecture is auto-detected as a target. `-m4` and `-m4-double-only` SH4 builds are supported (with the software back-end).
- **Tests:** benchmark gainz reported for the SW back-end too; coverage for every newly wrapped C++ routine and every routine that had a bug.

## v0.9.0 (2026-09-22): XMTRX 3x4 API expansion

- XMTRX 3x4 API for C and C++ on both back-ends: `shz_xmtrx_load_transpose_3x4()`, `shz_xmtrx_store_transpose_3x4()`, `shz_xmtrx_apply_transpose_3x4()`, `shz_xmtrx_apply_reverse_3x4()`, `shz_xmtrx_apply_reverse_transpose_3x4()` and the fused `shz_xmtrx_load_apply_3x4()`.
- The C++ API covers the whole 3x4 family.
- Faster SH4 `shz_xmtrx_get_scale()`, `shz_mat4x4_get_scale()` (also fixing a real bug for non-affine matrices) and `shz_mat4x4_transform_vec3()`, which is now hand-written `FIPR` assembly.
- More stable benchmark harness.

## v0.8.1 (2026-09-20)

- One-off rotations of a single 3D vector about the X, Y and Z axes: `shz_vec3_rotate_x()`, `shz_vec3_rotate_y()`, `shz_vec3_rotate_z()` (and `shz::vec3::rotate_x()` etc.), faster than going through XMTRX for a single rotation.
- Resources page additions, including the deep-dive into `FSCA`, `FSRRA`, `FTRV` and `FIPR`.

## v0.8.0 (2026-08-18)

"We're WAY overdue for a minor release." Lots of new features, many bug fixes for both back-ends, and no known regressions. Upstream recommends it as a stable tag to stay on before the 1.0 API.

## v0.7.0 (2026-05-24)

Fix for software back-end unit test builds.

## Related

- [Contributing](https://sh4zam.com/contributing/)
- [Back-ends](https://sh4zam.com/concepts/backends/)


---
# Cheatsheet

Source: https://sh4zam.com/cheatsheet/

> The whole SH4ZAM C API on one page: every symbol with its signature and a one-line description

Every public SH4ZAM 0.9.1 symbol on one page. Conventions: column-major matrices, quaternions stored `<W, X, Y, Z>`, radians by default, single-precision `float` only. C++ names drop the `shz_` prefix and live in `namespace shz`; see the [C++ API](https://sh4zam.com/api/cpp/).

## Scalar

`#include <sh4zam/shz_scalar.h>` · [module page](https://sh4zam.com/api/scalar/)

### Scalar: Comparisons

- [`shz_fminf`](https://sh4zam.com/api/scalar/shz_fminf/): `float shz_fminf(float a, float b)` Returns the minimum value of two given floats.
- [`shz_fmaxf`](https://sh4zam.com/api/scalar/shz_fmaxf/): `float shz_fmaxf(float a, float b)` Returns the maximum value of two given floats.
- [`shz_equalf`](https://sh4zam.com/api/scalar/shz_equalf/): `bool shz_equalf(float a, float b)` Checks for equality based on EITHER the absolute tolerance or relative tolerance, using `SHZ_FLT_EPSILON`.
- [`shz_equalf_abs`](https://sh4zam.com/api/scalar/shz_equalf_abs/): `bool shz_equalf_abs(float a, float b)` Checks for equality based on the absolute tolerance using `SHZ_FLT_EPSILON`.
- [`shz_equalf_rel`](https://sh4zam.com/api/scalar/shz_equalf_rel/): `bool shz_equalf_rel(float a, float b)` Checks for equality based on the relative tolerance using `SHZ_FLT_EPSILON`.

### Scalar: Rounding

- [`shz_floorf`](https://sh4zam.com/api/scalar/shz_floorf/): `float shz_floorf(float x)` Replacement for the \<math.h> routine, floorf().
- [`shz_ceilf`](https://sh4zam.com/api/scalar/shz_ceilf/): `float shz_ceilf(float x)` Replacement for the \<math.h> routine, ceilf().
- [`shz_roundf`](https://sh4zam.com/api/scalar/shz_roundf/): `float shz_roundf(float x)` Replacement for the \<math.h> routine, roundf().
- [`shz_truncf`](https://sh4zam.com/api/scalar/shz_truncf/): `float shz_truncf(float x)` Replacement for the \<math.h> routine, truncf().
- [`shz_remainderf`](https://sh4zam.com/api/scalar/shz_remainderf/): `float shz_remainderf(float num, float denom)` Replacement for the \<math.h> routine, remainderf().
- [`shz_fmodf`](https://sh4zam.com/api/scalar/shz_fmodf/): `float shz_fmodf(float num, float denom)` Replacement for the \<math.h> routine, fmodf().
- [`shz_remquof`](https://sh4zam.com/api/scalar/shz_remquof/): `float shz_remquof(float num, float denom, float* quot)` (Sorta) Replacement for the \<math.h> routine, remquof().

### Scalar: Mapping

- [`shz_clampf`](https://sh4zam.com/api/scalar/shz_clampf/): `float shz_clampf(float value, float min, float max)` Clamps a floating-point value by the given `min` and `max` values.
- [`shz_normalizef`](https://sh4zam.com/api/scalar/shz_normalizef/): `float shz_normalizef(float current, float from, float to)` Maps a value within the given range `from` to `to`, to be within the range of `0.0f += 1.0f`.
- [`shz_normalizef_fsrra`](https://sh4zam.com/api/scalar/shz_normalizef_fsrra/): `float shz_normalizef_fsrra(float current, float from, float to)` Maps a value within the given range `from` to `to`, to be within the range of `0.0f + 1.0f` more quickly, provided `to` - `from` is a positive difference.
- [`shz_remapf`](https://sh4zam.com/api/scalar/shz_remapf/): `float shz_remapf(float value, float inputStart, float inputEnd, float outputStart, float outputEnd)` Maps a value within the given range `inputStart` to `inputEnd`, to be within the range of `outputStart` to `outputEnd`.
- [`shz_remapf_fsrra`](https://sh4zam.com/api/scalar/shz_remapf_fsrra/): `float shz_remapf_fsrra(float value, float inputStart, float inputEnd, float outputStart, float outputEnd)` Maps a value within the given range `inputStart` to `inputEnd`, to be within the range of `outputStart` to `outputEnd` more quickly, provided the `outputEnd` - `outputStart` is a positive difference.
- [`shz_wrapf`](https://sh4zam.com/api/scalar/shz_wrapf/): `float shz_wrapf(float value, float min, float max)` Wraps the given `value` back to be within the range of `min` to `max`.
- [`shz_wrapf_fsrra`](https://sh4zam.com/api/scalar/shz_wrapf_fsrra/): `float shz_wrapf_fsrra(float value, float min, float max)` Wraps the given `value` back to be within the range of `min` to `max` more quickly, provided `max` - `min` is a positive difference.
- [`shz_fractf`](https://sh4zam.com/api/scalar/shz_fractf/): `float shz_fractf(float x)` Returns the fractional part of `x`, equivalent to GLSL `fract()`.
- [`shz_signf`](https://sh4zam.com/api/scalar/shz_signf/): `float shz_signf(float x)` Returns -1.0f if `x` \< 0, 0.0f if `x` == 0, or 1.0f if `x` > 0.
- [`shz_saturatef`](https://sh4zam.com/api/scalar/shz_saturatef/): `float shz_saturatef(float x)` Clamps `x` to the range \[0.0f, 1.0f\].

### Scalar: Miscellaneous

- [`shz_fabsf`](https://sh4zam.com/api/scalar/shz_fabsf/): `float shz_fabsf(float x)` Replacement for the \<math.h> routine, fabsf().
- [`shz_copysignf`](https://sh4zam.com/api/scalar/shz_copysignf/): `float shz_copysignf(float x, float y)` Replacement for the \<math.h> routine, copysignf().
- [`shz_fmaf`](https://sh4zam.com/api/scalar/shz_fmaf/): `float shz_fmaf(float a, float b, float c)` Replacement for the \<math.h> routine, fmaf().
- [`shz_fdimf`](https://sh4zam.com/api/scalar/shz_fdimf/): `float shz_fdimf(float x, float y)` Replacement for the \<math.h> routine, fdimf(),.
- [`shz_hypotf`](https://sh4zam.com/api/scalar/shz_hypotf/): `float shz_hypotf(float x, float y)` Replacement for the \<math.h> routine, hypotf().
- [`shz_cbrtf`](https://sh4zam.com/api/scalar/shz_cbrtf/): `float shz_cbrtf(float x)` Replacement for the \<math.h> routine, cbrtf().
- [`shz_lerpf`](https://sh4zam.com/api/scalar/shz_lerpf/): `float shz_lerpf(float a, float b, float t)` Returns a value that is linearly interpolated between `a` and `b` by the given ratio, `t`.
- [`shz_barycentric_lerpf`](https://sh4zam.com/api/scalar/shz_barycentric_lerpf/): `float shz_barycentric_lerpf(float a, float b, float c, float u, float v)` Returns a value that is barycentrically interpolated between `a`, `b`, and `c` using the given barycentric coordinates, `u` and `v`.
- [`shz_quadratic_roots`](https://sh4zam.com/api/scalar/shz_quadratic_roots/): `bool shz_quadratic_roots(float a, float b, float c, float* root1, float* root2)` Uses the quadratic formula with the given coefficients to solve for the two roots, returning `true` if any real roots exist, and `false` if the roots are only imaginary.
- [`shz_randf`](https://sh4zam.com/api/scalar/shz_randf/): `float shz_randf(int* seed)` Returns a random floating-point number between `0.0f` and `1.0f`, using and updating the given seed.
- [`shz_randf_range`](https://sh4zam.com/api/scalar/shz_randf_range/): `float shz_randf_range(int* seed, float min, float max)` Returns a random floating-point number between `min` and `max`, using and updating the given seed.
- [`shz_stepf`](https://sh4zam.com/api/scalar/shz_stepf/): `float shz_stepf(float x, float edge)` returns 0.0f if x \< edge, otherwise 1.0f
- [`shz_smoothstepf`](https://sh4zam.com/api/scalar/shz_smoothstepf/): `float shz_smoothstepf(float x, float edge0, float edge1)` Returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. edge0 must be less than edge1 or result is undefined.
- [`shz_smoothstepf_safe`](https://sh4zam.com/api/scalar/shz_smoothstepf_safe/): `float shz_smoothstepf_safe(float x, float edge0, float edge1)` Returns 0.0f at/below edge0, 1.0f at/above edge1, smoothly varying in-between. Accepts inverse edges.

### Scalar: FSRRA

- [`shz_inv_sqrtf_fsrra`](https://sh4zam.com/api/scalar/shz_inv_sqrtf_fsrra/): `float shz_inv_sqrtf_fsrra(float x)` Calculates 1.0f/sqrtf( `x`), using a fast approximation.
- [`shz_inv_sqrtf`](https://sh4zam.com/api/scalar/shz_inv_sqrtf/): `float shz_inv_sqrtf(float x)` Calculates 1.0f/sqrtf( `x` ), using a fast approximation, while safely protecting against division-by-zero.
- [`shz_sqrtf_fsrra`](https://sh4zam.com/api/scalar/shz_sqrtf_fsrra/): `float shz_sqrtf_fsrra(float x)` Returns the fast approximate square root of the given value, `x`.
- [`shz_sqrtf`](https://sh4zam.com/api/scalar/shz_sqrtf/): `float shz_sqrtf(float x)` Returns the fast approximate square root of the given value, `x`, safely returning `0.0f` is `x` == `0.0f`.
- [`shz_invf_fsrra`](https://sh4zam.com/api/scalar/shz_invf_fsrra/): `float shz_invf_fsrra(float x)` Takes the inverse of `x` using a very fast approximation, returning a positive result.
- [`shz_invf`](https://sh4zam.com/api/scalar/shz_invf/): `float shz_invf(float x)` Takes the inverse of `x` using a slighty faster approximation than doing a full division, safely handling negative values.
- [`shz_divf_fsrra`](https://sh4zam.com/api/scalar/shz_divf_fsrra/): `float shz_divf_fsrra(float num, float denom)` Divides `num` by `denom` using a very fast approximation, which requires `denom` be a positive value.
- [`shz_divf`](https://sh4zam.com/api/scalar/shz_divf/): `float shz_divf(float num, float denom)` Divides `num` by `denom` using a slightly faster approximation, allowing `denom` to be negative.

### Scalar: FIPR

- [`shz_dot6f`](https://sh4zam.com/api/scalar/shz_dot6f/): `float shz_dot6f(float x1, float y1, float z1, float x2, float y2, float z2)` Takes two sets of 3D vectors as 3 floats and calculates their dot product using an approximation.
- [`shz_dot8f`](https://sh4zam.com/api/scalar/shz_dot8f/): `float shz_dot8f(float x1, float y1, float z1, float w1, float x2, float y2, float z2, float w2)` Takes two sets of 4D vectors as 4 floats and calculates their dot product using an approximation.
- [`shz_mag_sqr3f`](https://sh4zam.com/api/scalar/shz_mag_sqr3f/): `float shz_mag_sqr3f(float x, float y, float z)` Takes a 3D vector as 3 floats and calculates its squared magnitude using a fast approximation.
- [`shz_mag_sqr4f`](https://sh4zam.com/api/scalar/shz_mag_sqr4f/): `float shz_mag_sqr4f(float x, float y, float z, float w)` Takes a 4D vector as 4 floats and calculates its squared magnitude using a fast approximation.

### Scalar: Transcendental

- [`shz_pow2f`](https://sh4zam.com/api/scalar/shz_pow2f/): `float shz_pow2f(float p)` Fast approximation for raising 2 to a floating-point power.
- [`shz_powf`](https://sh4zam.com/api/scalar/shz_powf/): `float shz_powf(float x, float p)` Fast approximation for C's powf().
- [`shz_pow10f`](https://sh4zam.com/api/scalar/shz_pow10f/): `float shz_pow10f(float x)` Fast approximation of POSIX's pow10f().
- [`shz_log2f`](https://sh4zam.com/api/scalar/shz_log2f/): `float shz_log2f(float x)` Fast approximation for C's log2f().
- [`shz_logf`](https://sh4zam.com/api/scalar/shz_logf/): `float shz_logf(float x)` Fast approximation for C's logf().
- [`shz_log10f`](https://sh4zam.com/api/scalar/shz_log10f/): `float shz_log10f(float x)` Fast approximation for C's log10f().
- [`shz_expf`](https://sh4zam.com/api/scalar/shz_expf/): `float shz_expf(float p)` Fast approximation for C's expf().

### Scalar: Macros

- [`SHZ_FLT_EPSILON`](https://sh4zam.com/api/scalar/SHZ_FLT_EPSILON/): `#define SHZ_FLT_EPSILON 0.01f` Floating-point epsilon used with inexact FP-based comparisons.

## Trigonometry

`#include <sh4zam/shz_trig.h>` · [module page](https://sh4zam.com/api/trig/)

### Trigonometry: Sin/Cos Pairs

- [`shz_sincosu16`](https://sh4zam.com/api/trig/shz_sincosu16/): `shz_sincos_t shz_sincosu16(uint16_t radians16)` Returns sinf()/cosf() pairs for the given unsigned 16-bit angle in radians.
- [`shz_sincosf`](https://sh4zam.com/api/trig/shz_sincosf/): `shz_sincos_t shz_sincosf(float radians)` Returns sinf()/cosf() pairs for the given floating-point angle in radians.
- [`shz_sincosf_deg`](https://sh4zam.com/api/trig/shz_sincosf_deg/): `shz_sincos_t shz_sincosf_deg(float degrees)` Returns sinf/cosf() pairs for the given floating-point angle in degrees.
- [`shz_sincos_tanf`](https://sh4zam.com/api/trig/shz_sincos_tanf/): `float shz_sincos_tanf(shz_sincos_t sincos)` Returns tanf() from the given pre-computed `sincos` pair.
- [`shz_sincos_secf`](https://sh4zam.com/api/trig/shz_sincos_secf/): `float shz_sincos_secf(shz_sincos_t sincos)` Returns the floating-point secant (1.0f / cosf(x)) from the given pre-computed `sincos` pair.
- [`shz_sincos_cscf`](https://sh4zam.com/api/trig/shz_sincos_cscf/): `float shz_sincos_cscf(shz_sincos_t sincos)` Returns the floating-point cosecant (1.0f / sinf(x)) from the given pre-computed `sincos` pair.
- [`shz_sincos_cotf`](https://sh4zam.com/api/trig/shz_sincos_cotf/): `float shz_sincos_cotf(shz_sincos_t sincos)` Returns the floating-point cotangent (1.0f / tanf(x)) from the given pre-computed `sincos` pair.

### Trigonometry: Independent Functions

- [`shz_sinf`](https://sh4zam.com/api/trig/shz_sinf/): `float shz_sinf(float radians)` One-off routine for returning only sinf() from an angle in radians.
- [`shz_sinf_deg`](https://sh4zam.com/api/trig/shz_sinf_deg/): `float shz_sinf_deg(float degrees)` One-off routine for returning only sinf() from an angle in degrees.
- [`shz_cosf`](https://sh4zam.com/api/trig/shz_cosf/): `float shz_cosf(float radians)` One-off routine for returning only cosf() from an angle in radians.
- [`shz_cosf_deg`](https://sh4zam.com/api/trig/shz_cosf_deg/): `float shz_cosf_deg(float degrees)` One-off routine for returning only cosf() from an angle in degrees.
- [`shz_tanf`](https://sh4zam.com/api/trig/shz_tanf/): `float shz_tanf(float radians)` One-off routine for returning only tanf() from an angle in radians.
- [`shz_tanf_deg`](https://sh4zam.com/api/trig/shz_tanf_deg/): `float shz_tanf_deg(float degrees)` One-off routine for returning only tanf() from an angle in degrees.
- [`shz_secf`](https://sh4zam.com/api/trig/shz_secf/): `float shz_secf(float radians)` One-off routine for returning only secant (1 / cos(x)) from an angle in radians.
- [`shz_secf_deg`](https://sh4zam.com/api/trig/shz_secf_deg/): `float shz_secf_deg(float degrees)` One-off routine for returning only secant (1 / cos(x)) from an angle in degrees.
- [`shz_cscf`](https://sh4zam.com/api/trig/shz_cscf/): `float shz_cscf(float radians)` One-off routine for returning only cosecant (1 / sin(x)) from an angle in radians.
- [`shz_cscf_deg`](https://sh4zam.com/api/trig/shz_cscf_deg/): `float shz_cscf_deg(float degrees)` One-off routine for returning only cosecant (1 / sin(x)) from an angle in degrees.
- [`shz_cotf`](https://sh4zam.com/api/trig/shz_cotf/): `float shz_cotf(float radians)` One-off routine for returning only cotangent (1 / tan(x)) from an angle in radians.
- [`shz_cotf_deg`](https://sh4zam.com/api/trig/shz_cotf_deg/): `float shz_cotf_deg(float degrees)` One-off routine for returning only cotangent (1 / cot(x)) from an angle in degrees.

### Trigonometry: Inverse Functions

- [`shz_asinf`](https://sh4zam.com/api/trig/shz_asinf/): `float shz_asinf(float x)` Fast arcsine approximation; equivalent to C's asinf().
- [`shz_acosf`](https://sh4zam.com/api/trig/shz_acosf/): `float shz_acosf(float x)` Fast arccosine approximation; equivalent to C's acosf().
- [`shz_atanf_unit`](https://sh4zam.com/api/trig/shz_atanf_unit/): `float shz_atanf_unit(float x)` Fast arctangent approximation for unit values between `0.0f` and `1.0f`.
- [`shz_atanf_q1`](https://sh4zam.com/api/trig/shz_atanf_q1/): `float shz_atanf_q1(float x)` Fast arctangent approximation for values lying within the first quadrant (`>= 0.0f`).
- [`shz_atanf`](https://sh4zam.com/api/trig/shz_atanf/): `float shz_atanf(float x)` Fast arctangent approximation; equvalent to C's atanf().
- [`shz_atan2f`](https://sh4zam.com/api/trig/shz_atan2f/): `float shz_atan2f(float y, float x)` Computes arctangent of `y / x`, using the signs of arguments to determine correct quadtrant. Equivalent to C's atan2f().
- [`shz_asecf`](https://sh4zam.com/api/trig/shz_asecf/): `float shz_asecf(float x)` Fast arcsecant/inverse secant approximation, taking units in radians.
- [`shz_acscf`](https://sh4zam.com/api/trig/shz_acscf/): `float shz_acscf(float x)` Fast arccosecant/inverse cosecant approximation; taking units in radians.
- [`shz_acotf`](https://sh4zam.com/api/trig/shz_acotf/): `float shz_acotf(float x)` Fast arccotangent/inverse cotangent approximation; taking units in radians.

### Trigonometry: Hyperbolic Functions

- [`shz_sinhf`](https://sh4zam.com/api/trig/shz_sinhf/): `float shz_sinhf(float x)` Fast hyperbolic sine function.
- [`shz_coshf`](https://sh4zam.com/api/trig/shz_coshf/): `float shz_coshf(float x)` Fast hyperbolic cosine function.
- [`shz_tanhf`](https://sh4zam.com/api/trig/shz_tanhf/): `float shz_tanhf(float x)` Fast hyperbolic tangent function.
- [`shz_cschf`](https://sh4zam.com/api/trig/shz_cschf/): `float shz_cschf(float x)` Fast hyperbolic cosecant function.
- [`shz_sechf`](https://sh4zam.com/api/trig/shz_sechf/): `float shz_sechf(float x)` Fast hyperbolic secant function.
- [`shz_cothf`](https://sh4zam.com/api/trig/shz_cothf/): `float shz_cothf(float x)` Fast hyperbolic cotangent function.

### Trigonometry: Inverse Hyperbolic Functions

- [`shz_asinhf`](https://sh4zam.com/api/trig/shz_asinhf/): `float shz_asinhf(float x)` Fast hyperbolic arcsine function.
- [`shz_acoshf`](https://sh4zam.com/api/trig/shz_acoshf/): `float shz_acoshf(float x)` Fast hyperbolic arccosine function.
- [`shz_atanhf`](https://sh4zam.com/api/trig/shz_atanhf/): `float shz_atanhf(float x)` Fast hyperbolic arctangent function.
- [`shz_acschf`](https://sh4zam.com/api/trig/shz_acschf/): `float shz_acschf(float x)` Fast hyperbolic arccosecant function.
- [`shz_asechf`](https://sh4zam.com/api/trig/shz_asechf/): `float shz_asechf(float x)` Fast hyperbolic arcsecant function.
- [`shz_acothf`](https://sh4zam.com/api/trig/shz_acothf/): `float shz_acothf(float x)` Fast hyperbolic arccotangent function.

### Trigonometry: Macros

- [`SHZ_F_PI`](https://sh4zam.com/api/trig/SHZ_F_PI/): `#define SHZ_F_PI 3.14159265359f` Single-precision floating-point PI approximation (do not use M_PI!).
- [`SHZ_F_TAU`](https://sh4zam.com/api/trig/SHZ_F_TAU/): `#define SHZ_F_TAU (SHZ_F_PI * 2.0f)` Single-precision FP PI approximation times 2.
- [`SHZ_F_PI_2`](https://sh4zam.com/api/trig/SHZ_F_PI_2/): `#define SHZ_F_PI_2 (SHZ_F_PI * 0.5f)` Single-precision FP PI approximation divided by 2.
- [`SHZ_F_PI_4`](https://sh4zam.com/api/trig/SHZ_F_PI_4/): `#define SHZ_F_PI_4 (SHZ_F_PI * 0.25f)` Single-precision FP PI approximation divided by 4.
- [`SHZ_FSCA_RAD_FACTOR`](https://sh4zam.com/api/trig/SHZ_FSCA_RAD_FACTOR/): `#define SHZ_FSCA_RAD_FACTOR 10430.37835f` Multiplicative factor for passing the FSCA instruction angles in radians.
- [`SHZ_FSCA_DEG_FACTOR`](https://sh4zam.com/api/trig/SHZ_FSCA_DEG_FACTOR/): `#define SHZ_FSCA_DEG_FACTOR 182.04444443f` Multiplicative factor for passing the FSCA instrution angles in degrees.
- [`SHZ_FSCA_ERROR_MAX`](https://sh4zam.com/api/trig/SHZ_FSCA_ERROR_MAX/): `#define SHZ_FSCA_ERROR_MAX 4.76837158e-7` Maximum FP error for FSCA instruction.
- [`SHZ_DEG_TO_RAD`](https://sh4zam.com/api/trig/SHZ_DEG_TO_RAD/): `#define SHZ_DEG_TO_RAD(deg) ((deg) * SHZ_F_PI / 180.0f)` Converts the given angle in degrees to radians.
- [`SHZ_RAD_TO_DEG`](https://sh4zam.com/api/trig/SHZ_RAD_TO_DEG/): `#define SHZ_RAD_TO_DEG(rad) ((rad) * 180.0f / SHZ_F_PI)` Converts the given angle in radians to degrees.

### Trigonometry: Types

- [`shz_sincos_t`](https://sh4zam.com/api/trig/shz_sincos_t/): `struct shz_sincos_t` Pair representing the sine and cosine of a given angle.
- [`shz_sincos`](https://sh4zam.com/api/trig/shz_sincos/): `typedef shz_sincos_t shz_sincos` Alternate C `shz_sincos_t` typedef for those who hate POSIX style.

## Vector

`#include <sh4zam/shz_vector.h>` · [module page](https://sh4zam.com/api/vector/)

### Vector: Adapters

- [`shz_vec2_deref`](https://sh4zam.com/api/vector/shz_vec2_deref/): `#define shz_vec2_deref(ptr) (*((SHZ_ALIASING shz_vec2_t*)(ptr)))` Dereferences the given pointer to a sequence of 2 floats as a `shz_vec2_t`.
- [`shz_vec3_deref`](https://sh4zam.com/api/vector/shz_vec3_deref/): `#define shz_vec3_deref(ptr) (*((SHZ_ALIASING shz_vec3_t*)(ptr)))` Dereferences the given pointer to a sequence of 3 floats as a `shz_vec3_t`.
- [`shz_vec4_deref`](https://sh4zam.com/api/vector/shz_vec4_deref/): `#define shz_vec4_deref(ptr) (*((SHZ_ALIASING shz_vec4_t*)(ptr)))` Dereferences the given pointer to a sequence of 4 floats as a `shz_vec4_t`.
- [`shz_vec2_from`](https://sh4zam.com/api/vector/shz_vec2_from/): `#define shz_vec2_from(value) SHZ_CONVERT(shz_vec2_t, value)` Converts the given `value` or expression to the equivalent 2D SH4ZAM vector value.
- [`shz_vec3_from`](https://sh4zam.com/api/vector/shz_vec3_from/): `#define shz_vec3_from(value) SHZ_CONVERT(shz_vec3_t, value)` Converts the given `value` or expression to the equivalent 3D SH4ZAM vector value.
- [`shz_vec4_from`](https://sh4zam.com/api/vector/shz_vec4_from/): `#define shz_vec4_from(value) SHZ_CONVERT(shz_vec4_t, value)` Converts the given `value` or expression to the equivalent 4D SH4ZAM vector value.
- [`shz_vec2_to`](https://sh4zam.com/api/vector/shz_vec2_to/): `#define shz_vec2_to(type, vector) SHZ_CONVERT(type, vector)` Converts the given 2D `vector` into a value of the given `type`.
- [`shz_vec3_to`](https://sh4zam.com/api/vector/shz_vec3_to/): `#define shz_vec3_to(type, vector) SHZ_CONVERT(type, vector)` Converts the given 3D `vector` into a value of the given `type`.
- [`shz_vec4_to`](https://sh4zam.com/api/vector/shz_vec4_to/): `#define shz_vec4_to(type, vector) SHZ_CONVERT(type, vector)` Converts the given 4D `vector` into a value of the given `type`.

### Vector: Type-Generic Routines

- [`shz_vec_abs`](https://sh4zam.com/api/vector/shz_vec_abs/): `#define shz_vec_abs(vec)` C type-generic vector absolute value.
- [`shz_vec_neg`](https://sh4zam.com/api/vector/shz_vec_neg/): `#define shz_vec_neg(vec)` C type-generic vector negation.
- [`shz_vec_inv`](https://sh4zam.com/api/vector/shz_vec_inv/): `#define shz_vec_inv(vec)` C type-generic vector inversion.
- [`shz_vec_max`](https://sh4zam.com/api/vector/shz_vec_max/): `#define shz_vec_max(vec)` C type-generic vector maximum value.
- [`shz_vec_min`](https://sh4zam.com/api/vector/shz_vec_min/): `#define shz_vec_min(vec)` C type-generic vector minimum value.
- [`shz_vec_clamp`](https://sh4zam.com/api/vector/shz_vec_clamp/): `#define shz_vec_clamp(vec, min, max)` C type-generic vector minimum value.
- [`shz_vec_equal`](https://sh4zam.com/api/vector/shz_vec_equal/): `#define shz_vec_equal(vec1, vec2)` C type-generic vector equals.
- [`shz_vec_add`](https://sh4zam.com/api/vector/shz_vec_add/): `#define shz_vec_add(vec1, vec2)` C type-generic vector addition.
- [`shz_vec_sub`](https://sh4zam.com/api/vector/shz_vec_sub/): `#define shz_vec_sub(vec1, vec2)` C type-generic vector subtraction.
- [`shz_vec_mul`](https://sh4zam.com/api/vector/shz_vec_mul/): `#define shz_vec_mul(vec1, vec2)` C type-generic vector multiplication.
- [`shz_vec_div`](https://sh4zam.com/api/vector/shz_vec_div/): `#define shz_vec_div(vec1, vec2)` C type-generic vector division.
- [`shz_vec_scale`](https://sh4zam.com/api/vector/shz_vec_scale/): `#define shz_vec_scale(vec, factor)` C type-generic vector scaling.
- [`shz_vec_dot`](https://sh4zam.com/api/vector/shz_vec_dot/): `#define shz_vec_dot(vec1, vec2)` C type-generic vector dot product.
- [`shz_vec_dot2`](https://sh4zam.com/api/vector/shz_vec_dot2/): `#define shz_vec_dot2(l, r1, r2)` C type-generic vector chained double dot product.
- [`shz_vec_dot3`](https://sh4zam.com/api/vector/shz_vec_dot3/): `#define shz_vec_dot3(l, r1, r2, r3)` C type-generic vector chained triple dot product.
- [`shz_vec_magnitude_sqr`](https://sh4zam.com/api/vector/shz_vec_magnitude_sqr/): `#define shz_vec_magnitude_sqr(vec)` C type-generic vector squared magnitude.
- [`shz_vec_magnitude`](https://sh4zam.com/api/vector/shz_vec_magnitude/): `#define shz_vec_magnitude(vec)` C type-generic vector magnitude.
- [`shz_vec_magnitude_inv`](https://sh4zam.com/api/vector/shz_vec_magnitude_inv/): `#define shz_vec_magnitude_inv(vec)` C type-generic vector inverse magnitude.
- [`shz_vec_normalize`](https://sh4zam.com/api/vector/shz_vec_normalize/): `#define shz_vec_normalize(vec)` C type-generic vector normalization.
- [`shz_vec_normalize_safe`](https://sh4zam.com/api/vector/shz_vec_normalize_safe/): `#define shz_vec_normalize_safe(vec)` C type-generic safe vector normalization.
- [`shz_vec_distance`](https://sh4zam.com/api/vector/shz_vec_distance/): `#define shz_vec_distance(vec1, vec2)` C type-generic vector distance.
- [`shz_vec_move`](https://sh4zam.com/api/vector/shz_vec_move/): `#define shz_vec_move(vec, target, maxdist)` C type-generic vector move.
- [`shz_vec_distance_sqr`](https://sh4zam.com/api/vector/shz_vec_distance_sqr/): `#define shz_vec_distance_sqr(vec1, vec2)` C type-generic vector squared distance.
- [`shz_vec_lerp`](https://sh4zam.com/api/vector/shz_vec_lerp/): `#define shz_vec_lerp(vec1, vec2, t)` C type-generic linear interpolation between two vectors.
- [`shz_vec_reflect`](https://sh4zam.com/api/vector/shz_vec_reflect/): `#define shz_vec_reflect(incidence, normal)` C type-generic vector reflection.
- [`shz_vec_refract`](https://sh4zam.com/api/vector/shz_vec_refract/): `#define shz_vec_refract(incidence, normal, eta)` C type-generic vector refraction.
- [`shz_vec_cross`](https://sh4zam.com/api/vector/shz_vec_cross/): `#define shz_vec_cross(vec1, vec2)` C type-generic vector cross-product.
- [`shz_vec_project`](https://sh4zam.com/api/vector/shz_vec_project/): `#define shz_vec_project(vec1, vec2)` C type-generic vector projection.
- [`shz_vec_project_safe`](https://sh4zam.com/api/vector/shz_vec_project_safe/): `#define shz_vec_project_safe(vec1, vec2)` C type-generic safe vector projection.
- [`shz_vec_angles`](https://sh4zam.com/api/vector/shz_vec_angles/): `#define shz_vec_angles(vec)` C type-generic angle-from-vector extraction.
- [`shz_vec_angle_between`](https://sh4zam.com/api/vector/shz_vec_angle_between/): `#define shz_vec_angle_between(vec1, vec2)` C type-generic angle between two vectors.
- [`shz_vec_swizzle`](https://sh4zam.com/api/vector/shz_vec_swizzle/): `#define shz_vec_swizzle(vec, ...)` C type-generic vector swizzling.
- [`shz_vec_floor`](https://sh4zam.com/api/vector/shz_vec_floor/): `#define shz_vec_floor(vec)` C type-generic component-wise floor.
- [`shz_vec_ceil`](https://sh4zam.com/api/vector/shz_vec_ceil/): `#define shz_vec_ceil(vec)` C type-generic component-wise ceil.
- [`shz_vec_round`](https://sh4zam.com/api/vector/shz_vec_round/): `#define shz_vec_round(vec)` C type-generic component-wise round.
- [`shz_vec_fract`](https://sh4zam.com/api/vector/shz_vec_fract/): `#define shz_vec_fract(vec)` C type-generic component-wise fract.
- [`shz_vec_sign`](https://sh4zam.com/api/vector/shz_vec_sign/): `#define shz_vec_sign(vec)` C type-generic component-wise sign.
- [`shz_vec_saturate`](https://sh4zam.com/api/vector/shz_vec_saturate/): `#define shz_vec_saturate(vec)` C type-generic component-wise saturate.
- [`shz_vec_minv`](https://sh4zam.com/api/vector/shz_vec_minv/): `#define shz_vec_minv(a, b)` C type-generic pairwise minimum.
- [`shz_vec_maxv`](https://sh4zam.com/api/vector/shz_vec_maxv/): `#define shz_vec_maxv(a, b)` C type-generic pairwise maximum.
- [`shz_vec_inv_sqrtf`](https://sh4zam.com/api/vector/shz_vec_inv_sqrtf/): `#define shz_vec_inv_sqrtf(vec)` C type-generic inv_sqrtf.
- [`shz_vec_sqrtf`](https://sh4zam.com/api/vector/shz_vec_sqrtf/): `#define shz_vec_sqrtf(vec)` C type-generic sqrtf.
- [`shz_vec_stepv`](https://sh4zam.com/api/vector/shz_vec_stepv/): `#define shz_vec_stepv(vec, edge)` C type-generic component-wise step.
- [`shz_vec_step`](https://sh4zam.com/api/vector/shz_vec_step/): `#define shz_vec_step(vec, edge)` C type-generic step.
- [`shz_vec_smoothstepv`](https://sh4zam.com/api/vector/shz_vec_smoothstepv/): `#define shz_vec_smoothstepv(vec, edge0, edge1)` C type-generic component-wise smoothstep.
- [`shz_vec_smoothstep`](https://sh4zam.com/api/vector/shz_vec_smoothstep/): `#define shz_vec_smoothstep(vec, edge0, edge1)` C type-generic smoothstep.
- [`shz_vec_smoothstepv_safe`](https://sh4zam.com/api/vector/shz_vec_smoothstepv_safe/): `#define shz_vec_smoothstepv_safe(vec, edge0, edge1)` C type-generic component-wise smoothstep_safe.
- [`shz_vec_smoothstep_safe`](https://sh4zam.com/api/vector/shz_vec_smoothstep_safe/): `#define shz_vec_smoothstep_safe(vec, edge0, edge1)` C type-generic smoothstep_safe.

### Vector: Initializers

- [`shz_vec2_init`](https://sh4zam.com/api/vector/shz_vec2_init/): `shz_vec2_t shz_vec2_init(float x, float y)` Returns a 2D vector with the given `x`, and `y` coordinates.
- [`shz_vec3_init`](https://sh4zam.com/api/vector/shz_vec3_init/): `shz_vec3_t shz_vec3_init(float x, float y, float z)` Returns a 3D vector with the given `x`, `y`, and `z` coordinates.
- [`shz_vec4_init`](https://sh4zam.com/api/vector/shz_vec4_init/): `shz_vec4_t shz_vec4_init(float x, float y, float z, float w)` Returns a 4D vector with the given `x`, `y`, `z`, and `w` coordinates.
- [`shz_vec2_fill`](https://sh4zam.com/api/vector/shz_vec2_fill/): `shz_vec2_t shz_vec2_fill(float v)` Returns a 2D vector with the value of each component equal to `v`.
- [`shz_vec3_fill`](https://sh4zam.com/api/vector/shz_vec3_fill/): `shz_vec3_t shz_vec3_fill(float v)` Returns a 3D vector with the value of each compoonent equal to `v`.
- [`shz_vec4_fill`](https://sh4zam.com/api/vector/shz_vec4_fill/): `shz_vec4_t shz_vec4_fill(float v)` Returns a 4D vector with the value of each component equal to `v`.

### Vector: Component-wise Operations

- [`shz_vec2_abs`](https://sh4zam.com/api/vector/shz_vec2_abs/): `shz_vec2_t shz_vec2_abs(shz_vec2_t vec)` 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/): `shz_vec3_t shz_vec3_abs(shz_vec3_t vec)` 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/): `shz_vec4_t shz_vec4_abs(shz_vec4_t vec)` 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/): `shz_vec2_t shz_vec2_neg(shz_vec2_t vec)` 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/): `shz_vec3_t shz_vec3_neg(shz_vec3_t vec)` 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/): `shz_vec4_t shz_vec4_neg(shz_vec4_t vec)` 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/): `shz_vec2_t shz_vec2_inv(shz_vec2_t vec)` Returns the 2D vector whose components have been inverted or reciprocated.
- [`shz_vec3_inv`](https://sh4zam.com/api/vector/shz_vec3_inv/): `shz_vec3_t shz_vec3_inv(shz_vec3_t vec)` Returns the 3D vector whose components have been inverted or reciprocated.
- [`shz_vec4_inv`](https://sh4zam.com/api/vector/shz_vec4_inv/): `shz_vec4_t shz_vec4_inv(shz_vec4_t vec)` Returns the 4D vector whose components have been inverted or reciprocated.
- [`shz_vec2_max`](https://sh4zam.com/api/vector/shz_vec2_max/): `float shz_vec2_max(shz_vec2_t vec)` Returns the maximum value of both of the given vector's components.
- [`shz_vec3_max`](https://sh4zam.com/api/vector/shz_vec3_max/): `float shz_vec3_max(shz_vec3_t vec)` Returns the maximum value of the given vector's 3 components.
- [`shz_vec4_max`](https://sh4zam.com/api/vector/shz_vec4_max/): `float shz_vec4_max(shz_vec4_t vec)` Returns the maximum value of the given vector's 4 componetns.
- [`shz_vec2_min`](https://sh4zam.com/api/vector/shz_vec2_min/): `float shz_vec2_min(shz_vec2_t vec)` Retuns the minimum value of both of the given vector's components.
- [`shz_vec3_min`](https://sh4zam.com/api/vector/shz_vec3_min/): `float shz_vec3_min(shz_vec3_t vec)` Returns the minimum value of the given vector's 3 components.
- [`shz_vec4_min`](https://sh4zam.com/api/vector/shz_vec4_min/): `float shz_vec4_min(shz_vec4_t vec)` Returns the minimum value of the given vector's 4 components.
- [`shz_vec2_clamp`](https://sh4zam.com/api/vector/shz_vec2_clamp/): `shz_vec2_t shz_vec2_clamp(shz_vec2_t vec, float min, float max)` 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/): `shz_vec3_t shz_vec3_clamp(shz_vec3_t vec, float min, float max)` 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/): `shz_vec4_t shz_vec4_clamp(shz_vec4_t vec, float min, float max)` 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/): `shz_vec2_t shz_vec2_floor(shz_vec2_t vec)` 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/): `shz_vec3_t shz_vec3_floor(shz_vec3_t vec)` 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/): `shz_vec4_t shz_vec4_floor(shz_vec4_t vec)` 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/): `shz_vec2_t shz_vec2_ceil(shz_vec2_t vec)` 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/): `shz_vec3_t shz_vec3_ceil(shz_vec3_t vec)` 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/): `shz_vec4_t shz_vec4_ceil(shz_vec4_t vec)` 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/): `shz_vec2_t shz_vec2_round(shz_vec2_t vec)` 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/): `shz_vec3_t shz_vec3_round(shz_vec3_t vec)` 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/): `shz_vec4_t shz_vec4_round(shz_vec4_t vec)` 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/): `shz_vec2_t shz_vec2_fract(shz_vec2_t vec)` 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/): `shz_vec3_t shz_vec3_fract(shz_vec3_t vec)` 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/): `shz_vec4_t shz_vec4_fract(shz_vec4_t vec)` 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/): `shz_vec2_t shz_vec2_sign(shz_vec2_t vec)` 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/): `shz_vec3_t shz_vec3_sign(shz_vec3_t vec)` 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/): `shz_vec4_t shz_vec4_sign(shz_vec4_t vec)` 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/): `shz_vec2_t shz_vec2_saturate(shz_vec2_t vec)` 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/): `shz_vec3_t shz_vec3_saturate(shz_vec3_t vec)` 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/): `shz_vec4_t shz_vec4_saturate(shz_vec4_t vec)` 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/): `shz_vec2_t shz_vec2_minv(shz_vec2_t a, shz_vec2_t b)` 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/): `shz_vec3_t shz_vec3_minv(shz_vec3_t a, shz_vec3_t b)` 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/): `shz_vec4_t shz_vec4_minv(shz_vec4_t a, shz_vec4_t b)` 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/): `shz_vec2_t shz_vec2_maxv(shz_vec2_t a, shz_vec2_t b)` 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/): `shz_vec3_t shz_vec3_maxv(shz_vec3_t a, shz_vec3_t b)` 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/): `shz_vec4_t shz_vec4_maxv(shz_vec4_t a, shz_vec4_t b)` 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/): `bool shz_vec2_equal(shz_vec2_t a, shz_vec2_t b)` 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/): `bool shz_vec3_equal(shz_vec3_t a, shz_vec3_t b)` 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/): `bool shz_vec4_equal(shz_vec4_t a, shz_vec4_t b)` 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/): `shz_vec2_t shz_vec2_stepv( shz_vec2_t vec, shz_vec2_t edge)` 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/): `shz_vec3_t shz_vec3_stepv(shz_vec3_t vec, shz_vec3_t edge)` 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/): `shz_vec4_t shz_vec4_stepv(shz_vec4_t vec, shz_vec4_t edge)` 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/): `shz_vec2_t shz_vec2_step(shz_vec2_t vec, float edge)` For each component: returns 0.0f if vec\[i\] \< edge, otherwise 1.0f.
- [`shz_vec3_step`](https://sh4zam.com/api/vector/shz_vec3_step/): `shz_vec3_t shz_vec3_step(shz_vec3_t vec, float edge)` For each component: returns 0.0f if vec\[i\] \< edge, otherwise 1.0f.
- [`shz_vec4_step`](https://sh4zam.com/api/vector/shz_vec4_step/): `shz_vec4_t shz_vec4_step(shz_vec4_t vec, float edge)` For each component: returns 0.0f if vec\[i\] \< edge, otherwise 1.0f.
- [`shz_vec2_smoothstep`](https://sh4zam.com/api/vector/shz_vec2_smoothstep/): `shz_vec2_t shz_vec2_smoothstep(shz_vec2_t vec, float edge0, float edge1)` 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/): `shz_vec3_t shz_vec3_smoothstep(shz_vec3_t vec, float edge0, float edge1)` 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/): `shz_vec4_t shz_vec4_smoothstep(shz_vec4_t vec, float edge0, float edge1)` 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/): `shz_vec2_t shz_vec2_smoothstepv(shz_vec2_t vec, shz_vec2_t edge0, shz_vec2_t edge1)` 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/): `shz_vec3_t shz_vec3_smoothstepv(shz_vec3_t vec, shz_vec3_t edge0, shz_vec3_t edge1)` 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/): `shz_vec4_t shz_vec4_smoothstepv(shz_vec4_t vec, shz_vec4_t edge0, shz_vec4_t edge1)` 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/): `shz_vec2_t shz_vec2_smoothstep_safe(shz_vec2_t vec, float edge0, float edge1)` 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/): `shz_vec3_t shz_vec3_smoothstep_safe(shz_vec3_t vec, float edge0, float edge1)` 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/): `shz_vec4_t shz_vec4_smoothstep_safe(shz_vec4_t vec, float edge0, float edge1)` 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/): `shz_vec2_t shz_vec2_smoothstepv_safe(shz_vec2_t vec, shz_vec2_t edge0, shz_vec2_t edge1)` 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/): `shz_vec3_t shz_vec3_smoothstepv_safe(shz_vec3_t vec, shz_vec3_t edge0, shz_vec3_t edge1)` 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/): `shz_vec4_t shz_vec4_smoothstepv_safe(shz_vec4_t vec, shz_vec4_t edge0, shz_vec4_t edge1)` 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/): `shz_vec2_t shz_vec2_inv_sqrtf(shz_vec2_t vec)` 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/): `shz_vec3_t shz_vec3_inv_sqrtf(shz_vec3_t vec)` 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/): `shz_vec4_t shz_vec4_inv_sqrtf(shz_vec4_t vec)` 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/): `shz_vec2_t shz_vec2_sqrtf(shz_vec2_t vec)` 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/): `shz_vec3_t shz_vec3_sqrtf(shz_vec3_t vec)` 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/): `shz_vec4_t shz_vec4_sqrtf(shz_vec4_t vec)` Returns a 4D vector whose components are the square root of the given vector's components.

### Vector: Arithmetic

- [`shz_vec2_add`](https://sh4zam.com/api/vector/shz_vec2_add/): `shz_vec2_t shz_vec2_add(shz_vec2_t vec1, shz_vec2_t vec2)` 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/): `shz_vec3_t shz_vec3_add(shz_vec3_t vec1, shz_vec3_t vec2)` 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/): `shz_vec4_t shz_vec4_add(shz_vec4_t vec1, shz_vec4_t vec2)` 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/): `shz_vec2_t shz_vec2_sub(shz_vec2_t vec1, shz_vec2_t vec2)` 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/): `shz_vec3_t shz_vec3_sub(shz_vec3_t vec1, shz_vec3_t vec2)` 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/): `shz_vec4_t shz_vec4_sub(shz_vec4_t vec1, shz_vec4_t vec2)` 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/): `shz_vec2_t shz_vec2_mul(shz_vec2_t vec1, shz_vec2_t vec2)` Returns a 2D vector whose component values are those of `vec1` times `vec2`.
- [`shz_vec3_mul`](https://sh4zam.com/api/vector/shz_vec3_mul/): `shz_vec3_t shz_vec3_mul(shz_vec3_t vec1, shz_vec3_t vec2)` Returns a 3D vector whose component values are those of `vec1` times `vec2`.
- [`shz_vec4_mul`](https://sh4zam.com/api/vector/shz_vec4_mul/): `shz_vec4_t shz_vec4_mul(shz_vec4_t vec1, shz_vec4_t vec2)` Returns a 4D vector whose component values are those of `vec1` times `vec2`.
- [`shz_vec2_div`](https://sh4zam.com/api/vector/shz_vec2_div/): `shz_vec2_t shz_vec2_div(shz_vec2_t vec1, shz_vec2_t vec2)` 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/): `shz_vec3_t shz_vec3_div(shz_vec3_t vec1, shz_vec3_t vec2)` 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/): `shz_vec4_t shz_vec4_div(shz_vec4_t vec1, shz_vec4_t vec2)` 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/): `shz_vec2_t shz_vec2_scale(shz_vec2_t vec, float factor)` 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/): `shz_vec3_t shz_vec3_scale(shz_vec3_t vec, float factor)` 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/): `shz_vec4_t shz_vec4_scale(shz_vec4_t vec, float factor)` Returns a 4D vector whose component values are those of the given vector multiplied by a factor.

### Vector: Magnitude

- [`shz_vec2_magnitude_sqr`](https://sh4zam.com/api/vector/shz_vec2_magnitude_sqr/): `float shz_vec2_magnitude_sqr(shz_vec2_t vec)` Returns the squared magnitude of the given 2D vector.
- [`shz_vec4_magnitude_sqr`](https://sh4zam.com/api/vector/shz_vec4_magnitude_sqr/): `float shz_vec4_magnitude_sqr(shz_vec4_t vec)` Returns the squared magnitude of the given 4D vector.
- [`shz_vec3_magnitude_sqr`](https://sh4zam.com/api/vector/shz_vec3_magnitude_sqr/): `float shz_vec3_magnitude_sqr(shz_vec3_t vec)` Returns the squared magnitude of the given 3D vector.
- [`shz_vec2_magnitude`](https://sh4zam.com/api/vector/shz_vec2_magnitude/): `float shz_vec2_magnitude(shz_vec2_t vec)` Returns the magnitude of the given 2D vector.
- [`shz_vec3_magnitude`](https://sh4zam.com/api/vector/shz_vec3_magnitude/): `float shz_vec3_magnitude(shz_vec3_t vec)` Returns the magnitude of the given 3D vector.
- [`shz_vec4_magnitude`](https://sh4zam.com/api/vector/shz_vec4_magnitude/): `float shz_vec4_magnitude(shz_vec4_t vec)` Returns the magnitude of the given 4D vector.
- [`shz_vec2_magnitude_inv`](https://sh4zam.com/api/vector/shz_vec2_magnitude_inv/): `float shz_vec2_magnitude_inv(shz_vec2_t vec)` Returns the inverse magnitude of the given 2D vector.
- [`shz_vec3_magnitude_inv`](https://sh4zam.com/api/vector/shz_vec3_magnitude_inv/): `float shz_vec3_magnitude_inv(shz_vec3_t vec)` Returns the inverse magnitude of the given 3D vector.
- [`shz_vec4_magnitude_inv`](https://sh4zam.com/api/vector/shz_vec4_magnitude_inv/): `float shz_vec4_magnitude_inv(shz_vec4_t vec)` Returns the inverse magnitude of the given 4D vector.
- [`shz_vec2_normalize`](https://sh4zam.com/api/vector/shz_vec2_normalize/): `shz_vec2_t shz_vec2_normalize(shz_vec2_t vec)` Returns a normalized unit vector from the given 2D vector.
- [`shz_vec3_normalize`](https://sh4zam.com/api/vector/shz_vec3_normalize/): `shz_vec3_t shz_vec3_normalize(shz_vec3_t vec)` Returns a normalized unit vector from the given 3D vector.
- [`shz_vec4_normalize`](https://sh4zam.com/api/vector/shz_vec4_normalize/): `shz_vec4_t shz_vec4_normalize(shz_vec4_t vec)` Returns a normalized unit vector from the given 4D vector.
- [`shz_vec2_normalize_safe`](https://sh4zam.com/api/vector/shz_vec2_normalize_safe/): `shz_vec2_t shz_vec2_normalize_safe(shz_vec2_t vec)` SAFELY returns a normalized unit vector from the given 2D vector.
- [`shz_vec3_normalize_safe`](https://sh4zam.com/api/vector/shz_vec3_normalize_safe/): `shz_vec3_t shz_vec3_normalize_safe(shz_vec3_t vec)` SAFELY returns a normalized unit vector from the given 3D vector.
- [`shz_vec4_normalize_safe`](https://sh4zam.com/api/vector/shz_vec4_normalize_safe/): `shz_vec4_t shz_vec4_normalize_safe(shz_vec4_t vec)` SAFELY returns a normalized unit vector from the given 4D vector.

### Vector: Binary Operations

- [`shz_vec2_dot`](https://sh4zam.com/api/vector/shz_vec2_dot/): `float shz_vec2_dot(shz_vec2_t vec1, shz_vec2_t vec2)` Returns the dot product between the two given 2D vectors.
- [`shz_vec2_dot2`](https://sh4zam.com/api/vector/shz_vec2_dot2/): `shz_vec2_t shz_vec2_dot2(shz_vec2_t l, shz_vec2_t r1, shz_vec2_t r2)` 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/): `shz_vec3_t shz_vec2_dot3(shz_vec2_t l, shz_vec2_t r1, shz_vec2_t r2, shz_vec2_t r3)` 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/): `float shz_vec3_dot(shz_vec3_t vec1, shz_vec3_t vec2)` Returns the dot product between the two given 3D vectors.
- [`shz_vec3_dot2`](https://sh4zam.com/api/vector/shz_vec3_dot2/): `shz_vec2_t shz_vec3_dot2(shz_vec3_t l, shz_vec3_t r1, shz_vec3_t r2)` 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/): `shz_vec3_t shz_vec3_dot3(shz_vec3_t l, shz_vec3_t r1, shz_vec3_t r2, shz_vec3_t r3)` 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/): `float shz_vec4_dot(shz_vec4_t vec1, shz_vec4_t vec2)` Returns the dot product between the two given 4D vectors.
- [`shz_vec4_dot2`](https://sh4zam.com/api/vector/shz_vec4_dot2/): `shz_vec2_t shz_vec4_dot2(shz_vec4_t l, shz_vec4_t r1, shz_vec4_t r2)` 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/): `shz_vec3_t shz_vec4_dot3(shz_vec4_t l, shz_vec4_t r1, shz_vec4_t r2, shz_vec4_t r3)` 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/): `float shz_vec2_distance(shz_vec2_t vec1, shz_vec2_t vec2)` Returns the distance between the two given 2D vectors.
- [`shz_vec3_distance`](https://sh4zam.com/api/vector/shz_vec3_distance/): `float shz_vec3_distance(shz_vec3_t vec1, shz_vec3_t vec2)` Returns the distance between the two given 3D vectors.
- [`shz_vec4_distance`](https://sh4zam.com/api/vector/shz_vec4_distance/): `float shz_vec4_distance(shz_vec4_t vec1, shz_vec4_t vec2)` Returns the distance between the two given 4D vectors.
- [`shz_vec2_distance_sqr`](https://sh4zam.com/api/vector/shz_vec2_distance_sqr/): `float shz_vec2_distance_sqr(shz_vec2_t vec1, shz_vec2_t vec2)` Returns the squared-distance between the two given 2D vectors.
- [`shz_vec3_distance_sqr`](https://sh4zam.com/api/vector/shz_vec3_distance_sqr/): `float shz_vec3_distance_sqr(shz_vec3_t vec1, shz_vec3_t vec2)` Returns the squared-distance between the two given 3D vectors.
- [`shz_vec4_distance_sqr`](https://sh4zam.com/api/vector/shz_vec4_distance_sqr/): `float shz_vec4_distance_sqr(shz_vec4_t vec1, shz_vec4_t vec2)` Returns the squared-distance between the two given 4D vectors.
- [`shz_vec2_move`](https://sh4zam.com/api/vector/shz_vec2_move/): `shz_vec2_t shz_vec2_move(shz_vec2_t vec, shz_vec2_t target, float max_distance)` 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/): `shz_vec3_t shz_vec3_move(shz_vec3_t vec, shz_vec3_t target, float max_distance)` 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/): `shz_vec4_t shz_vec4_move(shz_vec4_t vec, shz_vec4_t target, float max_distance)` 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/): `shz_vec2_t shz_vec2_lerp(shz_vec2_t a, shz_vec2_t b, float t)` 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/): `shz_vec3_t shz_vec3_lerp(shz_vec3_t a, shz_vec3_t b, float t)` 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/): `shz_vec4_t shz_vec4_lerp(shz_vec4_t a, shz_vec4_t b, float t)` 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/): `shz_vec2_t shz_vec2_reflect(shz_vec2_t incidence, shz_vec2_t normal)` 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/): `shz_vec3_t shz_vec3_reflect(shz_vec3_t incidence, shz_vec3_t normal)` 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/): `shz_vec4_t shz_vec4_reflect(shz_vec4_t incidence, shz_vec4_t normal)` 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/): `shz_vec2_t shz_vec2_refract(shz_vec2_t incidence, shz_vec2_t normal, float eta)` 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/): `shz_vec3_t shz_vec3_refract(shz_vec3_t incidence, shz_vec3_t normal, float eta)` 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/): `shz_vec4_t shz_vec4_refract(shz_vec4_t incidence, shz_vec4_t normal, float eta)` 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/): `float shz_vec2_cross(shz_vec2_t vec1, shz_vec2_t vec2)` Returns the cross product, as a scalar, between two 2D vectors.
- [`shz_vec3_cross`](https://sh4zam.com/api/vector/shz_vec3_cross/): `shz_vec3_t shz_vec3_cross(shz_vec3_t vec1, shz_vec3_t vec2)` 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/): `shz_vec2_t shz_vec2_project(shz_vec2_t vec, shz_vec2_t onto)` 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/): `shz_vec3_t shz_vec3_project(shz_vec3_t vec, shz_vec3_t onto)` 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/): `shz_vec4_t shz_vec4_project(shz_vec4_t vec, shz_vec4_t onto)` 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/): `shz_vec2_t shz_vec2_project_safe(shz_vec2_t vec, shz_vec2_t onto)` 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/): `shz_vec3_t shz_vec3_project_safe(shz_vec3_t vec, shz_vec3_t onto)` 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/): `shz_vec4_t shz_vec4_project_safe(shz_vec4_t vec, shz_vec4_t onto)` 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/): `shz_vec3_t shz_vec3_reject(shz_vec3_t vec, shz_vec3_t onto)` Returns the rejection of the given vector, `vec`, onto another vector, `onto`.

### Vector: Miscellaneous

- [`shz_vec3_triple`](https://sh4zam.com/api/vector/shz_vec3_triple/): `float shz_vec3_triple(shz_vec3_t a, shz_vec3_t b, shz_vec3_t c)` Returns the 3D vector "triple product" between vector's `a`, `b`, and `c`.
- [`shz_vec3_perp`](https://sh4zam.com/api/vector/shz_vec3_perp/): `shz_vec3_t shz_vec3_perp(shz_vec3_t vec)` Returns a vector which is perpendicular to the given vector.
- [`shz_vec3_barycenter`](https://sh4zam.com/api/vector/shz_vec3_barycenter/): `shz_vec3_t shz_vec3_barycenter(shz_vec3_t p, shz_vec3_t a, shz_vec3_t b, shz_vec3_t c)` 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/): `void shz_vec3_orthonormalize(shz_vec3_t in1, shz_vec3_t in2, shz_vec3_t* out1, shz_vec3_t* out2)` 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/): `shz_vec3_t shz_vec3_cubic_hermite(shz_vec3_t vec, shz_vec3_t tangent1, shz_vec3_t vec2, shz_vec3_t tangent2, float amounht)` Calculates the cubic hermite interpolation between two vectors and their tangents.

### Vector: Angles

- [`shz_vec2_angle_between`](https://sh4zam.com/api/vector/shz_vec2_angle_between/): `float shz_vec2_angle_between(shz_vec2_t vec1, shz_vec2_t vec2)` Returns the angle formed between the given 2D vectors in radians.
- [`shz_vec3_angle_between`](https://sh4zam.com/api/vector/shz_vec3_angle_between/): `float shz_vec3_angle_between(shz_vec3_t vec1, shz_vec3_t vec2)` Returns the angle formed between the given 3D vectors in radians.
- [`shz_vec2_angle`](https://sh4zam.com/api/vector/shz_vec2_angle/): `float shz_vec2_angle(shz_vec2_t vec)` 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/): `shz_vec3_t shz_vec3_angles(shz_vec3_t vec)` 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/): `shz_vec2_t shz_vec2_from_sincos(shz_sincos_t 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/): `shz_vec3_t shz_vec3_from_sincos(shz_sincos_t azimuth, shz_sincos_t elevation)` 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/): `shz_vec2_t shz_vec2_from_angle(float radians)` 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/): `shz_vec3_t shz_vec3_from_angles(float azimuth, float elevation)` 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/): `shz_vec2_t shz_vec2_from_angle_deg(float degrees)` 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/): `shz_vec3_t shz_vec3_from_angles_deg(float azimuth, float elevation)` 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/): `shz_vec2_t shz_vec2_rotate(shz_vec2_t vec, float radians)` 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/): `shz_vec3_t shz_vec3_rotate_x(shz_vec3_t vec, float radians)` 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/): `shz_vec3_t shz_vec3_rotate_y(shz_vec3_t vec, float radians)` 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/): `shz_vec3_t shz_vec3_rotate_z(shz_vec3_t vec, float radians)` Rotates the given 3D vector about the Z axis by the given angle in radians.

### Vector: Extending

- [`shz_vec2_vec3`](https://sh4zam.com/api/vector/shz_vec2_vec3/): `shz_vec3_t shz_vec2_vec3(shz_vec2_t vec, float z)` 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/): `shz_vec4_t shz_vec2_vec4(shz_vec2_t vec, float z, float w)` 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/): `shz_vec4_t shz_vec3_vec4(shz_vec3_t vec, float w)` Extends a 3D vector to 4D, using `w` as the value of the W component.

### Vector: Swizzling

- [`shz_vec2_swizzle`](https://sh4zam.com/api/vector/shz_vec2_swizzle/): `shz_vec2_t shz_vec2_swizzle(shz_vec2_t vec, unsigned x_idx, unsigned y_idx)` 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/): `shz_vec3_t shz_vec3_swizzle(shz_vec3_t vec, unsigned x_idx, unsigned y_idx, unsigned z_idx)` 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/): `shz_vec4_t shz_vec4_swizzle(shz_vec4_t vec, unsigned x_idx, unsigned y_idx, unsigned z_idx, unsigned w_idx)` Returns a new 2D vector whose elements are equal to the source vector's values at the given indices.

### Vector: Types

- [`shz_vec2_t`](https://sh4zam.com/api/vector/shz_vec2_t/): `struct shz_vec2_t` 2D Vector type
- [`shz_vec2`](https://sh4zam.com/api/vector/shz_vec2/): `typedef shz_vec2_t shz_vec2` Alternate typedef for the `shz_vec2` struct for those who hate POSIX-style.
- [`shz_vec3_t`](https://sh4zam.com/api/vector/shz_vec3_t/): `struct shz_vec3_t` 3D Vector type
- [`shz_vec3`](https://sh4zam.com/api/vector/shz_vec3/): `typedef shz_vec3_t shz_vec3` Alternate typedef for the `shz_vec3` struct for those who hate POSIX-style.
- [`shz_vec4_t`](https://sh4zam.com/api/vector/shz_vec4_t/): `struct shz_vec4_t` 4D Vector type
- [`shz_vec4`](https://sh4zam.com/api/vector/shz_vec4/): `typedef shz_vec4_t shz_vec4` Alternate typedef for the `shz_vec4` struct for those who hate POSIX-style.

## Quaternion

`#include <sh4zam/shz_quat.h>` · [module page](https://sh4zam.com/api/quat/)

### Quaternion: Initialization

- [`shz_quat_init`](https://sh4zam.com/api/quat/shz_quat_init/): `shz_quat_t shz_quat_init(float w, float x, float y, float z)` Initializes and returns a new quaternion with the given components, in WXYZ order.
- [`shz_quat_identity`](https://sh4zam.com/api/quat/shz_quat_identity/): `shz_quat_t shz_quat_identity(void)` Initializes and returns an identity quaternion.
- [`shz_quat_equal`](https://sh4zam.com/api/quat/shz_quat_equal/): `bool shz_quat_equal(shz_quat_t a, shz_quat_t b)` Returns true if the two given quaternions are considered equal based on either absolute or relative tolerance.
- [`shz_quat_from_angles_xyz`](https://sh4zam.com/api/quat/shz_quat_from_angles_xyz/): `shz_quat_t shz_quat_from_angles_xyz(float xangle, float yangle, float zangle)` Initializes and returns a quaternion with the given X-Y-Z rotations in radians.
- [`shz_quat_from_rotation_xyz`](https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz/): `shz_quat_t shz_quat_from_rotation_xyz(float xAngle, float yAngle, float zAngle)` Returns the quaternion of the rotation `shz_xmtrx_init_rotation_xyz()` builds, from angles in radians.
- [`shz_quat_from_rotation_zyx`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx/): `shz_quat_t shz_quat_from_rotation_zyx(float zAngle, float yAngle, float xAngle)` Returns the quaternion of the rotation `shz_xmtrx_init_rotation_zyx()` builds, Qz \* Qy \* Qx, from angles in radians.
- [`shz_quat_from_rotation_zxy`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy/): `shz_quat_t shz_quat_from_rotation_zxy(float zAngle, float xAngle, float yAngle)` Returns the quaternion of the rotation `shz_xmtrx_init_rotation_zxy()` builds, Qz \* Qx \* Qy, from angles in radians.
- [`shz_quat_from_rotation_yxz`](https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz/): `shz_quat_t shz_quat_from_rotation_yxz(float yAngle, float xAngle, float zAngle)` Returns the quaternion of the rotation `shz_xmtrx_init_rotation_yxz()` builds, Qy \* Qx \* Qz, from angles in radians.
- [`shz_quat_from_rotation_xyz_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_xyz_u16/): `shz_quat_t shz_quat_from_rotation_xyz_u16(uint16_t xAngle, uint16_t yAngle, uint16_t zAngle)` Equivalent to `shz_quat_from_rotation_xyz()`, with 16-bit binary angles (65536 per turn, the FSCA unit).
- [`shz_quat_from_rotation_zyx_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zyx_u16/): `shz_quat_t shz_quat_from_rotation_zyx_u16(uint16_t zAngle, uint16_t yAngle, uint16_t xAngle)` Equivalent to `shz_quat_from_rotation_zyx()`, with 16-bit binary angles.
- [`shz_quat_from_rotation_zxy_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_zxy_u16/): `shz_quat_t shz_quat_from_rotation_zxy_u16(uint16_t zAngle, uint16_t xAngle, uint16_t yAngle)` Equivalent to `shz_quat_from_rotation_zxy()`, with 16-bit binary angles.
- [`shz_quat_from_rotation_yxz_u16`](https://sh4zam.com/api/quat/shz_quat_from_rotation_yxz_u16/): `shz_quat_t shz_quat_from_rotation_yxz_u16(uint16_t yAngle, uint16_t xAngle, uint16_t zAngle)` Equivalent to `shz_quat_from_rotation_yxz()`, with 16-bit binary angles.
- [`shz_quat_from_axis_angle`](https://sh4zam.com/api/quat/shz_quat_from_axis_angle/): `shz_quat_t shz_quat_from_axis_angle(shz_vec3_t axis, float angle)` Initializes and returns a quaternion representing a rotation of `angle` radians about the given `axis`.
- [`shz_quat_from_look_axis`](https://sh4zam.com/api/quat/shz_quat_from_look_axis/): `shz_quat_t shz_quat_from_look_axis(shz_vec3_t forward, shz_vec3_t up)` Creates a quaternion looking in the given direction with the given reference direction.
- [`shz_quat_from_rotated_axis`](https://sh4zam.com/api/quat/shz_quat_from_rotated_axis/): `shz_quat_t shz_quat_from_rotated_axis(shz_vec3_t v1, shz_vec3_t v2)` Returns the quaternion representing the rotation from axis `v1` to `v2`.
- [`shz_quat_lerp`](https://sh4zam.com/api/quat/shz_quat_lerp/): `shz_quat_t shz_quat_lerp(shz_quat_t a, shz_quat_t b, float t)` Returns the quaternion that is linearly interpolating `a` to `b`, by a t factor of `0.0f-1.0f`.
- [`shz_quat_nlerp`](https://sh4zam.com/api/quat/shz_quat_nlerp/): `shz_quat_t shz_quat_nlerp(shz_quat_t a, shz_quat_t b, float t)` Equivalent to `shz_quat_lerp()`, except that the resulting quaternion is normalized.
- [`shz_quat_slerp`](https://sh4zam.com/api/quat/shz_quat_slerp/): `shz_quat_t shz_quat_slerp(shz_quat_t q, shz_quat_t p, float t)` Returns the quaternion that is spherically linearly interpolating `a` to `b`, by a `t` factor of `0.0f-1.0f`.
- [`shz_quat_squad`](https://sh4zam.com/api/quat/shz_quat_squad/): `shz_quat_t shz_quat_squad(shz_quat_t q1, shz_quat_t q2, shz_quat_t s1, shz_quat_t s2, float t)` Evaluates a smooth cubic spherical interpolation (SQUAD) at parameter `t`.

### Quaternion: Properties

- [`shz_quat_angle`](https://sh4zam.com/api/quat/shz_quat_angle/): `float shz_quat_angle(shz_quat_t q)` Returns the angle of rotation from the given quaternion.
- [`shz_quat_axis`](https://sh4zam.com/api/quat/shz_quat_axis/): `shz_vec3_t shz_quat_axis(shz_quat_t q)` Returns the axis of rotation from the given quaternion.
- [`shz_quat_angle_x`](https://sh4zam.com/api/quat/shz_quat_angle_x/): `float shz_quat_angle_x(shz_quat_t q)` Returns the angle of rotation the quaternion represents about the X axis in radians.
- [`shz_quat_angle_y`](https://sh4zam.com/api/quat/shz_quat_angle_y/): `float shz_quat_angle_y(shz_quat_t q)` Returns the angle of rotation the quaternion represents about the Y axis in radians.
- [`shz_quat_angle_z`](https://sh4zam.com/api/quat/shz_quat_angle_z/): `float shz_quat_angle_z(shz_quat_t q)` Returns the angle of rotation the quaternion represents about the Z axis in radians.
- [`shz_quat_to_axis_angle`](https://sh4zam.com/api/quat/shz_quat_to_axis_angle/): `void shz_quat_to_axis_angle(shz_quat_t q, shz_vec3_t* vec, float* angle)` Returns both the axis and angle of rotation simultaneously (faster if both are needed) from the given quaternion.
- [`shz_quat_to_angles_xyz`](https://sh4zam.com/api/quat/shz_quat_to_angles_xyz/): `shz_vec3_t shz_quat_to_angles_xyz(shz_quat_t q)` Returns the roll, pitch, and yaw angles of rotation represented by the given quaternion.
- [`shz_quat_magnitude_sqr`](https://sh4zam.com/api/quat/shz_quat_magnitude_sqr/): `float shz_quat_magnitude_sqr(shz_quat_t quat)` Returns the squared magnitude of the given quaternion.
- [`shz_quat_magnitude`](https://sh4zam.com/api/quat/shz_quat_magnitude/): `float shz_quat_magnitude(shz_quat_t quat)` Returns the magnitude of the given quaternion.
- [`shz_quat_magnitude_inv`](https://sh4zam.com/api/quat/shz_quat_magnitude_inv/): `float shz_quat_magnitude_inv(shz_quat_t quat)` Returns the inverse magnitude of the given quaternion.

### Quaternion: Modifiers

- [`shz_quat_normalize`](https://sh4zam.com/api/quat/shz_quat_normalize/): `shz_quat_t shz_quat_normalize(shz_quat_t quat)` Returns the normalized form of the given quaternion.
- [`shz_quat_normalize_safe`](https://sh4zam.com/api/quat/shz_quat_normalize_safe/): `shz_quat_t shz_quat_normalize_safe(shz_quat_t quat)` SAFELY returns the normalized form of the given quaternion.
- [`shz_quat_conjugate`](https://sh4zam.com/api/quat/shz_quat_conjugate/): `shz_quat_t shz_quat_conjugate(shz_quat_t quat)` Returns the conjugate of the given quaternion.
- [`shz_quat_inv`](https://sh4zam.com/api/quat/shz_quat_inv/): `shz_quat_t shz_quat_inv(shz_quat_t quat)` Returns the inverse of the given quaternion.
- [`shz_quat_neg`](https://sh4zam.com/api/quat/shz_quat_neg/): `shz_quat_t shz_quat_neg(shz_quat_t quat)` Returns the negation of the given quaternion.

### Quaternion: Arithmetic

- [`shz_quat_add`](https://sh4zam.com/api/quat/shz_quat_add/): `shz_quat_t shz_quat_add(shz_quat_t q, shz_quat_t p)` Returns the quaternion produced from adding each component of the given quaternions.
- [`shz_quat_sub`](https://sh4zam.com/api/quat/shz_quat_sub/): `shz_quat_t shz_quat_sub(shz_quat_t q, shz_quat_t p)` Returns the quaternion produced from subtracting each component of quaternion `p` from quaterion `q`.
- [`shz_quat_scale`](https://sh4zam.com/api/quat/shz_quat_scale/): `shz_quat_t shz_quat_scale(shz_quat_t q, float f)` Scales the components of the given quaternion by the given factor.
- [`shz_quat_mult`](https://sh4zam.com/api/quat/shz_quat_mult/): `shz_quat_t shz_quat_mult(shz_quat_t q1, shz_quat_t q2)` Multiplies the two quaternions, returning the result as a new quaternion.
- [`shz_quat_div`](https://sh4zam.com/api/quat/shz_quat_div/): `shz_quat_t shz_quat_div(shz_quat_t q, shz_quat_t p)` Divides quaternion `p` by quaternion `q` (multiplying by its inverse), returning the resulting quaternion.
- [`shz_quat_dot`](https://sh4zam.com/api/quat/shz_quat_dot/): `float shz_quat_dot(shz_quat_t q1, shz_quat_t q2)` Returns the dot product of the two quaternions.
- [`shz_quat_dot2`](https://sh4zam.com/api/quat/shz_quat_dot2/): `shz_vec2_t shz_quat_dot2(shz_quat_t l, shz_quat_t r1, shz_quat_t r2)` Returns the two dot products taken between the `l` quaternion and the `r1` and `r2` quaternions.
- [`shz_quat_dot3`](https://sh4zam.com/api/quat/shz_quat_dot3/): `shz_vec3_t shz_quat_dot3(shz_quat_t l, shz_quat_t r1, shz_quat_t r2, shz_quat_t r3)` Returns the two dot products taken between the `l` quaternion and the `r1`, `r2`, and `r3` quaternions.

### Quaternion: Miscellaneous

- [`shz_quat_angle_between`](https://sh4zam.com/api/quat/shz_quat_angle_between/): `float shz_quat_angle_between(shz_quat_t q, shz_quat_t p)` Returns the angle in radians between the rotations represented by quaternions `q` and `p`.
- [`shz_quat_rotate_towards`](https://sh4zam.com/api/quat/shz_quat_rotate_towards/): `shz_quat_t shz_quat_rotate_towards(shz_quat_t from, shz_quat_t to, float max_angle)` Rotates quaternion `from` towards quaternion `to` by at most `max_angle` radians.

### Quaternion: Transformations

- [`shz_quat_transform_vec3`](https://sh4zam.com/api/quat/shz_quat_transform_vec3/): `shz_vec3_t shz_quat_transform_vec3(shz_quat_t q, shz_vec3_t v)` Rotates a vector by the given quaternion.

### Quaternion: Types

- [`shz_quat_t`](https://sh4zam.com/api/quat/shz_quat_t/): `struct shz_quat_t` Represents a 3D quaternion.
- [`shz_quat`](https://sh4zam.com/api/quat/shz_quat/): `typedef shz_quat_t shz_quat` Alternate `shz_quat_t` C typedef for those who hate POSIX style.

## Matrix

`#include <sh4zam/shz_matrix.h>` · [module page](https://sh4zam.com/api/matrix/)

### Matrix: Initialization

- [`shz_mat4x4_init_identity`](https://sh4zam.com/api/matrix/shz_mat4x4_init_identity/): `void shz_mat4x4_init_identity(shz_mat4x4_t* mat)` Initializes the given matrix to the 4x4 identity matrix.
- [`shz_mat4x4_init_identity_safe`](https://sh4zam.com/api/matrix/shz_mat4x4_init_identity_safe/): `void shz_mat4x4_init_identity_safe(shz_mat4x4_t* mat)` Safely initializes the given matrix to the 4x4 identity matrix.
- [`shz_mat4x4_init_zero`](https://sh4zam.com/api/matrix/shz_mat4x4_init_zero/): `void shz_mat4x4_init_zero(shz_mat4x4_t* mat)` Initializes the given matrix with all 0s for its element values.
- [`shz_mat4x4_init_one`](https://sh4zam.com/api/matrix/shz_mat4x4_init_one/): `void shz_mat4x4_init_one(shz_mat4x4_t* mat)` Initializes the given matrix with all 1s for its element values.
- [`shz_mat4x4_init_fill`](https://sh4zam.com/api/matrix/shz_mat4x4_init_fill/): `void shz_mat4x4_init_fill(shz_mat4x4_t* mat, float value)` Initializes the given matrix with all elements assigned to the given value.
- [`shz_mat4x4_init_translation`](https://sh4zam.com/api/matrix/shz_mat4x4_init_translation/): `void shz_mat4x4_init_translation(shz_mat4x4_t* mat, float x, float y, float z)` Initializes the given matrix to a 3D translation matrix with the given coordinates.
- [`shz_mat4x4_init_scale`](https://sh4zam.com/api/matrix/shz_mat4x4_init_scale/): `void shz_mat4x4_init_scale(shz_mat4x4_t* mat, float x, float y, float z)` Initializes the given matrix to a 3D scaling matrix with the given dimensions.
- [`shz_mat4x4_init_rotation_x`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_x/): `void shz_mat4x4_init_rotation_x(shz_mat4x4_t* mat, float xAngle)` Initializes the given matrix to a 3D rotation matrix by `xAngle` radians over the X-axis.
- [`shz_mat4x4_init_rotation_y`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_y/): `void shz_mat4x4_init_rotation_y(shz_mat4x4_t* mat, float yAngle)` Initializes the given matrix to a 3D rotation matrix by `yAngle` radians over the Y-axis.
- [`shz_mat4x4_init_rotation_z`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_z/): `void shz_mat4x4_init_rotation_z(shz_mat4x4_t* mat, float zAngle)` Initializes the given matrix to a 3D rotation matrix by `zAngle` radians over the Z-axis.
- [`shz_mat4x4_init_rotation_xyz`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_xyz/): `void shz_mat4x4_init_rotation_xyz(shz_mat4x4_t* mat, float xAngle, float yAngle, float zAngle)` Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan X-Y-Z angles.
- [`shz_mat4x4_init_rotation_zyx`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_zyx/): `void shz_mat4x4_init_rotation_zyx(shz_mat4x4_t* mat, float zAngle, float yAngle, float xAngle)` Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan Z-Y-X angles.
- [`shz_mat4x4_init_rotation_zxy`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_zxy/): `void shz_mat4x4_init_rotation_zxy(shz_mat4x4_t* mat, float zAngle, float xAngle, float yAngle)` Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan Z-X-Y angles.
- [`shz_mat4x4_init_rotation_yxz`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_yxz/): `void shz_mat4x4_init_rotation_yxz(shz_mat4x4_t* mat, float yAngle, float xAngle, float zAngle)` Initializes the given matrix to a 3D rotation matrix from the intrinsic rotation created by the given Tait-Bryan Y-X-Z angles.
- [`shz_mat4x4_init_rotation`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation/): `void shz_mat4x4_init_rotation(shz_mat4x4_t* mat, float radians, float xAxis, float yAxis, float zAxis)` Initializes the given 4x4 matrix to a 3D rotation matrix of `angle` radians about the vector with the given components.
- [`shz_mat4x4_init_rotation_dir`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_dir/): `void shz_mat4x4_init_rotation_dir(shz_mat4x4_t* mat, float angle, float x, float y, float z)` Initializes the given 4x4 matrix to contain a 3D rotation matrix of `angle` radians about the given direction.
- [`shz_mat4x4_init_rotation_quat`](https://sh4zam.com/api/matrix/shz_mat4x4_init_rotation_quat/): `void shz_mat4x4_init_rotation_quat(shz_mat4x4_t* m, shz_quat_t q)` Initializes the given matrix to a 3D rotation matrix with its orientation given by a quaternion.
- [`shz_mat4x4_init_diagonal`](https://sh4zam.com/api/matrix/shz_mat4x4_init_diagonal/): `void shz_mat4x4_init_diagonal(shz_mat4x4_t* mat, float x, float y, float z, float w)` Initializes the given matrix to a diagonal matrix with the given 4 values.
- [`shz_mat4x4_init_upper_triangular`](https://sh4zam.com/api/matrix/shz_mat4x4_init_upper_triangular/): `void shz_mat4x4_init_upper_triangular(shz_mat4x4_t* mat, float col1, shz_vec2_t col2, shz_vec3_t col3, shz_vec4_t col4)` Initializes the given matrix to an upper triangular matrix whose nonzero entries have the given value.
- [`shz_mat4x4_init_lower_triangular`](https://sh4zam.com/api/matrix/shz_mat4x4_init_lower_triangular/): `void shz_mat4x4_init_lower_triangular(shz_mat4x4_t* mat, shz_vec4_t col1, shz_vec3_t col2, shz_vec2_t col3, float col4)` Initializes the given matrix to a lower triangular matrix whose nonzero entries have the given value.
- [`shz_mat4x4_init_symmetric_skew`](https://sh4zam.com/api/matrix/shz_mat4x4_init_symmetric_skew/): `void shz_mat4x4_init_symmetric_skew(shz_mat4x4_t* mat, float x, float y, float z)` Initializes the given matrix to be the symmetric skew of the given 3D vector components.
- [`shz_mat4x4_init_outer_product`](https://sh4zam.com/api/matrix/shz_mat4x4_init_outer_product/): `void shz_mat4x4_init_outer_product(shz_mat4x4_t* mat, shz_vec4_t v1, shz_vec4_t v2)` Initializes the given matrix to be the result from taking the outer product of the two given 4D vectors.
- [`shz_mat4x4_init_permutation_wxyz`](https://sh4zam.com/api/matrix/shz_mat4x4_init_permutation_wxyz/): `void shz_mat4x4_init_permutation_wxyz(shz_mat4x4_t* mat)` Initializes the matrix to to a permutation matrix, which reorders the components of transformed vectors to be in WXYZ order.
- [`shz_mat4x4_init_permutation_yzwx`](https://sh4zam.com/api/matrix/shz_mat4x4_init_permutation_yzwx/): `void shz_mat4x4_init_permutation_yzwx(shz_mat4x4_t* mat)` Initializes the matrix to to a permutation matrix, which reorders the components of transformed vectors to be in YZWX order.
- [`shz_mat4x4_init_screen`](https://sh4zam.com/api/matrix/shz_mat4x4_init_screen/): `void shz_mat4x4_init_screen(shz_mat4x4_t* mat, float width, float height)` Initializes the given matrix to the viewport matrix with the given dimenions.
- [`shz_mat4x4_init_lookat`](https://sh4zam.com/api/matrix/shz_mat4x4_init_lookat/): `void shz_mat4x4_init_lookat(shz_mat4x4_t* mat, shz_vec3_t eye, shz_vec3_t center, shz_vec3_t up)` Initializes the given matrix to a "lookAt" view matrix.
- [`shz_mat4x4_init_ortho`](https://sh4zam.com/api/matrix/shz_mat4x4_init_ortho/): `void shz_mat4x4_init_ortho(shz_mat4x4_t* mat, float left, float right, float bottom, float top, float znear, float zfar)` Initializes the given matrix to an orthographic projection matrix.
- [`shz_mat4x4_init_frustum`](https://sh4zam.com/api/matrix/shz_mat4x4_init_frustum/): `void shz_mat4x4_init_frustum(shz_mat4x4_t* mat, float left, float right, float bottom, float top, float znear, float zfar)` Initializes the given matrix to a frustum projection matrix.
- [`shz_mat4x4_init_perspective`](https://sh4zam.com/api/matrix/shz_mat4x4_init_perspective/): `void shz_mat4x4_init_perspective(shz_mat4x4_t* mat, float fov, float aspect, float znear)` Initializes the given matrix to a perspective projection matrix.

### Matrix: Decomposition

- [`shz_mat4x4_decompose`](https://sh4zam.com/api/matrix/shz_mat4x4_decompose/): `void shz_mat4x4_decompose(const shz_mat4x4_t* mat, shz_vec3_t* translation, shz_quat_t* rotation, shz_vec3_t* scale)` Decomposes a 4x4 transform matrix into translation, rotation, and scale.

### Matrix: Getting

- [`shz_mat4x4_row`](https://sh4zam.com/api/matrix/shz_mat4x4_row/): `shz_vec4_t shz_mat4x4_row(const shz_mat4x4_t* mat, size_t row)` Extracts the `row` index as a 4D row vector from the given matrix.
- [`shz_mat4x4_col`](https://sh4zam.com/api/matrix/shz_mat4x4_col/): `shz_vec4_t shz_mat4x4_col(const shz_mat4x4_t* mat, size_t col)` Extracts the `col` index as a 4D column vector from the given matrix.
- [`shz_mat4x4_get_translation`](https://sh4zam.com/api/matrix/shz_mat4x4_get_translation/): `shz_vec3_t shz_mat4x4_get_translation(const shz_mat4x4_t* mat)` Returns the translational components from the 4th column as a 3D vector.
- [`shz_mat4x4_get_scale`](https://sh4zam.com/api/matrix/shz_mat4x4_get_scale/): `shz_vec3_t shz_mat4x4_get_scale(const shz_mat4x4_t* mat)` Exracts the 3D scale factors from the given 4x4 matrix.
- [`shz_mat4x4_determinant`](https://sh4zam.com/api/matrix/shz_mat4x4_determinant/): `float shz_mat4x4_determinant(const shz_mat4x4_t* mat)` Returns the determinant of the given 4x4 matrix.
- [`shz_mat4x4_trace`](https://sh4zam.com/api/matrix/shz_mat4x4_trace/): `float shz_mat4x4_trace(const shz_mat4x4_t* mat)` Returns the trace of the given 4x4 matrix.
- [`shz_mat4x4_3x3`](https://sh4zam.com/api/matrix/shz_mat4x4_3x3/): `void shz_mat4x4_3x3(const shz_mat4x4_t* mat4, shz_mat3x3_t* mat3)` Extracts the top-left 3x3 of the given 4D matrix.
- [`shz_mat4x4_3x3_inverse_unscaled`](https://sh4zam.com/api/matrix/shz_mat4x4_3x3_inverse_unscaled/): `void shz_mat4x4_3x3_inverse_unscaled(const shz_mat4x4_t* mat4, shz_mat3x3_t* invmat3)` Extracts and inverts the top-level, unscaled 3x3 of the given 4x4 matrix.
- [`shz_mat4x4_3x3_inverse`](https://sh4zam.com/api/matrix/shz_mat4x4_3x3_inverse/): `void shz_mat4x4_3x3_inverse(const shz_mat4x4_t* mat4, shz_mat3x3_t* invmat3)` Extracts and inverts the top-level 3x3 (which may be scaled) of the given 4x4 matrix.
- [`shz_mat4x4_3x3_determinant`](https://sh4zam.com/api/matrix/shz_mat4x4_3x3_determinant/): `float shz_mat4x4_3x3_determinant(const shz_mat4x4_t* mat)` Returns the determinant of the given 4x4 matrix's internal top-level 3x3 matrix.

### Matrix: Setting

- [`shz_mat4x4_set_row`](https://sh4zam.com/api/matrix/shz_mat4x4_set_row/): `void shz_mat4x4_set_row(shz_mat4x4_t* mat, size_t row, shz_vec4_t vec)` Sets the values of `mat` at the given `row` to those of the 4D vector, `vec`.
- [`shz_mat4x4_set_col`](https://sh4zam.com/api/matrix/shz_mat4x4_set_col/): `void shz_mat4x4_set_col(shz_mat4x4_t* mat, size_t col, shz_vec4_t vec)` Sets the values of `mat` at the given `col` to those of the 4D vector, `vec`.
- [`shz_mat4x4_swap_rows`](https://sh4zam.com/api/matrix/shz_mat4x4_swap_rows/): `void shz_mat4x4_swap_rows(shz_mat4x4_t* mat, size_t row1, size_t row2)` Swaps the 4D row vectors located at `row1` and `row2` within `mat`.
- [`shz_mat4x4_swap_cols`](https://sh4zam.com/api/matrix/shz_mat4x4_swap_cols/): `void shz_mat4x4_swap_cols(shz_mat4x4_t* mat, size_t col1, size_t col2)` Swaps the 4D column vectors located at `col1` and `col2` within `mat`.
- [`shz_mat4x4_set_translation`](https://sh4zam.com/api/matrix/shz_mat4x4_set_translation/): `void shz_mat4x4_set_translation(shz_mat4x4_t* mat, float x, float y, float z)` Assigns only the 3D translation-related elements of the given matrix to the given values.
- [`shz_mat4x4_set_scale`](https://sh4zam.com/api/matrix/shz_mat4x4_set_scale/): `void shz_mat4x4_set_scale(shz_mat4x4_t* mat, float x, float y, float z)` Assigns only the 3D scale-related elements of the given matrix to the given values.
- [`shz_mat4x4_set_rotation_quat`](https://sh4zam.com/api/matrix/shz_mat4x4_set_rotation_quat/): `void shz_mat4x4_set_rotation_quat(shz_mat4x4_t* m, shz_quat_t q)` Sets just the rotational component of the matrix to the orientation given by a quaternion, keeping the other elements in-tact.
- [`shz_mat4x4_set_diagonal`](https://sh4zam.com/api/matrix/shz_mat4x4_set_diagonal/): `void shz_mat4x4_set_diagonal(shz_mat4x4_t* mat, float x, float y, float z, float w)` Assigns only the 4 elements along the diagonal of the given matrix to the given values.

### Matrix: Applying

- [`shz_mat4x4_apply`](https://sh4zam.com/api/matrix/shz_mat4x4_apply/): `void shz_mat4x4_apply(shz_mat4x4_t* dst, const shz_mat4x4_t* src)` Multiplies and accumulates the `src` 4x4 matrix onto the `dst` 4x4 matrix.
- [`shz_mat4x4_apply_unaligned`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_unaligned/): `void shz_mat4x4_apply_unaligned(shz_mat4x4_t* dst, const float src[16])` Multiplies and accumulates the unaligned `src` 4x4 matrix onto the `dst` 4x4 matrix.
- [`shz_mat4x4_apply_transpose`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_transpose/): `void shz_mat4x4_apply_transpose(shz_mat4x4_t* dst, const shz_mat4x4_t* src)` Multiplies and accumulates the transposed `src` 4x4 matrix onto the `dst` 4x4 matrix.
- [`shz_mat4x4_apply_transpose_unaligned`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_transpose_unaligned/): `void shz_mat4x4_apply_transpose_unaligned(shz_mat4x4_t* dst, const float src[16])` Multiplies and accumulates the transposed unaligned `src` 4x4 matrix onto the `dst` 4x4 matrix.
- [`shz_mat4x4_apply_translation`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_translation/): `void shz_mat4x4_apply_translation(shz_mat4x4_t* mat, float x, float y, float z)` Adds the given 3D vector components to the translational values of the given matrix.
- [`shz_mat4x4_apply_scale`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_scale/): `void shz_mat4x4_apply_scale(shz_mat4x4_t* mat, float x, float y, float z)` Multiplies and accumulates the scale-related elements of the given matrix by the given 3D components.
- [`shz_mat4x4_apply_rotation_x`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_x/): `void shz_mat4x4_apply_rotation_x(shz_mat4x4_t* mat, float xAngle)` Multiplies and accumulates a rotation matrix by `xAngle` radians about the X-axis onto the given matrix.
- [`shz_mat4x4_apply_rotation_y`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_y/): `void shz_mat4x4_apply_rotation_y(shz_mat4x4_t* mat, float yAngle)` Multiplies and accumulates a rotation matrix by `yAngle` radians about the Y-axis onto the given matrix.
- [`shz_mat4x4_apply_rotation_z`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_z/): `void shz_mat4x4_apply_rotation_z(shz_mat4x4_t* mat, float zAngle)` Multiplies and accumulates a rotation matrix by `zAngle` radians about the Z-axis onto the given matrix.
- [`shz_mat4x4_apply_rotation_xyz`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_xyz/): `void shz_mat4x4_apply_rotation_xyz(shz_mat4x4_t* mat, float xAngle, float yAngle, float zAngle)` Rotates the given transform matrix about the X axis, then the Y axis, then the Z axis by the given angles in radians.
- [`shz_mat4x4_apply_rotation_zyx`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_zyx/): `void shz_mat4x4_apply_rotation_zyx(shz_mat4x4_t* mat, float zAngle, float yAngle, float xAngle)` Rotates the given transform matrix about the Z axis, then the Y axis, then the X axis by the given angles in radians.
- [`shz_mat4x4_apply_rotation_zxy`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_zxy/): `void shz_mat4x4_apply_rotation_zxy(shz_mat4x4_t* mat, float zAngle, float xAngle, float yAngle)` Rotates the given transform matrix about the Z axis, then the X axis, then the Y axis by the given angles in radians.
- [`shz_mat4x4_apply_rotation_yxz`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_yxz/): `void shz_mat4x4_apply_rotation_yxz(shz_mat4x4_t* mat, float yAngle, float xAngle, float zAngle)` Rotates the given transform matrix about the Y axis, then the X axis, then the Z axis by the given angles in radians.
- [`shz_mat4x4_apply_rotation`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation/): `void shz_mat4x4_apply_rotation(shz_mat4x4_t* mat, float angle, float xAxis, float yAxis, float zAxis)` Rotates the given transform matrix about the arbitrary axis given by a 3D direction vector and angle of rotation in radians.
- [`shz_mat4x4_apply_rotation_quat`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_rotation_quat/): `void shz_mat4x4_apply_rotation_quat(shz_mat4x4_t* m, shz_quat_t q)` Multiplies and accumulates the given matrix with a rotation matrix whose orientation is given by a quaternion.
- [`shz_mat4x4_apply_lookat`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_lookat/): `void shz_mat4x4_apply_lookat(shz_mat4x4_t* m, shz_vec3_t pos, shz_vec3_t target, shz_vec3_t up)` Applies the 3D "lookAt" matrix constructed with the given vector components onto the given matrix.
- [`shz_mat4x4_apply_ortho`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_ortho/): `void shz_mat4x4_apply_ortho(shz_mat4x4_t* m, float left, float right, float bottom, float top, float znear, float zfar)` Multiplies and accumulates the ortho matrix constructed from the given values onto the given matrix.
- [`shz_mat4x4_apply_frustum`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_frustum/): `void shz_mat4x4_apply_frustum(shz_mat4x4_t* m, float left, float right, float bottom, float top, float znear, float zfar)` Multiplies and accumulates the frustum matrix constructed from the given values onto the given matrix.
- [`shz_mat4x4_apply_perspective`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_perspective/): `void shz_mat4x4_apply_perspective(shz_mat4x4_t* m, float fov, float aspect, float znear)` Multiplies and accumulates the perspective matrix constructed from the given values onto the given matrix.
- [`shz_mat4x4_apply_screen`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_screen/): `void shz_mat4x4_apply_screen(shz_mat4x4_t* m, float width, float height)` Multiplies and accumulates the viewport matrix created with the given components ont othe given matrix.
- [`shz_mat4x4_apply_symmetric_skew`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_symmetric_skew/): `void shz_mat4x4_apply_symmetric_skew(shz_mat4x4_t* mat, float x, float y, float z)` Multiplies and accumulates the given matrix with a symmetric skew matrix formed from the given 3D vector components.
- [`shz_mat4x4_apply_permutation_wxyz`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_permutation_wxyz/): `void shz_mat4x4_apply_permutation_wxyz(shz_mat4x4_t* mat)` Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in WXYZ order.
- [`shz_mat4x4_apply_permutation_yzwx`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_permutation_yzwx/): `void shz_mat4x4_apply_permutation_yzwx(shz_mat4x4_t* mat)` Multiplies and accumulates a permutation matrix, which reorders the components of transformed vectors to be in YZWX order.
- [`shz_mat4x4_apply_self`](https://sh4zam.com/api/matrix/shz_mat4x4_apply_self/): `void shz_mat4x4_apply_self(shz_mat4x4_t* mat)` Multiplies and accumulates the given matrix onto itself.

### Matrix: GL Transformations

- [`shz_mat4x4_translate`](https://sh4zam.com/api/matrix/shz_mat4x4_translate/): `void shz_mat4x4_translate(shz_mat4x4_t* mat, float x, float y, float z)` Multiplies and accumulates `mat` by a 3D translation matrix with the given components.
- [`shz_mat4x4_scale`](https://sh4zam.com/api/matrix/shz_mat4x4_scale/): `void shz_mat4x4_scale(shz_mat4x4_t* mat, float x, float y, float z)` Multiplies and accumulates `mat` by a 3D scaling matrix with the given components.
- [`shz_mat4x4_rotate_x`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_x/): `void shz_mat4x4_rotate_x(shz_mat4x4_t* mat, float radians)` Multiplies and accumulates `mat` by a 3D rotation matrix about the X axis.
- [`shz_mat4x4_rotate_y`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_y/): `void shz_mat4x4_rotate_y(shz_mat4x4_t* mat, float radians)` Multiplies and accumulates `mat` by a 3D rotation matrix about the Y axis.
- [`shz_mat4x4_rotate_z`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_z/): `void shz_mat4x4_rotate_z(shz_mat4x4_t* mat, float radians)` Multiplies and accumulates `mat` by a 3D rotation matrix about the Z axis.
- [`shz_mat4x4_rotate_xyz`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_xyz/): `void shz_mat4x4_rotate_xyz(shz_mat4x4_t* mat, float xRadians, float yRadians, float zRadians)` Multiplies and accumulates `mat` by 3D rotation matrices about the X then Y then Z axes.
- [`shz_mat4x4_rotate_zyx`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_zyx/): `void shz_mat4x4_rotate_zyx(shz_mat4x4_t* mat, float zRadians, float yRadians, float xRadians)` Multiplies and accumulates `mat` by 3D rotation matrices about the Z then Y then X axes.
- [`shz_mat4x4_rotate_zxy`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_zxy/): `void shz_mat4x4_rotate_zxy(shz_mat4x4_t* mat, float zRadians, float xRadians, float yRadians)` Multiplies and accumulates `mat` by 3D rotation matrices about the Z then X then Y axes.
- [`shz_mat4x4_rotate_yxz`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate_yxz/): `void shz_mat4x4_rotate_yxz(shz_mat4x4_t* mat, float yRadians, float xRadians, float zRadians)` Multiplies and accumulates `mat` by 3D rotation matrices about the Y then X then Z axes.
- [`shz_mat4x4_rotate`](https://sh4zam.com/api/matrix/shz_mat4x4_rotate/): `void shz_mat4x4_rotate(shz_mat4x4_t* mat, float radians, float xAxis, float yAxis, float zAxis)` Multiplies and accumulates `mat` by the 3D rotation matrix formed by the given axis and angle.

### Matrix: Reverse GL Transformations

- [`shz_mat4x4_translate_reverse`](https://sh4zam.com/api/matrix/shz_mat4x4_translate_reverse/): `void shz_mat4x4_translate_reverse(shz_mat4x4_t* mat, float x, float y, float z)` Pre-multiplies and accumulates the given matrix onto the 3D translation matrix with the given components.
- [`shz_mat4x4_scale_reverse`](https://sh4zam.com/api/matrix/shz_mat4x4_scale_reverse/): `void shz_mat4x4_scale_reverse(shz_mat4x4_t* mat, float x, float y, float z)` Pre-multiplies and accumulates the given matrix onto the 3D scaling matrix with the given components.

### Matrix: Transforming

- [`shz_mat4x4_mult`](https://sh4zam.com/api/matrix/shz_mat4x4_mult/): `void shz_mat4x4_mult(shz_mat4x4_t* mat, const shz_mat4x4_t* lhs, const shz_mat4x4_t* rhs)` Multiplies two 4x4 matrices together, storing the result into a third.
- [`shz_mat4x4_mult_unaligned`](https://sh4zam.com/api/matrix/shz_mat4x4_mult_unaligned/): `void shz_mat4x4_mult_unaligned(shz_mat4x4_t* mat, const shz_mat4x4_t* lhs, const float rhs[16])` Multiplies two 4x4 matrices together, with the right handed matrix being unaligned, storing the result into a third.
- [`shz_mat4x4_mult_transpose`](https://sh4zam.com/api/matrix/shz_mat4x4_mult_transpose/): `void shz_mat4x4_mult_transpose(shz_mat4x4_t* mat, const shz_mat4x4_t* lhs, const shz_mat4x4_t* rhs)` Multiplies the regular matrix, `lhs`, by the transpose of the matrix, `rhs`, storing the result into `mat`.
- [`shz_mat4x4_mult_transpose_unaligned`](https://sh4zam.com/api/matrix/shz_mat4x4_mult_transpose_unaligned/): `void shz_mat4x4_mult_transpose_unaligned(shz_mat4x4_t* mat, const shz_mat4x4_t* lhs, const float rhs[16])` Multiplies the regular matrix, `lhs`, by the transpose of the unaligned matrix, `rhs`, storing the result into `mat`.
- [`shz_mat4x4_transform_vec2`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec2/): `shz_vec2_t shz_mat4x4_transform_vec2(const shz_mat4x4_t* m, shz_vec2_t v)` Transforms a 2D vector by a 4x4 matrix.
- [`shz_mat4x4_transform_vec3`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec3/): `shz_vec3_t shz_mat4x4_transform_vec3(const shz_mat4x4_t* m, shz_vec3_t v)` Transforms a 3D vector by a 4x4 matrix.
- [`shz_mat4x4_transform_vec4`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec4/): `shz_vec4_t shz_mat4x4_transform_vec4(const shz_mat4x4_t* mat, shz_vec4_t in)` Transforms a 4D vector by a 4x4 matrix.
- [`shz_mat4x4_transform_vec2_transpose`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec2_transpose/): `shz_vec2_t shz_mat4x4_transform_vec2_transpose(const shz_mat4x4_t* m, shz_vec2_t v)` Transforms a 2D vector the the transpose of a 4x4 matrix.
- [`shz_mat4x4_transform_vec3_transpose`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec3_transpose/): `shz_vec3_t shz_mat4x4_transform_vec3_transpose(const shz_mat4x4_t* m, shz_vec3_t v)` Transforms a 3D vector the the transpose of a 4x4 matrix.
- [`shz_mat4x4_transform_vec4_transpose`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_vec4_transpose/): `shz_vec4_t shz_mat4x4_transform_vec4_transpose(const shz_mat4x4_t* m, shz_vec4_t v)` Transforms a 4D vector the the transpose of a 4x4 matrix.
- [`shz_mat4x4_transform_point2`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_point2/): `shz_vec2_t shz_mat4x4_transform_point2(const shz_mat4x4_t* mat, shz_vec2_t pt)` Transforms a 2D point by a 4x4 matrix.
- [`shz_mat4x4_transform_point3`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_point3/): `shz_vec3_t shz_mat4x4_transform_point3(const shz_mat4x4_t* mat, shz_vec3_t pt)` Transforms a 3D point by a 4x4 matrix.
- [`shz_mat4x4_transform_point2_transpose`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_point2_transpose/): `shz_vec2_t shz_mat4x4_transform_point2_transpose(const shz_mat4x4_t* mat, shz_vec2_t pt)` Transforms a 2D point by the transpose of a 4x4 matrix.
- [`shz_mat4x4_transform_point3_transpose`](https://sh4zam.com/api/matrix/shz_mat4x4_transform_point3_transpose/): `shz_vec3_t shz_mat4x4_transform_point3_transpose(const shz_mat4x4_t* mat, shz_vec3_t pt)` Transforms a 3D point by the transpose of a 4x4 matrix.

### Matrix: Miscellaneous

- [`shz_mat4x4_to_quat`](https://sh4zam.com/api/matrix/shz_mat4x4_to_quat/): `shz_quat_t shz_mat4x4_to_quat(const shz_mat4x4_t* mat)` Converts the given 4x4 orientation matrix into a quaternion.
- [`shz_mat4x4_transpose`](https://sh4zam.com/api/matrix/shz_mat4x4_transpose/): `void shz_mat4x4_transpose(const shz_mat4x4_t* mat, shz_mat4x4_t* out)` Stores the transpose of `mat` within `out`.
- [`shz_mat4x4_inverse`](https://sh4zam.com/api/matrix/shz_mat4x4_inverse/): `void shz_mat4x4_inverse(const shz_mat4x4_t* SHZ_RESTRICT mtrx, shz_mat4x4_t* SHZ_RESTRICT out)` Computes the inverse of a 4x4 matrix.
- [`shz_mat4x4_inverse_block_triangular`](https://sh4zam.com/api/matrix/shz_mat4x4_inverse_block_triangular/): `void shz_mat4x4_inverse_block_triangular(const shz_mat4x4_t* mtx, shz_mat4x4_t* out)` Computes the inverse of a 4x4 matrix in block-triangular form.
- [`shz_mat4x4_equal`](https://sh4zam.com/api/matrix/shz_mat4x4_equal/): `bool shz_mat4x4_equal(const shz_mat4x4_t* SHZ_RESTRICT mat1, const shz_mat4x4_t* mat2)` Returns true if the two matrices are equal, based on either absolute or relative tolerance.
- [`shz_mat4x4_is_block_triangular`](https://sh4zam.com/api/matrix/shz_mat4x4_is_block_triangular/): `bool shz_mat4x4_is_block_triangular(const shz_mat4x4_t* mat)` Returns true if the given matrix is in block-triangular form: having a bottom row in the form of `<0.0f, 0.0f, 0.0f, w>`.
- [`shz_mat4x4_copy`](https://sh4zam.com/api/matrix/shz_mat4x4_copy/): `void shz_mat4x4_copy(shz_mat4x4_t* dst, const shz_mat4x4_t* src)` Copies the given `src` 4x4 matrix into the given `dst` 4x4 matrix.
- [`shz_mat4x4_copy_unaligned`](https://sh4zam.com/api/matrix/shz_mat4x4_copy_unaligned/): `void shz_mat4x4_copy_unaligned(shz_mat4x4_t* dst, const float src[16])` Copies the given unaligned `src` 4x4 matrix into the given `dst` 4x4 matrix.
- [`shz_mat4x4_swap`](https://sh4zam.com/api/matrix/shz_mat4x4_swap/): `void shz_mat4x4_swap(shz_mat4x4_t* matA, shz_mat4x4_t* matB)` Swaps the contents of the two given matrices, `matA` and `matB`.
- [`shz_mat4x4_blend`](https://sh4zam.com/api/matrix/shz_mat4x4_blend/): `void shz_mat4x4_blend(shz_mat4x4_t* dst, const shz_mat4x4_t* matrix, float weights)` Adds and accumulates a scaled 4x4 matrix into the given matrix.

### Matrix: Types

- [`shz_mat4x4_t`](https://sh4zam.com/api/matrix/shz_mat4x4_t/): `struct shz_mat4x4_t` Structure representing a 4x4 column-major matrix.
- [`shz_mat4x4`](https://sh4zam.com/api/matrix/shz_mat4x4/): `typedef shz_mat4x4_t shz_mat4x4` Alternate `shz_mat4x4_t` C typedef for those who hate POSIX style.
- [`shz_mat2x2_t`](https://sh4zam.com/api/matrix/shz_mat2x2_t/): `struct shz_mat2x2_t` Structure representing a 2x2 column-major matrix.
- [`shz_mat3x3_t`](https://sh4zam.com/api/matrix/shz_mat3x3_t/): `struct shz_mat3x3_t` Structure representing a 3x3 column-major matrix.
- [`shz_mat3x4_t`](https://sh4zam.com/api/matrix/shz_mat3x4_t/): `struct shz_mat3x4_t` Structure representing a 3x4 column-major matrix.
- [`shz_mat4x3_t`](https://sh4zam.com/api/matrix/shz_mat4x3_t/): `struct shz_mat4x3_t` Structure representing a 4x3 column-major matrix.

### Matrix: Functions

- [`shz_mat3x3_transpose`](https://sh4zam.com/api/matrix/shz_mat3x3_transpose/): `void shz_mat3x3_transpose(const shz_mat3x3_t* mat, shz_mat3x3_t* out)` Stores the transpose of 3x3 matrix `mat` within `out`.
- [`shz_mat3x3_inverse_unscaled`](https://sh4zam.com/api/matrix/shz_mat3x3_inverse_unscaled/): `void shz_mat3x3_inverse_unscaled(const shz_mat3x3_t* mat, shz_mat3x3_t* out)` Computes the inverse of an orthonormal 3x3 matrix.
- [`shz_mat3x3_inverse`](https://sh4zam.com/api/matrix/shz_mat3x3_inverse/): `void shz_mat3x3_inverse(const shz_mat3x3_t* mat, shz_mat3x3_t* out)` Computes the inverse of a 3x3 matrix.
- [`shz_mat3x3_scale`](https://sh4zam.com/api/matrix/shz_mat3x3_scale/): `void shz_mat3x3_scale(shz_mat3x3_t* dst, const shz_mat3x3_t* src, float value)` Uniformly scales each element within a 3x3 matrix by the given value.
- [`shz_mat3x3_transform_vec3`](https://sh4zam.com/api/matrix/shz_mat3x3_transform_vec3/): `shz_vec3_t shz_mat3x3_transform_vec3(const shz_mat3x3_t* m, shz_vec3_t v)` Transforms an input vector by a 3x3 matrix, returning the resulting vector.
- [`shz_mat3x3_transform_vec3_transpose`](https://sh4zam.com/api/matrix/shz_mat3x3_transform_vec3_transpose/): `shz_vec3_t shz_mat3x3_transform_vec3_transpose(const shz_mat3x3_t* m, shz_vec3_t v)` Transforms an input vector by the transpose of a 3x3 matrix, returning the resulting vector.

## XMTRX

`#include <sh4zam/shz_xmtrx.h>` · [module page](https://sh4zam.com/api/xmtrx/)

### XMTRX: Accessors

- [`shz_xmtrx_read`](https://sh4zam.com/api/xmtrx/shz_xmtrx_read/): `float shz_xmtrx_read(shz_xmtrx_reg_t xf)` Returns the floating-point value held within the given XMTRX register.
- [`shz_xmtrx_write`](https://sh4zam.com/api/xmtrx/shz_xmtrx_write/): `void shz_xmtrx_write(shz_xmtrx_reg_t xf, float value)` 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/): `shz_vec4_t shz_xmtrx_read_row(unsigned int index)` 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/): `shz_vec4_t shz_xmtrx_read_col(unsigned int index)` 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/): `void shz_xmtrx_write_row(unsigned int index, shz_vec4_t vector)` 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/): `void shz_xmtrx_write_col(unsigned int index, shz_vec4_t vector)` 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/): `void shz_xmtrx_swap_rows(unsigned int index1, unsigned int index2)` Swaps the values of the rows with the given indices.
- [`shz_xmtrx_swap_cols`](https://sh4zam.com/api/xmtrx/shz_xmtrx_swap_cols/): `void shz_xmtrx_swap_cols(unsigned int index1, unsigned int index2)` Swaps the values of the columns with the given indices.

### XMTRX: Loading

- [`shz_xmtrx_load_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_4x4/): `void shz_xmtrx_load_4x4(const shz_mat4x4_t* matrix)` Loads the given 4x4 matrix as XMTRX.
- [`shz_xmtrx_load_wxyz_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_wxyz_4x4/): `void shz_xmtrx_load_wxyz_4x4(const shz_mat4x4_t* matrix)` 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/): `void shz_xmtrx_load_unaligned_4x4(const float matrix[16])` 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/): `void shz_xmtrx_load_cols_4x4(const shz_vec4_t* c1, const shz_vec4_t* c2, const shz_vec4_t* c3, const shz_vec4_t* c4)` 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/): `void shz_xmtrx_load_rows_4x4(const shz_vec4_t* r1, const shz_vec4_t* r2, const shz_vec4_t* r3, const shz_vec4_t* r4)` 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/): `void shz_xmtrx_load_transpose_4x4(const shz_mat4x4_t* matrix)` 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/): `void shz_xmtrx_load_transpose_unaligned_4x4(const float matrix[16])` 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/): `void shz_xmtrx_load_3x4(const shz_mat3x4_t* matrix)` 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/): `void shz_xmtrx_load_transpose_3x4(const shz_mat3x4_t* matrix)` 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/): `void shz_xmtrx_load_cols_4x3(const shz_vec4_t* c1, const shz_vec4_t* c2, const shz_vec4_t* c3)` 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/): `void shz_xmtrx_load_rows_3x4(const shz_vec4_t* r1, const shz_vec4_t* r2, const shz_vec4_t* r3)` 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/): `void shz_xmtrx_load_cols_3x4(const shz_vec3_t* c1, const shz_vec3_t* c2, const shz_vec3_t* c3, const shz_vec3_t* c4)` 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/): `void shz_xmtrx_load_3x3(const shz_mat3x3_t* matrix)` 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/): `void shz_xmtrx_load_transpose_3x3(const shz_mat3x3_t* matrix)` 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/): `void shz_xmtrx_load_2x2(const shz_mat2x2_t* matrix)` Loads the given 2x2 matrix into XMTRX, initializing its remaining elements to identity.

### XMTRX: Storing

- [`shz_xmtrx_store_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_store_4x4/): `void shz_xmtrx_store_4x4(shz_mat4x4_t* matrix)` 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/): `void shz_xmtrx_store_unaligned_4x4(float matrix[16])` 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/): `void shz_xmtrx_store_transpose_4x4(shz_mat4x4_t* matrix)` 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/): `void shz_xmtrx_store_transpose_unaligned_4x4(float matrix[16])` 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/): `void shz_xmtrx_store_3x4(shz_mat3x4_t* matrix)` 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/): `void shz_xmtrx_store_transpose_3x4(shz_mat3x4_t* matrix)` 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/): `void shz_xmtrx_store_3x3(shz_mat3x3_t* matrix)` 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/): `void shz_xmtrx_store_transpose_3x3(shz_mat3x3_t* matrix)` 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/): `void shz_xmtrx_store_2x2(shz_mat2x2_t* matrix)` Stores the top-left 2x2 values currently held within XMTRX into the given matrix.

### XMTRX: Initialization

- [`shz_xmtrx_init_identity`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_identity/): `void shz_xmtrx_init_identity(void)` Initializes XMTRX to the 4x4 identity matrix.
- [`shz_xmtrx_init_identity_safe`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_identity_safe/): `void shz_xmtrx_init_identity_safe(void)` Safely initializes XMTRX to be a 4D identity matrix.
- [`shz_xmtrx_init_zero`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_zero/): `void shz_xmtrx_init_zero(void)` 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/): `void shz_xmtrx_init_one(void)` 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/): `void shz_xmtrx_init_fill(float value)` Initializes XMTRX to contain the given `value` for each element.
- [`shz_xmtrx_init_translation`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_translation/): `void shz_xmtrx_init_translation(float x, float y, float z)` 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/): `void shz_xmtrx_init_scale(float x, float y, float z)` 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/): `void shz_xmtrx_init_rotation_x(float 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/): `void shz_xmtrx_init_rotation_y(float 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/): `void shz_xmtrx_init_rotation_z(float 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/): `void shz_xmtrx_init_rotation_xyz(float xAngle, float yAngle, float zAngle)` 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/): `void shz_xmtrx_init_rotation_zyx(float zAngle, float yAngle, float xAngle)` 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/): `void shz_xmtrx_init_rotation_zxy(float zAngle, float xAngle, float yAngle)` 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/): `void shz_xmtrx_init_rotation_yxz(float yAngle, float xAngle, float zAngle)` 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/): `void shz_xmtrx_init_rotation(float angle, float xAxis, float yAxis, float zAxis)` 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/): `void shz_xmtrx_init_rotation_dir(float angle, float x, float y, float z)` 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/): `void shz_xmtrx_init_diagonal(float x, float y, float z, float w)` 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/): `void shz_xmtrx_init_upper_triangular(float col1, shz_vec2_t col2, shz_vec3_t col3, shz_vec4_t col4)` 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/): `void shz_xmtrx_init_lower_triangular(shz_vec4_t col1, shz_vec3_t col2, shz_vec2_t col3, float col4)` 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/): `void shz_xmtrx_init_symmetric_skew(float x, float y, float z)` 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/): `void shz_xmtrx_init_outer_product(shz_vec4_t x, shz_vec4_t y)` 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/): `void shz_xmtrx_init_permutation_wxyz(void)` 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/): `void shz_xmtrx_init_permutation_yzwx(void)` 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/): `void shz_xmtrx_init_permutation_wzyx(void)` 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/): `void shz_xmtrx_init_screen(float width, float height)` Initializes XMTRX to the viewport matrix with the given dimensions.
- [`shz_xmtrx_init_lookat`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_lookat/): `void shz_xmtrx_init_lookat(shz_vec3_t eye, shz_vec3_t center, shz_vec3_t up)` Initializes XMTRX to a "lookAt" view matrix, equivalent to gluLookAt().
- [`shz_xmtrx_init_ortho`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_ortho/): `void shz_xmtrx_init_ortho(float left, float right, float bottom, float top, float znear, float zfar)` Initializes XMTRX to an orthographic projection matrix, equivalent to glOrtho().
- [`shz_xmtrx_init_frustum`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_frustum/): `void shz_xmtrx_init_frustum(float left, float right, float bottom, float top, float znear, float zfar)` Initializes XMTRX to a frustum projection matrix, equivalent to glFrustum().
- [`shz_xmtrx_init_perspective`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_perspective/): `void shz_xmtrx_init_perspective(float fov, float aspect, float znear)` Initializes XMTRX to a perspective projection matrix.
- [`shz_xmtrx_init_rotation_quat`](https://sh4zam.com/api/xmtrx/shz_xmtrx_init_rotation_quat/): `void shz_xmtrx_init_rotation_quat(shz_quat_t q)` Initializes XMTRX to a 3D rotation matrix with its orientation given by a quaternion.

### XMTRX: Apply Operation

- [`shz_xmtrx_apply_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_4x4/): `void shz_xmtrx_apply_4x4(const shz_mat4x4_t* matrix)` Multiplies and accumulates the given 4x4 matrix onto XMTRX.
- [`shz_xmtrx_apply_unaligned_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_unaligned_4x4/): `void shz_xmtrx_apply_unaligned_4x4(const float matrix[16])` 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/): `void shz_xmtrx_apply_transpose_4x4(const shz_mat4x4_t* matrix)` 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/): `void shz_xmtrx_apply_transpose_unaligned_4x4(const float matrix[16])` 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/): `void shz_xmtrx_apply_reverse_4x4(const shz_mat4x4_t* matrix)` 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/): `void shz_xmtrx_apply_reverse_unaligned_4x4(const float matrix[16])` 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/): `void shz_xmtrx_apply_reverse_transpose_4x4(const shz_mat4x4_t* matrix)` 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/): `void shz_xmtrx_apply_reverse_transpose_unaligned_4x4(const float matrix[16])` 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/): `void shz_xmtrx_apply_3x4(const shz_mat3x4_t* matrix)` 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/): `void shz_xmtrx_apply_transpose_3x4(const shz_mat3x4_t* matrix)` 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/): `void shz_xmtrx_apply_reverse_3x4(const shz_mat3x4_t* mat)` 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/): `void shz_xmtrx_apply_reverse_transpose_3x4(const shz_mat3x4_t* mat)` 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/): `void shz_xmtrx_apply_3x3(const shz_mat3x3_t* matrix)` 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/): `void shz_xmtrx_apply_transpose_3x3(const shz_mat3x3_t* matrix)` 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/): `void shz_xmtrx_apply_2x2(const shz_mat2x2_t* matrix)` 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/): `void shz_xmtrx_apply_translation(float x, float y, float z)` 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/): `void shz_xmtrx_apply_scale(float x, float y, float z)` 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/): `void shz_xmtrx_apply_rotation_x(float 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/): `void shz_xmtrx_apply_rotation_y(float 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/): `void shz_xmtrx_apply_rotation_z(float 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/): `void shz_xmtrx_apply_rotation_xyz(float xAngle, float yAngle, float zAngle)` 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/): `void shz_xmtrx_apply_rotation_zyx(float zAngle, float yAngle, float xAngle)` 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/): `void shz_xmtrx_apply_rotation_zxy(float zAngle, float xAngle, float yAngle)` 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/): `void shz_xmtrx_apply_rotation_yxz(float yAngle, float xAngle, float zAngle)` 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/): `void shz_xmtrx_apply_rotation(float angle, float x, float y, float z)` 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/): `void shz_xmtrx_apply_rotation_quat(shz_quat_t 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/): `void shz_xmtrx_apply_lookat(shz_vec3_t eye, shz_vec3_t center, shz_vec3_t up)` 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/): `void shz_xmtrx_apply_ortho(float left, float right, float bottom, float top, float znear, float zfar)` Applies a 2D orthographic projection matrix onto XMTRX, equivalent to glOrtho().
- [`shz_xmtrx_apply_frustum`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_frustum/): `void shz_xmtrx_apply_frustum(float left, float right, float bottom, float top, float znear, float zfar)` Applies a frustum projection matrix onto XMTRX, equivalent to glFrustum().
- [`shz_xmtrx_apply_perspective`](https://sh4zam.com/api/xmtrx/shz_xmtrx_apply_perspective/): `void shz_xmtrx_apply_perspective(float fov, float aspect, float znear)` 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/): `void shz_xmtrx_apply_screen(float width, float height)` 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/): `void shz_xmtrx_apply_symmetric_skew(float x, float y, float z)` 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/): `void shz_xmtrx_apply_permutation_wxyz(void)` 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/): `void shz_xmtrx_apply_permutation_yzwx(void)` 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/): `void shz_xmtrx_apply_permutation_wzyx(void)` 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/): `void shz_xmtrx_apply_self(void)` Multiplies and accumulatse the XMTRX matrix by itself, squaring it.

### XMTRX: GL Transformations

- [`shz_xmtrx_translate`](https://sh4zam.com/api/xmtrx/shz_xmtrx_translate/): `void shz_xmtrx_translate(float x, float y, float z)` 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/): `void shz_xmtrx_scale(float x, float y, float z)` 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/): `void shz_xmtrx_rotate_x(float radians)` 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/): `void shz_xmtrx_rotate_y(float radians)` 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/): `void shz_xmtrx_rotate_z(float radians)` 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/): `void shz_xmtrx_rotate_xyz(float xRadians, float yRadians, float zRadians)` 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/): `void shz_xmtrx_rotate_zyx(float zRadians, float yRadians, float xRadians)` 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/): `void shz_xmtrx_rotate_zxy(float zRadians, float xRadians, float yRadians)` 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/): `void shz_xmtrx_rotate_yxz(float yRadians, float xRadians, float zRadians)` 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/): `void shz_xmtrx_rotate(float radians, float xAxis, float yAxis, float zAxis)` Multiplies and accumulates XMTRX by the 3D rotation matrix formed by the given axis and angle (glRotatef equivalent).

### XMTRX: Reverse GL Transformations

- [`shz_xmtrx_translate_reverse`](https://sh4zam.com/api/xmtrx/shz_xmtrx_translate_reverse/): `void shz_xmtrx_translate_reverse(float x, float y, float z)` 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/): `void shz_xmtrx_scale_reverse(float x, float y, float z)` Pre-multiplies and accumulates XMTRX onto the 3D scaling matrix with the given components.

### XMTRX: Compound Operations

- [`shz_xmtrx_load_apply_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_load_apply_4x4/): `void shz_xmtrx_load_apply_4x4(const shz_mat4x4_t* matrix1, const shz_mat4x4_t* matrix2)` 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/): `void shz_xmtrx_load_apply_unaligned_4x4(const float matrix1[16], const float matrix2[16])` 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/): `void shz_xmtrx_apply_store_4x4(shz_mat4x4_t* out, const shz_mat4x4_t* in)` 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/): `void shz_xmtrx_apply_store_unaligned_4x4(float out[16], const float in[16])` 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/): `void shz_xmtrx_load_apply_store_4x4(shz_mat4x4_t* out, const shz_mat4x4_t* matrix1, const shz_mat4x4_t* matrix2)` 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/): `void shz_xmtrx_load_apply_store_unaligned_4x4(float out[16], const float matrix1[16], const float matrix2[16])` 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/): `void shz_xmtrx_load_apply_3x4(const shz_mat3x4_t* matrix1, const shz_mat3x4_t* matrix2)` 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/): `void shz_xmtrx_load_apply_store_3x4(shz_mat3x4_t* out, const shz_mat3x4_t* matrix1, const shz_mat3x4_t* matrix2)` 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/): `void shz_xmtrx_load_apply_store_3x3(shz_mat3x3_t* out, const shz_mat3x3_t* matrix1, const shz_mat3x3_t* matrix2)` Loads XMTRX with the 3x3 result of applying `matrix2` onto `matrix1`, storing the result.

### XMTRX: Transformations

- [`shz_xmtrx_transform_vec4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transform_vec4/): `shz_vec4_t shz_xmtrx_transform_vec4(shz_vec4_t vec)` 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/): `shz_vec3_t shz_xmtrx_transform_vec3(shz_vec3_t vec)` 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/): `shz_vec2_t shz_xmtrx_transform_vec2(shz_vec2_t vec)` 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/): `shz_vec2_t shz_xmtrx_transform_point2(shz_vec2_t pt)` 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/): `shz_vec3_t shz_xmtrx_transform_point3(shz_vec3_t pt)` Returns the 3D point that is the result of transforming `pt` by XMTRX.

### XMTRX: Setters

- [`shz_xmtrx_set_translation`](https://sh4zam.com/api/xmtrx/shz_xmtrx_set_translation/): `void shz_xmtrx_set_translation(float x, float y, float z)` Sets only the translational components of XMTRX to the given values.
- [`shz_xmtrx_set_scale`](https://sh4zam.com/api/xmtrx/shz_xmtrx_set_scale/): `void shz_xmtrx_set_scale(float x, float y, float z)` Sets only the inner 3x3 submatrix of XMTRX to be a scaling matrix.

### XMTRX: Getters

- [`shz_xmtrx_get_translation`](https://sh4zam.com/api/xmtrx/shz_xmtrx_get_translation/): `shz_vec3_t shz_xmtrx_get_translation(void)` 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/): `shz_vec3_t shz_xmtrx_get_scale(void)` Returns the scaling components from the inner 3x3 matrix of XMTRX, as a 3D vector.

### XMTRX: Component-Wise Matrix Operations

- [`shz_xmtrx_add_4x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_add_4x4/): `void shz_xmtrx_add_4x4(const shz_mat4x4_t* mat)` 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/): `void shz_xmtrx_sub_4x4(const shz_mat4x4_t* mat)` Subtracts each element within `mat` from each element within XMTRX, storing the result in XMTRX.

### XMTRX: Miscellaneous

- [`shz_xmtrx_transpose`](https://sh4zam.com/api/xmtrx/shz_xmtrx_transpose/): `void shz_xmtrx_transpose(void)` Transposes the elements within XMTRX, in-place.
- [`shz_xmtrx_negate`](https://sh4zam.com/api/xmtrx/shz_xmtrx_negate/): `void shz_xmtrx_negate(void)` Negates each element held within XMTRX.
- [`shz_xmtrx_abs`](https://sh4zam.com/api/xmtrx/shz_xmtrx_abs/): `void shz_xmtrx_abs(void)` Takes the absolute value of each element held within XMTRX.
- [`shz_xmtrx_to_quat`](https://sh4zam.com/api/xmtrx/shz_xmtrx_to_quat/): `shz_quat_t shz_xmtrx_to_quat(void)` Constructs a quaternion from the 3D rotation matrix within XMTRX.
- [`shz_xmtrx_determinant`](https://sh4zam.com/api/xmtrx/shz_xmtrx_determinant/): `float shz_xmtrx_determinant(void)` Returns the determinant of XMTRX.
- [`shz_xmtrx_invert`](https://sh4zam.com/api/xmtrx/shz_xmtrx_invert/): `void shz_xmtrx_invert(void)` Inverts XMTRX in-place.
- [`shz_xmtrx_blend`](https://sh4zam.com/api/xmtrx/shz_xmtrx_blend/): `void shz_xmtrx_blend(const shz_mat4x4_t* matrix, float weight)` 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/): `void shz_xmtrx_blend_4x4(const shz_mat4x4_t* matrix, float weight)` Adds and accumulates a scaled 4x4 matrix onto XMTRX.
- [`shz_xmtrx_blend_3x4`](https://sh4zam.com/api/xmtrx/shz_xmtrx_blend_3x4/): `void shz_xmtrx_blend_3x4(const shz_mat3x4_t* matrix, float weight)` Adds and accumulates a scaled 3x4 matrix onto XMTRX.

### XMTRX: Enumerations

- [`shz_xmtrx_reg`](https://sh4zam.com/api/xmtrx/shz_xmtrx_reg/): `enum shz_xmtrx_reg` Registers comprising XMTRX, in the FPU back-bank.

## Complex

`#include <sh4zam/shz_complex.h>` · [module page](https://sh4zam.com/api/complex/)

### Complex: Preprocessor

- [`SHZ_CMPLXF`](https://sh4zam.com/api/complex/SHZ_CMPLXF/): `#define SHZ_CMPLXF(x, y) shz_cinitf(x, y)` Initializes a complex number.
- [`SHZ_CMPLXF32`](https://sh4zam.com/api/complex/SHZ_CMPLXF32/): `#define SHZ_CMPLXF32(x, y) SHZ_CMPLXF(x, y)` Initializes a complex number.
- [`SHZ_I`](https://sh4zam.com/api/complex/SHZ_I/): `#define SHZ_I SHZ_CMPLXF32(0.0f, 1.0f)` Unit imaginary constant, 'I'.

### Complex: Basic

- [`shz_cinitf`](https://sh4zam.com/api/complex/shz_cinitf/): `shz_complex_t shz_cinitf(float real, float imag)` Returns a complex number which has been initialized to contain the given component values.
- [`shz_cpolarf`](https://sh4zam.com/api/complex/shz_cpolarf/): `shz_complex_t shz_cpolarf(float r, float theta)` Returns a complex number with a magnitude of `r`, and a phase angle of `theta` (in radians).
- [`shz_cequalf`](https://sh4zam.com/api/complex/shz_cequalf/): `bool shz_cequalf(shz_complex_t lhs, shz_complex_t rhs)` Checks for equality between two complex numbers with either an absolute or relative tolerance.
- [`shz_crealf`](https://sh4zam.com/api/complex/shz_crealf/): `float shz_crealf(shz_complex_t c)` Returns the real component of a complex number.
- [`shz_cimagf`](https://sh4zam.com/api/complex/shz_cimagf/): `float shz_cimagf(shz_complex_t c)` Returns the imaginary component of a complex number.

### Complex: Arithmetic

- [`shz_caddf`](https://sh4zam.com/api/complex/shz_caddf/): `shz_complex_t shz_caddf(shz_complex_t lhs, shz_complex_t rhs)` Adds two complex numbers together and returns the result.
- [`shz_csubf`](https://sh4zam.com/api/complex/shz_csubf/): `shz_complex_t shz_csubf(shz_complex_t lhs, shz_complex_t rhs)` Subtracts `rhs` from `lhs` and returns the complex result.
- [`shz_cmulf`](https://sh4zam.com/api/complex/shz_cmulf/): `shz_complex_t shz_cmulf(shz_complex_t lhs, shz_complex_t rhs)` Multiplies two complex numbers together, returning the complex result.
- [`shz_cdivf`](https://sh4zam.com/api/complex/shz_cdivf/): `shz_complex_t shz_cdivf(shz_complex_t lhs, shz_complex_t rhs)` Divides `lhs` by `rhs`, returning the complex result.
- [`shz_cscalef`](https://sh4zam.com/api/complex/shz_cscalef/): `shz_complex_t shz_cscalef(shz_complex_t c, float v)` Scales both componets of the complex number, `c`, by the value, `v`, returning the result.
- [`shz_crecipf`](https://sh4zam.com/api/complex/shz_crecipf/): `shz_complex_t shz_crecipf(shz_complex_t c)` Returns the multiplicative inverse or reciprocal of the complex number, `c`.

### Complex: Manipulation

- [`shz_cabsf`](https://sh4zam.com/api/complex/shz_cabsf/): `float shz_cabsf(shz_complex_t c)` Returns the absolute value (or magnitude) of the complex number, `c`.
- [`shz_inv_cabsf`](https://sh4zam.com/api/complex/shz_inv_cabsf/): `float shz_inv_cabsf(shz_complex_t c)` Returns the inverse of the absolute value (or inverse of the magnitude) of the complex number, `c`.
- [`shz_cnormf`](https://sh4zam.com/api/complex/shz_cnormf/): `float shz_cnormf(shz_complex_t c)` Returns the squared magnitude of the complex number, `c`.
- [`shz_cargf`](https://sh4zam.com/api/complex/shz_cargf/): `float shz_cargf(shz_complex_t c)` Returns the phase angle of the complex number, `c`.
- [`shz_conjf`](https://sh4zam.com/api/complex/shz_conjf/): `shz_complex_t shz_conjf(shz_complex_t c)` Returns the complex conjugate of `c`.
- [`shz_cprojf`](https://sh4zam.com/api/complex/shz_cprojf/): `shz_complex_t shz_cprojf(shz_complex_t c)` Calculates the projection of the complex number, `c`, onto the Riemann sphere.

### Complex: Transcendental

- [`shz_csqrtf`](https://sh4zam.com/api/complex/shz_csqrtf/): `shz_complex_t shz_csqrtf(shz_complex_t c)` Computes and returns the complex square root of `c`.
- [`shz_cpowf`](https://sh4zam.com/api/complex/shz_cpowf/): `shz_complex_t shz_cpowf(shz_complex_t base, shz_complex_t exp)` Raises the complex `base` to the complex `exp` power, returning a complex result.
- [`shz_cexpf`](https://sh4zam.com/api/complex/shz_cexpf/): `shz_complex_t shz_cexpf(shz_complex_t c)` Returns the complex base `e` exponential of `c`.
- [`shz_clogf`](https://sh4zam.com/api/complex/shz_clogf/): `shz_complex_t shz_clogf(shz_complex_t c)` Computes and returns the complex natural logarithm of `c`.
- [`shz_clog10f`](https://sh4zam.com/api/complex/shz_clog10f/): `shz_complex_t shz_clog10f(shz_complex_t c)` Computes and returns the complex base 10 logarithm of `c`.

### Complex: Spherical Trigonometry

- [`shz_csinf`](https://sh4zam.com/api/complex/shz_csinf/): `shz_complex_t shz_csinf(shz_complex_t c)` Calculates and returns the complex sine of `c`.
- [`shz_ccosf`](https://sh4zam.com/api/complex/shz_ccosf/): `shz_complex_t shz_ccosf(shz_complex_t c)` Calculates and returns the complex cosine of `c`.
- [`shz_ctanf`](https://sh4zam.com/api/complex/shz_ctanf/): `shz_complex_t shz_ctanf(shz_complex_t c)` Calculates and returns the complex tangent of `c`.
- [`shz_ccscf`](https://sh4zam.com/api/complex/shz_ccscf/): `shz_complex_t shz_ccscf(shz_complex_t c)` Calculates and returns the complex cosecant of `c`.
- [`shz_csecf`](https://sh4zam.com/api/complex/shz_csecf/): `shz_complex_t shz_csecf(shz_complex_t c)` Calculates and returns the complex secant of `c`.
- [`shz_ccotf`](https://sh4zam.com/api/complex/shz_ccotf/): `shz_complex_t shz_ccotf(shz_complex_t c)` Calculates and returns the complex cotangent of `c`.
- [`shz_casinf`](https://sh4zam.com/api/complex/shz_casinf/): `shz_complex_t shz_casinf(shz_complex_t c)` Calculates and returns the complex arcsine of `c`.
- [`shz_cacosf`](https://sh4zam.com/api/complex/shz_cacosf/): `shz_complex_t shz_cacosf(shz_complex_t c)` Calculates and returns the complex arccosine of `c`.
- [`shz_catanf`](https://sh4zam.com/api/complex/shz_catanf/): `shz_complex_t shz_catanf(shz_complex_t c)` Calculates and returns the complex arctangent of `c`.
- [`shz_cacscf`](https://sh4zam.com/api/complex/shz_cacscf/): `shz_complex_t shz_cacscf(shz_complex_t c)` Calculates and returns the complex arccosecant of `c`.
- [`shz_casecf`](https://sh4zam.com/api/complex/shz_casecf/): `shz_complex_t shz_casecf(shz_complex_t c)` Calculates and returns the complex arcsecant of `c`.
- [`shz_cacotf`](https://sh4zam.com/api/complex/shz_cacotf/): `shz_complex_t shz_cacotf(shz_complex_t c)` Calculates and returns the complex arccotangent of `c`.

### Complex: Hyperbolic Trigonometry

- [`shz_csinhf`](https://sh4zam.com/api/complex/shz_csinhf/): `shz_complex_t shz_csinhf(shz_complex_t c)` Calculates and returns the complex hyperbolic sine of `c`.
- [`shz_ccoshf`](https://sh4zam.com/api/complex/shz_ccoshf/): `shz_complex_t shz_ccoshf(shz_complex_t c)` Calculates and returns the complex hyperbolic cosine of `c`.
- [`shz_ctanhf`](https://sh4zam.com/api/complex/shz_ctanhf/): `shz_complex_t shz_ctanhf(shz_complex_t c)` Calculates and returns the complex hyperbolic tangent of `c`.
- [`shz_ccschf`](https://sh4zam.com/api/complex/shz_ccschf/): `shz_complex_t shz_ccschf(shz_complex_t c)` Calculates and returns the complex hyperbolic cosecant of `c`.
- [`shz_csechf`](https://sh4zam.com/api/complex/shz_csechf/): `shz_complex_t shz_csechf(shz_complex_t c)` Calculates and returns the complex hyperbolic secant of `c`.
- [`shz_ccothf`](https://sh4zam.com/api/complex/shz_ccothf/): `shz_complex_t shz_ccothf(shz_complex_t c)` Calculates and returns the complex hyperbolic cotangent of `c`.
- [`shz_casinhf`](https://sh4zam.com/api/complex/shz_casinhf/): `shz_complex_t shz_casinhf(shz_complex_t c)` Calculates and returns the complex hyperbolic arcsine of `c`.
- [`shz_cacoshf`](https://sh4zam.com/api/complex/shz_cacoshf/): `shz_complex_t shz_cacoshf(shz_complex_t c)` Calculates and returns the complex hyperbolic arccosine of `c`.
- [`shz_catanhf`](https://sh4zam.com/api/complex/shz_catanhf/): `shz_complex_t shz_catanhf(shz_complex_t c)` Calculates and returns the complex hyperbolic arctangent of `c`.
- [`shz_cacschf`](https://sh4zam.com/api/complex/shz_cacschf/): `shz_complex_t shz_cacschf(shz_complex_t c)` Calculates and returns the complex hyperbolic arccosecant of `c`.
- [`shz_casechf`](https://sh4zam.com/api/complex/shz_casechf/): `shz_complex_t shz_casechf(shz_complex_t c)` Calculates and returns the complex hyperbolic arcsecant of `c`.
- [`shz_cacothf`](https://sh4zam.com/api/complex/shz_cacothf/): `shz_complex_t shz_cacothf(shz_complex_t c)` Calculates and returns the complex hyperbolic arccotangent of `c`.

### Complex: Signal Processing

- [`shz_fft`](https://sh4zam.com/api/complex/shz_fft/): `void shz_fft(shz_complex_t* s, size_t size)` Fast Fourier Transform.

### Complex: Types

- [`shz_complex_t`](https://sh4zam.com/api/complex/shz_complex_t/): `struct shz_complex_t` Represents a floating-point complex number real/imaginary pair.
- [`shz_complex`](https://sh4zam.com/api/complex/shz_complex/): `typedef shz_complex_t shz_complex` `shz_complex_t` alias for those who don't like POSIX-style.

## Memory

`#include <sh4zam/shz_mem.h>` · [module page](https://sh4zam.com/api/memory/)

### Memory: C stdlib Replacements

- [`shz_memcpy`](https://sh4zam.com/api/memory/shz_memcpy/): `void* shz_memcpy( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes)` Generic drop-in fast memcpy() replacement.
- [`shz_memmove`](https://sh4zam.com/api/memory/shz_memmove/): `void* shz_memmove(void* dst, const void* src, size_t bytes)` Generic drop-in fast memmove() replacement.

### Memory: Specializations

- [`shz_memcpy1`](https://sh4zam.com/api/memory/shz_memcpy1/): `void* shz_memcpy1( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes)` Copies an unaligned buffer to another one byte at a time.
- [`shz_memcpy2`](https://sh4zam.com/api/memory/shz_memcpy2/): `void* shz_memcpy2( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes)` Copies from one 2-byte aligned buffer to another two bytes at a time.
- [`shz_memcpy4`](https://sh4zam.com/api/memory/shz_memcpy4/): `void* shz_memcpy4( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes)` Copies a from one 4-byte aligned buffer to another 4 bytes at a time.
- [`shz_memcpy8`](https://sh4zam.com/api/memory/shz_memcpy8/): `void* shz_memcpy8( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes)` Copies a from one 8-byte aligned buffer to another 8 bytes at a time.
- [`shz_memset8`](https://sh4zam.com/api/memory/shz_memset8/): `void* shz_memset8(void* dst, uint64_t value, size_t bytes)` Assigns the given 8-byte `value` to the `bytes` in `dst`.
- [`shz_memcpy32`](https://sh4zam.com/api/memory/shz_memcpy32/): `void* shz_memcpy32( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes)` Copies `bytes` from the `src` to the `dst` buffer in 32-byte chunks.
- [`shz_sq_memcpy32`](https://sh4zam.com/api/memory/shz_sq_memcpy32/): `void* shz_sq_memcpy32( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes)` Copies `bytes` from `src` to `dst` in 32-byte chunks, using the Store Queues.
- [`shz_sq_memcpy32_xmtrx`](https://sh4zam.com/api/memory/shz_sq_memcpy32_xmtrx/): `void* shz_sq_memcpy32_xmtrx( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes)` Copies `bytes` from `src` to `dst` in 32-byte chunks, using the Store Queues and XMTRX.
- [`shz_memcpy64`](https://sh4zam.com/api/memory/shz_memcpy64/): `void* shz_memcpy64( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes)` Specialized memcpy() variant for copying multiples of 64-bytes.
- [`shz_memcpy128`](https://sh4zam.com/api/memory/shz_memcpy128/): `void* shz_memcpy128( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src, size_t bytes)` Specialized memcpy() variant for copying multiples of 128 bytes.

### Memory: Constant-sized Operations

- [`shz_memcpy2_8`](https://sh4zam.com/api/memory/shz_memcpy2_8/): `void shz_memcpy2_8( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src)` Copies 8 shorts from `src` to `dst`.
- [`shz_memcpy2_16`](https://sh4zam.com/api/memory/shz_memcpy2_16/): `void shz_memcpy2_16( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src)` Copies 16 shorts from `src` to `dst`.
- [`shz_memset2_16`](https://sh4zam.com/api/memory/shz_memset2_16/): `void shz_memset2_16(void* dst, uint16_t value)` Sets the values of the 16 shorts pointed to by `dst` to the given `value`.
- [`shz_memcpy4_16`](https://sh4zam.com/api/memory/shz_memcpy4_16/): `void shz_memcpy4_16( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src)` Copies 16 4-byte, long values from `src` to `dst`.
- [`shz_memcpy32_1`](https://sh4zam.com/api/memory/shz_memcpy32_1/): `void shz_memcpy32_1( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src)` Copies 32 bytes from `p1` to `p2` as a single chunk.
- [`shz_memswap32_1`](https://sh4zam.com/api/memory/shz_memswap32_1/): `void shz_memswap32_1(void* SHZ_RESTRICT p1, void* SHZ_RESTRICT p2)` Swaps the values within the given 32-byte buffers.
- [`shz_memswap32_1_xmtrx`](https://sh4zam.com/api/memory/shz_memswap32_1_xmtrx/): `void shz_memswap32_1_xmtrx(void* SHZ_RESTRICT p1, void* SHZ_RESTRICT p2)` Swaps the values within the given 32-byte buffers, using XMTRX.
- [`shz_sq_memcpy32_1`](https://sh4zam.com/api/memory/shz_sq_memcpy32_1/): `void* shz_sq_memcpy32_1( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src)` Copies `src` to `dst` in a single 32-byte transaction using the Store Queues.
- [`shz_sq_memcpy32_1_xmtrx`](https://sh4zam.com/api/memory/shz_sq_memcpy32_1_xmtrx/): `void* shz_sq_memcpy32_1_xmtrx( void* SHZ_RESTRICT dst, const void* SHZ_RESTRICT src)` Copies `src` to `dst` in a single 32-byte transaction using the Store Queues and XMTRX.
- [`shz_dcache_alloc_line`](https://sh4zam.com/api/memory/shz_dcache_alloc_line/): `void shz_dcache_alloc_line(void* src)` Intrinsic around the SH4 `MOVCA.L` instruction.

### Memory: Macros

- [`SHZ_PREFETCH`](https://sh4zam.com/api/memory/SHZ_PREFETCH/): `#define SHZ_PREFETCH(ptr) SHZ_PREFETCH_(ptr)` Used to prepopulate the cache line mapping to the given address, before it is used.

## Compiler Definitions

`#include <sh4zam/shz_cdefs.h>` · [module page](https://sh4zam.com/api/cdefs/)

### Compiler Definitions: Back-Ends

- [`SHZ_SH4`](https://sh4zam.com/api/cdefs/SHZ_SH4/): `#define SHZ_SH4 1` Back-end for the Dreamcast's SH4.
- [`SHZ_PPC`](https://sh4zam.com/api/cdefs/SHZ_PPC/): `#define SHZ_PPC 2` Back-end for the Gamecube/Wii's Gekko PPC.
- [`SHZ_MIPS`](https://sh4zam.com/api/cdefs/SHZ_MIPS/): `#define SHZ_MIPS 3` Back-end for MIPS architectures.
- [`SHZ_ARM`](https://sh4zam.com/api/cdefs/SHZ_ARM/): `#define SHZ_ARM 4` Back-end for ARM architectures.
- [`SHZ_X86_64`](https://sh4zam.com/api/cdefs/SHZ_X86_64/): `#define SHZ_X86_64 5` Back-end for x86_64 architectures.
- [`SHZ_SPU`](https://sh4zam.com/api/cdefs/SHZ_SPU/): `#define SHZ_SPU 6` Back-end for the Cell B/E SPU architecture.
- [`SHZ_WASM`](https://sh4zam.com/api/cdefs/SHZ_WASM/): `#define SHZ_WASM 8` Back-end for WebAssembly.
- [`SHZ_SW`](https://sh4zam.com/api/cdefs/SHZ_SW/): `#define SHZ_SW ~0` Generic C-based software back-end.

### Compiler Definitions: TLS Models

- [`SHZ_TLS_DISABLED`](https://sh4zam.com/api/cdefs/SHZ_TLS_DISABLED/): `#define SHZ_TLS_DISABLED 0` No thread-local variables.
- [`SHZ_TLS_IMPLICIT`](https://sh4zam.com/api/cdefs/SHZ_TLS_IMPLICIT/): `#define SHZ_TLS_IMPLICIT 1` Use `thread_local` keyword for TLS.
- [`SHZ_TLS_PTHREAD`](https://sh4zam.com/api/cdefs/SHZ_TLS_PTHREAD/): `#define SHZ_TLS_PTHREAD 2` Use pthread unique keys for TLS.
- [`SHZ_TLS_CTHREAD`](https://sh4zam.com/api/cdefs/SHZ_TLS_CTHREAD/): `#define SHZ_TLS_CTHREAD 3` Use C11 thread TSS keys for TLS.

### Compiler Definitions: Compiler Detection

- [`SHZ_GNUC`](https://sh4zam.com/api/cdefs/SHZ_GNUC/): `#define SHZ_GNUC 1` Defined when building with a GCC-compatible compiler.

### Compiler Definitions: Utilities

- [`SHZ_STRINGIFY_LITERAL`](https://sh4zam.com/api/cdefs/SHZ_STRINGIFY_LITERAL/): `#define SHZ_STRINGIFY_LITERAL(a) #a` Stringifies a literal expression.
- [`SHZ_STRINGIFY`](https://sh4zam.com/api/cdefs/SHZ_STRINGIFY/): `#define SHZ_STRINGIFY(a) SHZ_STRINGIFY_LITERAL(a)` Stringifies an expression *after* preprocessing, supporting macro expansion.
- [`SHZ_COUNT_OF`](https://sh4zam.com/api/cdefs/SHZ_COUNT_OF/): `#define SHZ_COUNT_OF(array) (sizeof(array) / sizeof((array)[0]))` Returns the number of elements within a statically sized array.
- [`SHZ_CONTAINER_OF`](https://sh4zam.com/api/cdefs/SHZ_CONTAINER_OF/): `#define SHZ_CONTAINER_OF(ptr, type, member) ((type*)((char*)(ptr) - offsetof(type, member)))` Returns the containing structure from a pointer to one of its members.
- [`SHZ_SWAP`](https://sh4zam.com/api/cdefs/SHZ_SWAP/): `#define SHZ_SWAP(a, b) do { typeof(a) tmp = a; a = b; b = tmp; } while(false)` Macro which swaps the two values held by `a` and `b`.
- [`SHZ_DECLARE_STRUCT`](https://sh4zam.com/api/cdefs/SHZ_DECLARE_STRUCT/): `#define SHZ_DECLARE_STRUCT(n, t) struct n; typedef struct n t` Macro which forward declares a struct and its typedef.
- [`SHZ_DECLARE_STRUCT_ALIGNED`](https://sh4zam.com/api/cdefs/SHZ_DECLARE_STRUCT_ALIGNED/): `#define SHZ_DECLARE_STRUCT_ALIGNED(n, t, a) struct SHZ_ALIGNAS(a) n; typedef struct n t` Macro which forward declares a manually aligned struct and its typedef.

### Compiler Definitions: TLS Utilities

- [`SHZ_TLS_DECL`](https://sh4zam.com/api/cdefs/SHZ_TLS_DECL/): `#define SHZ_TLS_DECL(type, name, ...) static type name = __VA_ARGS__` Declares a TLS variable with disabled model (so not thread-local).
- [`SHZ_TLS_REF`](https://sh4zam.com/api/cdefs/SHZ_TLS_REF/): `#define SHZ_TLS_REF(name) (&name)` References a TLS variable, with disabled model.

### Compiler Definitions: Aliasing Types

- [`shz_alias_int16_t`](https://sh4zam.com/api/cdefs/shz_alias_int16_t/): `typedef SHZ_ALIASING int16_t shz_alias_int16_t` int16_t type whose value may be aliased as another type.
- [`shz_alias_uint16_t`](https://sh4zam.com/api/cdefs/shz_alias_uint16_t/): `typedef SHZ_ALIASING uint16_t shz_alias_uint16_t` uint16_t type whose value may be aliased as another type.
- [`shz_alias_int32_t`](https://sh4zam.com/api/cdefs/shz_alias_int32_t/): `typedef SHZ_ALIASING int32_t shz_alias_int32_t` int32_t type whose value may be aliased as another type.
- [`shz_alias_uint32_t`](https://sh4zam.com/api/cdefs/shz_alias_uint32_t/): `typedef SHZ_ALIASING uint32_t shz_alias_uint32_t` uint32_t type whose value may be aliased as another type.
- [`shz_alias_float_t`](https://sh4zam.com/api/cdefs/shz_alias_float_t/): `typedef SHZ_ALIASING float shz_alias_float_t` float type whose value may be aliased as another type.
- [`shz_alias_int64_t`](https://sh4zam.com/api/cdefs/shz_alias_int64_t/): `typedef SHZ_ALIASING int64_t shz_alias_int64_t` int64_t type whose value may be aliased as another type.
- [`shz_alias_uint64_t`](https://sh4zam.com/api/cdefs/shz_alias_uint64_t/): `typedef SHZ_ALIASING uint64_t shz_alias_uint64_t` uint64_t type whose value may be aliased as another type.
- [`shz_alias_double_t`](https://sh4zam.com/api/cdefs/shz_alias_double_t/): `typedef SHZ_ALIASING double shz_alias_double_t` double type whose value may be aliased as another type.

### Compiler Definitions: Macros

- [`SHZ_TARGET`](https://sh4zam.com/api/cdefs/SHZ_TARGET/): `#define SHZ_TARGET SHZ_SW` Target architecture Determines the actual architecture we're building for.
- [`SHZ_BACKEND`](https://sh4zam.com/api/cdefs/SHZ_BACKEND/): `#define SHZ_BACKEND SHZ_SPU` SH4ZAM back-end Selects which SH4ZAM implementation to use for a given target.
- [`SHZ_TLS_MODEL`](https://sh4zam.com/api/cdefs/SHZ_TLS_MODEL/): `#define SHZ_TLS_MODEL SHZ_TLS_IMPLICIT` thread_local storage.

### Compiler Definitions: Not in upstream reference

- [`SHZ_MSVC`](https://sh4zam.com/api/cdefs/SHZ_MSVC/): `#define SHZ_MSVC 1` Defined when building with Microsoft Visual C++.
- [`SHZ_CLANG`](https://sh4zam.com/api/cdefs/SHZ_CLANG/): `#define SHZ_CLANG 1` Defined when bulding with Clang.
- [`SHZ_MINGW64`](https://sh4zam.com/api/cdefs/SHZ_MINGW64/): `#define SHZ_MINGW64 1` Defined when bulding with MinGW-w64.
- [`SHZ_MINGW32`](https://sh4zam.com/api/cdefs/SHZ_MINGW32/): `#define SHZ_MINGW32 1` Defined when building for 32-bit MinGW or other MinGW compiler(s).
- [`SHZ_GCC`](https://sh4zam.com/api/cdefs/SHZ_GCC/): `#define SHZ_GCC 1` Defined when building for GCC.
- [`SHZ_ALIGNAS`](https://sh4zam.com/api/cdefs/SHZ_ALIGNAS/): `#define SHZ_ALIGNAS(N) __attribute__((aligned((N))))` Forces a function or type to be aligned by `N` bytes.
- [`SHZ_SIMD`](https://sh4zam.com/api/cdefs/SHZ_SIMD/): `#define SHZ_SIMD(N) __attribute__((vector_size((N))))` Tells GCC that a scalar type is to be treated as a vector of size `N.`
- [`SHZ_HOT`](https://sh4zam.com/api/cdefs/SHZ_HOT/): `#define __attribute__((hot))` Tells GCC that a particular function should be optimized for performance.
- [`SHZ_COLD`](https://sh4zam.com/api/cdefs/SHZ_COLD/): `#define __attribute__((cold))` Tells GCC that a particular function should be optimized for size.
- [`SHZ_FAST_MATH`](https://sh4zam.com/api/cdefs/SHZ_FAST_MATH/): `#define __attribute__((optimize("fast-math")))` Put this before a function definition to tell GCC to use fast math optimizations on a specific function.
- [`SHZ_NO_FAST_MATH`](https://sh4zam.com/api/cdefs/SHZ_NO_FAST_MATH/): `#define SHZ_NO_FAST_MATH __attribute__((optimize("no-fast-math")))` Put this before a function definition to tell GCC to NOT use fast math optimizations on a specific function.
- [`SHZ_NO_UNROLL_LOOPS`](https://sh4zam.com/api/cdefs/SHZ_NO_UNROLL_LOOPS/): `#define SHZ_NO_UNROLL_LOOPS __attribute__((optimize("no-unroll-loops")))` Put this before a function definition to tell GCC to NOT unroll loops in a specific function.
- [`SHZ_NO_OPTIMIZATION`](https://sh4zam.com/api/cdefs/SHZ_NO_OPTIMIZATION/): `#define SHZ_NO_OPTIMIZATION __attribute__((optimize("O0")))` Tells GCC to disable any optimizations when compiling a function.
- [`SHZ_FUNC_ALIGNAS`](https://sh4zam.com/api/cdefs/SHZ_FUNC_ALIGNAS/): `#define SHZ_FUNC_ALIGNAS(N) __attribute__((aligned(N)))` Aligns a function within the .text segment by `N` bytes.
- [`SHZ_FORCE_INLINE`](https://sh4zam.com/api/cdefs/SHZ_FORCE_INLINE/): `#define __attribute__((always_inline))` Forces GCC to inline the given function.
- [`SHZ_NO_INLINE`](https://sh4zam.com/api/cdefs/SHZ_NO_INLINE/): `#define __attribute__((noinline))` Prevents GCC from inlining the given function.
- [`SHZ_FLATTEN`](https://sh4zam.com/api/cdefs/SHZ_FLATTEN/): `#define SHZ_FLATTEN __attribute__((flatten))` Forces GCC to inline all calls to other functions made within the tagged function.
- [`SHZ_PACKED`](https://sh4zam.com/api/cdefs/SHZ_PACKED/): `#define SHZ_PACKED __attribute__((packed))` Tells GCC not to introduce any extra padding for the given type.
- [`SHZ_PURE`](https://sh4zam.com/api/cdefs/SHZ_PURE/): `#define __attribute__((pure))` Tells GCC the function has no effects other than returning a value that depends on its arguments and global variables.
- [`SHZ_CONST`](https://sh4zam.com/api/cdefs/SHZ_CONST/): `#define __attribute__((const))` Tells GCC the function has no effects other than returning a value that depends only on its arguments.
- [`SHZ_ALIASING`](https://sh4zam.com/api/cdefs/SHZ_ALIASING/): `#define SHZ_ALIASING __attribute__((__may_alias__))` Tells GCC that the decorated pointer may be breaking strict aliasing rules for C and C++
- [`SHZ_DEPRECATED`](https://sh4zam.com/api/cdefs/SHZ_DEPRECATED/): `#define SHZ_DEPRECATED(m) __attribute__((deprecated(m)))` Emits a warning that a symbol has been deprecated with a message, upon use.
- [`SHZ_LIKELY`](https://sh4zam.com/api/cdefs/SHZ_LIKELY/): `#define SHZ_LIKELY(e) __builtin_expect(!!(e), 1)` Tells GCC that the expression is likely to be true (used for conditional and loop optimizations)
- [`SHZ_UNLIKELY`](https://sh4zam.com/api/cdefs/SHZ_UNLIKELY/): `#define SHZ_UNLIKELY(e) __builtin_expect(!!(e), 0)` Tells GCC that the expression is likely to be false (used for conditional and loop optimizations)
- [`SHZ_RESTRICT`](https://sh4zam.com/api/cdefs/SHZ_RESTRICT/): `#define SHZ_RESTRICT __restrict__` Tells GCC the pointer paraemter is unique and is not aliased by another parameter
- [`SHZ_MEMORY_BARRIER_SOFT`](https://sh4zam.com/api/cdefs/SHZ_MEMORY_BARRIER_SOFT/): `#define SHZ_MEMORY_BARRIER_SOFT() asm volatile("" : : : "memory")` Creates a software memory barrier beyond which any loads or stores may not be reordered
- [`SHZ_MEMORY_BARRIER_HARD`](https://sh4zam.com/api/cdefs/SHZ_MEMORY_BARRIER_HARD/): `#define SHZ_MEMORY_BARRIER_HARD() __sync_synchronize()` Creates a hardware memory barrier beyond which any loads or stores may not be reordered
- [`SHZ_INSTR_BARRIER`](https://sh4zam.com/api/cdefs/SHZ_INSTR_BARRIER/): `#define SHZ_INSTR_BARRIER() asm volatile("")` Prevents the compiler from reordering instructions beyond the barrier.
- [`SHZ_DECLS_BEGIN`](https://sh4zam.com/api/cdefs/SHZ_DECLS_BEGIN/): `#define` Dummy define provided for C++ compatibility
- [`SHZ_DECLS_END`](https://sh4zam.com/api/cdefs/SHZ_DECLS_END/): `#define` Dummy define provided for C++ compatibility
- [`SHZ_INLINE`](https://sh4zam.com/api/cdefs/SHZ_INLINE/): `#define inline static` Requests a function or member to be inlined (nonforcibly) OR to have static linkage.
- [`SHZ_NOEXCEPT`](https://sh4zam.com/api/cdefs/SHZ_NOEXCEPT/): `#define` Dummy define provided for C++ compatibility
- [`SHZ_INIT`](https://sh4zam.com/api/cdefs/SHZ_INIT/): `#define SHZ_INIT(type, ...) ((type){ __VA_ARGS__ })` Temporary struct initialization statement to use within C.
- [`SHZ_CONVERT`](https://sh4zam.com/api/cdefs/SHZ_CONVERT/): `#define SHZ_CONVERT(type, value)` Conversion macro for zero-overhead conversions, taking the given `value` to a value of the given `type.`

## Version

`#include <sh4zam/shz_version.h>` · [module page](https://sh4zam.com/api/version/)

### Version: Compile-Time Utilities

- [`SHZ_VERSION_MAJOR`](https://sh4zam.com/api/version/SHZ_VERSION_MAJOR/): `#define SHZ_VERSION_MAJOR 0` Compile-time SH4ZAM major version.
- [`SHZ_VERSION_MINOR`](https://sh4zam.com/api/version/SHZ_VERSION_MINOR/): `#define SHZ_VERSION_MINOR 9` Compile-time SH4ZAM minor version.
- [`SHZ_VERSION_PATCH`](https://sh4zam.com/api/version/SHZ_VERSION_PATCH/): `#define SHZ_VERSION_PATCH 1` Compile-time Sh4ZAM patch version.
- [`SHZ_VERSION`](https://sh4zam.com/api/version/SHZ_VERSION/): `#define SHZ_VERSION` Current SH4ZAM full compile-time version identifier, integer-compatible.
- [`SHZ_VERSION_INIT`](https://sh4zam.com/api/version/SHZ_VERSION_INIT/): `#define SHZ_VERSION_INIT(major, minor, patch)` Packs values of individual version components into a SH4ZAM full version value.

### Version: Link-Time Utilities

- [`shz_version_t`](https://sh4zam.com/api/version/shz_version_t/): `typedef uint32_t shz_version_t` Integer-compatible value type containing a full SH4ZAM version.
- [`shz_version`](https://sh4zam.com/api/version/shz_version-typedef/): `typedef shz_version_t shz_version` Version typedef for those who hate POSIX-style.
- [`shz_version_linked`](https://sh4zam.com/api/version/shz_version_linked/): `shz_version_t shz_version_linked(void)` Returns the full version of SH4ZAM that was linked against.
- [`shz_version_fields`](https://sh4zam.com/api/version/shz_version_fields/): `void shz_version_fields(shz_version_t version, uint8_t* major, uint16_t* minor, uint8_t* patch)` Extracts the individual version component values from a full version.


---
# Community

Source: https://sh4zam.com/community/

> Where to ask about SH4ZAM - the

The `#sh4zam` channel within the [Simulant Discord Server](https://discord.gg/G2Ay9kxec2) for Dreamcast development is the best place to ask questions, get help, give feedback, or discuss anything relating to SH4ZAM. Also, feel free to [open tickets](https://github.com/gyrovorbis/sh4zam/issues) for any issues or feature requests.

## Links

- Source: [github.com/gyrovorbis/sh4zam](https://github.com/gyrovorbis/sh4zam)
- Issues and feature requests: [GitHub issues](https://github.com/gyrovorbis/sh4zam/issues)
- Chat: `#sh4zam` on the [Simulant Discord](https://discord.gg/G2Ay9kxec2)
- KallistiOS: [KallistiOS](https://github.com/KallistiOS/KallistiOS) and [kos-ports](https://github.com/KallistiOS/kos-ports)
- Code of Conduct: [Don't be a dick.](https://github.com/gyrovorbis/sh4zam/blob/master/CODE_OF_CONDUCT.md)

## Acknowledgements

SH4ZAM began as a collection of inline assembly routines developed specifically to accelerate the math in the Grand Theft Auto 3 and Vice City DC ports. Those routines, along with many others from various contributors, were separated and combined into a single standalone library. Special thanks to the following individuals who have either directly or indirectly contributed to SH4ZAM:

- Falco Girgis
- Paul Cercueil
- Oleg Endo
- jnmartin64
- Stefanos Kornilios Mitsis Poiitidis
- MoopTheHedgehog
- Mikael Kalms
- Twada
- TapamN
- UnknownShadow
- yomboprime
- David Reichelt
- Luke Benstead
- Ian Michael
- HailToDodongo
- Jesse Stojan
- Jamie Hyland
- Aleios
- John Brooks
- Daniel Fairchild
- BruceLeet
- Eric Fradella
- Donald Haase
- IANN (@meisei4)
- Niels "Mouse's Mistake" Van Son

## License

SH4ZAM is MIT licensed, © Falco Girgis and SH4ZAM contributors.

## Related

- [Contributing](https://sh4zam.com/contributing/)
- [Showcase](https://sh4zam.com/showcase/)
- [Changelog](https://sh4zam.com/changelog/)


---
# Architecture

Source: https://sh4zam.com/concepts/architecture/

> How SH4ZAM is laid out (interface headers, inline implementations, per-back-end code, out-of-line sources) and how a call reaches its back-end

SH4ZAM is a header-heavy library: almost everything is `inline`, so the compiler sees the implementation at every call site and can schedule SH4 instructions across your code. The headers are split so the part you read stays clean: interface headers hold only documented declarations, and the implementations live in an `inline/` tree with one folder per back-end. A small static library, `libsh4zam.a`, holds the few routines that are better out of line.

## File tree

```text
include/sh4zam/
  shz_sh4zam.h / .hpp        umbrella: includes everything
  shz_cdefs.h / .hpp         configuration, target/back-end detection, attributes, TLS, SHZ_CONVERT
  shz_version.h / .hpp       compile-time and link-time version
  shz_scalar.h / .hpp        scalar math
  shz_trig.h / .hpp          trigonometry
  shz_vector.h / .hpp        vec2 / vec3 / vec4
  shz_quat.h / .hpp          quaternions
  shz_matrix.h / .hpp        in-memory matrices
  shz_xmtrx.h / .hpp         the register-resident active matrix
  shz_complex.h / .hpp       complex numbers + FFT
  shz_mem.h / .hpp           memcpy family, store queues, cache
  inline/
    shz_<module>.inl.h       generic implementation; picks a back-end
    sh4/shz_<module>_sh4.inl.h    SH4 inline asm
    sw/shz_<module>_sw.inl.h      portable C
    spu/shz_vector_spu.inl.h      Cell SPU (vector only)
source/
  shz_matrix.c  shz_quat.c  shz_version.c  shz_xmtrx.c      out-of-line, any back-end
  sh4/shz_xmtrx_sh4.s  sh4/shz_mem_sh4.s  sh4/shz_complex_sh4.c
  sw/shz_xmtrx_sw.c    sw/shz_complex_sw.c
example/   bruces_balls/  pvr_dma/
test/      one *_test_suite.cpp per module, libGimbal + cglm submodules
```

## The pattern per module

For each module `X`:

- `shz_X.h` is the **interface**: types, constants and documented declarations only. This is the file to read, and the file this site's API reference is generated from.
- `inline/shz_X.inl.h` is the **implementation**, included at the bottom of `shz_X.h`. Routines that are the same on every back-end are written here once. Routines that differ call `shz_foo_sh4()` or `shz_foo_sw()`.
- `inline/sh4/shz_X_sh4.inl.h` and `inline/sw/shz_X_sw.inl.h` hold those back-end-specific versions.
- `shz_X.hpp` is the **C++ API** in `namespace shz`, a thin layer over the C functions.

## How a call is dispatched

Each `inline/shz_X.inl.h` picks its back-end at compile time. For most modules that is exactly one include:

```c
#if SHZ_BACKEND == SHZ_SH4
#   include "sh4/shz_scalar_sh4.inl.h"
#else
#   include "sw/shz_scalar_sw.inl.h"
#endif
```

The back-end is chosen at compile time, with no function pointers: the chosen implementation is inlined into your code. `SHZ_BACKEND` comes from `shz_cdefs.h` (auto-detected) or from your build system; see [Back-ends](https://sh4zam.com/concepts/backends/).

Some routines are written once in the generic file on top of other SH4ZAM routines. `shz_invf()`, for example, is `shz_invf_fsrra()` with the sign restored, so it is fast on every back-end that has a fast `shz_invf_fsrra()`.

## What libsh4zam.a contains

The static library holds what is better out of line: the larger matrix and quaternion routines (`source/shz_matrix.c`, `source/shz_quat.c`), the version query, the XMTRX routines that are big enough to be called rather than inlined (`shz_xmtrx_sh4.s` / `shz_xmtrx_sw.c`), the memory routines in `shz_mem_sh4.s`, and the FFT. That's why you need `-lsh4zam` even though most of the API is inline: without it, your project compiles and then fails to link.

## Configuration in shz_cdefs.h

`shz_cdefs.h` is included by everything. It defines:

- `SHZ_TARGET` and `SHZ_BACKEND` (see [Back-ends](https://sh4zam.com/concepts/backends/)).
- `SHZ_TLS_MODEL` and `SHZ_TLS_DECL()` / `SHZ_TLS_REF()`, used for the per-thread XMTRX state of the software back-end.
- Compiler detection: `SHZ_GNUC`, `SHZ_GCC`, `SHZ_CLANG`, `SHZ_MINGW32`, `SHZ_MINGW64`, `SHZ_MSVC`.
- Attribute macros: `SHZ_INLINE`, `SHZ_FORCE_INLINE`, `SHZ_NO_INLINE`, `SHZ_HOT`, `SHZ_COLD`, `SHZ_FAST_MATH`, `SHZ_NO_FAST_MATH`, `SHZ_PURE`, `SHZ_CONST`, `SHZ_ALIGNAS()`, `SHZ_SIMD()`, `SHZ_PACKED`, `SHZ_ALIASING`, `SHZ_RESTRICT`, `SHZ_LIKELY()`, `SHZ_UNLIKELY()`, `SHZ_DEPRECATED()`, barriers (`SHZ_MEMORY_BARRIER_SOFT()`, `SHZ_MEMORY_BARRIER_HARD()`, `SHZ_INSTR_BARRIER()`), and `SHZ_DECLS_BEGIN` / `SHZ_DECLS_END` for `extern "C"`.
- Utilities: `SHZ_STRINGIFY()`, `SHZ_COUNT_OF()`, `SHZ_CONTAINER_OF()`, `SHZ_SWAP()`, `SHZ_DECLARE_STRUCT()`, `SHZ_INIT()`, and `SHZ_CONVERT()` for zero-cost conversions.
- Aliasing typedefs `shz_alias_int16_t` .. `shz_alias_double_t` for type punning.

Upstream keeps the attribute macros out of its own Doxygen reference; the [Compiler Definitions](https://sh4zam.com/api/cdefs/) page lists them under "Not in upstream reference".

## Versioning

`shz_version.h` defines `SHZ_VERSION_MAJOR`, `SHZ_VERSION_MINOR`, `SHZ_VERSION_PATCH` and the packed `SHZ_VERSION`. Upstream keeps the version in sync across `shz_version.h`, `CMakeLists.txt` and `doc/Doxyfile` with `util/shz_versioning.py`.

## Related

- [Back-ends](https://sh4zam.com/concepts/backends/)
- [C and C++ APIs](https://sh4zam.com/concepts/c-and-cpp/)
- [Using Within a Project](https://sh4zam.com/guides/using-in-a-project/)
- [Compiler Definitions API](https://sh4zam.com/api/cdefs/)


---
# Back-ends

Source: https://sh4zam.com/concepts/backends/

> SH4ZAM's SH4, software and SPU back-ends, how one is selected, targets versus back-ends, and the precision you can expect from each

Every SH4ZAM routine has a portable C implementation, and the hot ones also have a hand-written SH4 implementation. Which one you get is decided at compile time by `SHZ_BACKEND`. This is what lets cross-platform engines such as Simulant and the Meese Engine use one API everywhere: the same calls run as SH4 assembly on a Dreamcast and as plain C on a PC or GameCube.

## The three back-ends

| `SHZ_BACKEND` | What it is | Used when |
| --- | --- | --- |
| `SHZ_SH4` | Hand-optimized SH4 inline asm and `.s` files using `FIPR`, `FTRV`, `FSCA`, `FSRRA`, XMTRX, store queues. | CMake and the KOS Makefile default to it on Dreamcast. Header auto-detection (no build-system define) picks it only when the target is SH4 **and** the FPU is in single-precision mode (`__SH4_SINGLE__` or `__SH4_SINGLE_ONLY__`). |
| `SHZ_SW` | Generic C-based software back-end. XMTRX is emulated in memory. | Everything else, including SH4 builds in other FPU modes. |
| `SHZ_SPU` | Cell Broadband Engine SPU implementation. Partial: only some vector routines have SPU-specific code; the rest use the shared C. | Target is the SPU. |

Each function's API page shows its "Back-ends" line: whether a dedicated SH4 or SPU implementation exists, or whether it uses shared C code on that back-end. The same information is in the `backends` field of [`/api/index.json`](https://sh4zam.com/api/index.json).

## Targets are not back-ends

`SHZ_TARGET` is the architecture the compiler is building for, auto-detected from compiler macros: `SHZ_SH4`, `SHZ_PPC`, `SHZ_MIPS`, `SHZ_ARM`, `SHZ_X86_64`, `SHZ_SPU` or `SHZ_WASM`. `SHZ_BACKEND` is the implementation. Since v0.9.1 they are decoupled: PowerPC, MIPS, ARM, x86_64 and WebAssembly are detected targets, but they all use the software back-end. There are no optimized back-ends for them.

Both macros are only auto-detected when not already defined, so you can force either one. With CMake, set the `SHZ_BACKEND` cache variable (`SH4`, `SPU` or `SW`); the build exports the matching `SHZ_BACKEND=SHZ_<value>` definition to everything that links it. With the KOS Makefile, `make SHZ_BACKEND=SW`.

If you build for SH4 with `-m4` or `-m4-double-only`, set `SHZ_BACKEND` to `SW` yourself: the CMake and Makefile defaults select the SH4 back-end on Dreamcast regardless of FPU mode, and its inline assembly assumes single precision.

The software back-end is built for all targets, including Dreamcast, so a Dreamcast project can switch between the accelerated and software back-ends without rebuilding `libsh4zam.a` for the other one. That's handy for checking whether a bug is in your code or in an SH4 routine.

## What the software back-end guarantees

- Same API, same types, same layouts. Code compiles unchanged.
- XMTRX is a block of 16 floats in thread-local storage (see `SHZ_TLS_MODEL` below), so the XMTRX API behaves the same.
- Results are computed with ordinary C float math, so they are not bit-identical to the SH4 hardware approximations. Store queue routines fall back to `memcpy()` plus barriers.

## Precision differences

The SH4 back-end trades precision for speed in specific places:

- `FSCA` sine/cosine has a maximum error of `SHZ_FSCA_ERROR_MAX`.
- `FSRRA` (all `_fsrra` routines, normalization) is an approximation.
- `FIPR` dot products are reduced precision; C++ exposes a tolerance constant `shz::fipr_max_error`.

That is why `SHZ_FLT_EPSILON` is a deliberately loose `0.01f`, and why `shz_equalf()` and friends compare with it. The unit tests check both back-ends against cglm within these tolerances.

## TLS model

`SHZ_TLS_MODEL` controls how per-thread state (the emulated XMTRX) is stored. CMake always defines it. Without CMake, `shz_cdefs.h` picks `SHZ_TLS_IMPLICIT` for an SH4 target and `SHZ_TLS_DISABLED` for SPU; on other targets nothing is picked, which leaves the model at `SHZ_TLS_DISABLED`, so define `SHZ_TLS_MODEL` yourself (or build with CMake) if more than one thread uses XMTRX.

| Value | Mechanism | CMake default for |
| --- | --- | --- |
| `SHZ_TLS_IMPLICIT` | compiler `thread_local` / `_Thread_local` | Dreamcast, MSVC |
| `SHZ_TLS_PTHREAD` | pthread keys | everything else |
| `SHZ_TLS_CTHREAD` | C11 `tss_t` | opt-in |
| `SHZ_TLS_DISABLED` | plain `static`, shared by all threads | the SPU back-end |

## Related

- [Architecture](https://sh4zam.com/concepts/architecture/)
- [Install with CMake](https://sh4zam.com/guides/install-cmake/)
- [XMTRX](https://sh4zam.com/concepts/xmtrx/)
- [Compiler Definitions API](https://sh4zam.com/api/cdefs/)


---
# C and C++ APIs

Source: https://sh4zam.com/concepts/c-and-cpp/

> How SH4ZAM's C and C++ APIs map onto each other - aliases, CRTP vector types, static XMTRX members, type-generic C macros, and mixing both

SH4ZAM ships two interoperable APIs over the same implementation: a C17 API (with extras for C23) and a C++20 API (with extras for C++23). They are layout-compatible and freely mixable; C++ can still use the C API by design, and every C++ type is also compatible with its corresponding C type. The tables below map one onto the other.

## The mapping at a glance

| C | C++ | How |
| --- | --- | --- |
| `shz_floorf(x)` | `shz::floorf(x)` | `constexpr auto floorf = shz_floorf;` alias |
| `shz_sincosf(a)` returning `shz_sincos_t` | `shz::sincosf(a)` or `shz::sincos::from_radians(a)` | alias, plus the `shz::sincos` type with `sinf()`, `cosf()`, `tanf()` and friends |
| `shz_vec3_t` | `shz::vec3` | `struct vec3 : vecN<vec3, shz_vec3_t, 3>`, which derives from `shz_vec3_t` |
| `shz_vec3_cross(a, b)` | `a.cross(b)` | member function wrapping the C call |
| `shz_vec3_add(a, b)` | `a + b` | operators |
| `shz_vec3_normalize(v)` | `v.direction()` or `v.normalized()`; `v.normalize()` in place | members |
| `shz_quat_slerp(q, p, t)` | `shz::quat::slerp(q, p, t)` | static member |
| `shz_mat4x4_init_identity(&m)` | `m.init_identity()` | member |
| `shz_xmtrx_apply_rotation_x(a)` | `shz::xmtrx::apply_rotation_x(a)` | `struct xmtrx` with static members only |
| `shz_xmtrx_store_4x4(&m)` | `shz::xmtrx::store(&m)` | overloads replace the size suffixes |
| `shz_vec4_from(x)` / `shz_vec4_to(T, v)` | `shz::vec4::from(x)` / `v.to<T>()` | |
| `SHZ_F_PI` | `shz::pi_f` | `constexpr float` |

Every C function page in the [API reference](https://sh4zam.com/api/) has a "C++ equivalent" line, and every [C++ class page](https://sh4zam.com/api/cpp/) lists, per member, the C function it calls. [`/api/index.json`](https://sh4zam.com/api/index.json) has the same mapping in the `cpp` field of each symbol.

## Free-function aliases

Scalar, trig, complex and memory routines are `constexpr` function-pointer aliases in `namespace shz`: same name minus the `shz_` prefix, same signature, no wrapper. The full list is on the [C++ API](https://sh4zam.com/api/cpp/) page.

## Vector types

`shz::vec2`, `shz::vec3` and `shz::vec4` share a CRTP base, `shz::vecN<CRTP, C, R>`, that provides the common surface once: `from()`, `to<T>()`, `deref()`, `swizzle<I...>()`, `abs`, `neg`, `inv`, `min`/`max`/`minv`/`maxv`, `clamp`, `floor`/`ceil`/`round`/`fract`/`sign`/`saturate`, `dot`, `magnitude` and friends, `direction` / `normalize`, `distance`, `lerp`, `step`, `smoothstep`, `reflect`, `refract`, `project`, and the arithmetic operators. Each derived type adds what only it has, e.g. `vec3::cross()`, `vec3::rotate_x()`, `vec2::from_angle()`.

The base calls the C type-generic macros (`shz_vec_dot()` and so on), which resolve to the per-dimension C function, so `shz::vec3::dot` ends up in `shz_vec3_dot()`.

With C++23, the vector types also get a deducing-this `operator[]`, iterators (`begin()`/`end()`) and a `<=>` comparison.

## XMTRX

`shz::xmtrx` is a struct with only static member functions, because XMTRX is a single piece of global (per-thread) register state. Names drop the `shz_xmtrx_` prefix, and overloads replace the size suffixes: `shz::xmtrx::load()` accepts a `shz_mat4x4_t`, a `float[16]`, a `std::array<float, 16>`, a `shz_mat3x4_t` and more.

## Type-generic C

C has no overloading, so `shz_vector.h` provides 48 `_Generic` macros named `shz_vec_<verb>` that forward to the proper routine based on argument type:

```c
#include <sh4zam/shz_vector.h>

float len3(shz_vec3_t v) { return shz_vec_magnitude(v); }   // -> shz_vec3_magnitude()
float len4(shz_vec4_t v) { return shz_vec_magnitude(v); }   // -> shz_vec4_magnitude()
```

When the same header is compiled as C++, those names become overloaded inline functions instead, so `shz_vec_dot()` works in both languages.

## Mixing

Because the C++ types derive from the C structs, you can pass them straight to C functions, and wrap C results back up:

```cpp
#include <sh4zam/shz_sh4zam.hpp>

shz::vec3 bounce(const shz::vec3& v, const shz::vec3& n) {
    shz_vec3_t r = shz_vec3_reflect(v, n);   // C call on C++ objects
    return shz::vec3(r);                     // back to the C++ type
}
```

## Language levels

- C: the library builds as C11; the API targets C17, with extra API features supported for C23.
- C++: C++20 minimum, with extra API features (the ones above) for C++23.

## Related

- [C++ API](https://sh4zam.com/api/cpp/)
- [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/)
- [Types and Memory Layout](https://sh4zam.com/concepts/types-and-layout/)
- [Interop with Existing APIs](https://sh4zam.com/guides/interop/)


---
# Conventions

Source: https://sh4zam.com/concepts/conventions/

> Coordinate systems, column-major matrices, W-first quaternions, radians, single precision and epsilon in SH4ZAM

The following conventions are used throughout the SH4ZAM API by default, unless a function's own page says otherwise. They match GL, so code ported from GL-style math libraries such as CGLM or GLM usually keeps its meaning.

## Summary

| Convention | Description |
| --- | --- |
| Coordinates | Right-handed for world/view space, left-handed for screen/clip space, as with GL. |
| Matrices | Stored in column-major order, as with GL. `mat.col[3]` (also `mat.pos`) is the translation. |
| Quaternions | Stored in `<W, X, Y, Z>` order. W comes first. Identity is (1, 0, 0, 0). |
| Angles | Radians. `_deg` variants take degrees; `u16` variants take a 16-bit fixed-point angle (65536 = one full turn). |
| Precision | Single-precision `float` everywhere. No `double` API. |
| Epsilon | `SHZ_FLT_EPSILON` is `0.01f`, deliberately loose because `FSCA`, `FSRRA` and `FIPR` are approximations. |

## Matrices are column-major

`shz_mat4x4_t` stores 16 floats column by column. The same storage is visible as `elem[16]`, `elem2D[4][4]` (indexed `[column][row]`), four `shz_vec4_t` columns `col[4]`, or the named columns `left`, `up`, `forward`, `pos`:

```c
#include <sh4zam/shz_matrix.h>

shz_vec3_t position_of(const shz_mat4x4_t* m) {
    return m->pos.xyz;           // same as m->col[3].xyz
}
```

`shz_mat4x4_t` must be 8-byte aligned. Use the `_unaligned` routines for matrices that might not be.

## Quaternions store W first

```c
#include <sh4zam/shz_quat.h>

shz_quat_t q = shz_quat_identity();   // w = 1, x = y = z = 0
float w = q.w;                        // also q.e[0]
shz_vec3_t axis = q.axis;             // x, y, z as a shz_vec3_t
```

Watch this when converting from libraries that store `<X, Y, Z, W>` (GLM's `glm::quat` storage, many engines): a straight bit-cast reorders the components. Build the SH4ZAM quaternion with `shz_quat_init(w, x, y, z)` instead.

## Radians, degrees, fixed point

`shz_sinf(x)` takes radians, `shz_sinf_deg(x)` takes degrees, `shz_sincosu16(a)` takes the raw 16-bit `FSCA` angle. `SHZ_DEG_TO_RAD()` and `SHZ_RAD_TO_DEG()` convert; `SHZ_FSCA_RAD_FACTOR` (10430.37835f, which is 65536/2π) and `SHZ_FSCA_DEG_FACTOR` (182.04444443f) scale to the fixed-point format.

## Single precision only

Every API takes and returns `float`. Use the `f` suffix on literals (`1.0f`, not `1.0`), since a `double` near SH4ZAM's inline assembly can leave the FPU in the wrong precision mode, and `float`-with-`double` arithmetic is slow on the SH4. Details in [Optimization Tips](https://sh4zam.com/guides/optimization/#fp-precision-modes).

## Comparing floats

`shz_equalf()` checks for equality based on either the absolute or the relative tolerance, using `SHZ_FLT_EPSILON`; `shz_equalf_abs()` and `shz_equalf_rel()` apply just one of the two. Vector, quaternion and matrix `equal` routines follow the same idea. In C++, `shz::fipr_max_error` is the tolerance constant for results that went through `FIPR`; upstream marks its current value (`0.1f`) as not accurate yet.

## Related

- [Types and Memory Layout](https://sh4zam.com/concepts/types-and-layout/)
- [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/)
- [Trigonometry API](https://sh4zam.com/api/trig/)
- [Quaternion API](https://sh4zam.com/api/quat/)


---
# Naming and Suffixes

Source: https://sh4zam.com/concepts/naming-and-suffixes/

> How SH4ZAM names functions, types and C++ wrappers, and what every suffix (_fsrra, _safe, _deg, _unaligned, _wxyz, sq_) means

Every SH4ZAM name is built from the same few parts: a module prefix, a verb, and optional suffixes that change precision, safety, units, alignment or register layout. Once you know the parts, you can guess most names correctly.

## Functions, types, C++

| Kind | Pattern | Example |
| --- | --- | --- |
| C function | `shz_<module>_<verb>[_<qualifier>]` | `shz_vec3_cross()`, `shz_xmtrx_apply_rotation_x()` |
| Scalar/trig C function | `shz_<name>` (usually the `<math.h>` name) | `shz_floorf()`, `shz_sinf()` |
| C type | `shz_<name>_t` | `shz_vec3_t`, `shz_mat4x4_t`, `shz_quat_t` |
| C type, alternate | `shz_<name>` (same type, "for those who hate POSIX-style") | `shz_vec3`, `shz_mat4x4` |
| Macro / constant | `SHZ_<NAME>` | `SHZ_F_PI`, `SHZ_FLT_EPSILON` |
| Type-generic C macro | `shz_vec_<verb>` | `shz_vec_dot()` picks `shz_vec2_dot()`, `shz_vec3_dot()` or `shz_vec4_dot()` |
| C++ namespace | `shz::` | |
| C++ scalar/trig | `shz::<name>`, a `constexpr` alias of the C function | `shz::floorf` is `shz_floorf` |
| C++ types | `shz::<name>`, deriving from the C struct | `shz::vec3 : shz_vec3_t` |
| C++ XMTRX | `shz::xmtrx::<verb>`, static member functions | `shz::xmtrx::apply_rotation_x()` |

Module prefixes: `vec2`/`vec3`/`vec4` (vector), `quat`, `mat4x4`/`mat3x3`/... (matrix), `xmtrx`, complex functions are C99-style (`shz_caddf()`, `shz_cabsf()`), memory functions are libc-style (`shz_memcpy()`).

## Suffixes

### `_fsrra`

Uses the SH4 `FSRRA` instruction, a single-instruction approximation of 1/sqrt(x). Faster, less precise, and the argument or denominator must be **positive**.

- `shz_inv_sqrtf_fsrra(x)`: fast 1/sqrt(x).
- `shz_sqrtf_fsrra(x)`: fast square root.
- `shz_invf_fsrra(x)`: fast 1/x. It is computed as 1/sqrt(x*x), so it returns 1/|x|: a negative input comes back with the wrong sign. `shz_invf()` is the variant that safely handles negative values.
- `shz_divf_fsrra(num, denom)`: fast division; requires `denom` to be positive. `shz_divf()` otherwise.
- `shz_normalizef_fsrra()`, `shz_remapf_fsrra()`, `shz_wrapf_fsrra()`: range mapping, valid when the range difference is positive.

The classic use is perspective division, where W is known to be positive.

### `_safe`

Guards against degenerate input at a small cost. `shz_vec3_normalize_safe()` returns a zero vector when the magnitude is not greater than zero, where `shz_vec3_normalize()` would divide by zero. Also `shz_smoothstepf_safe()`, `shz_quat_normalize_safe()`, `shz_vec3_project_safe()` and others. (`shz_xmtrx_init_identity_safe()` is deprecated: the plain `shz_xmtrx_init_identity()` is always safe now.)

### `_deg`

Takes the angle in degrees. Everything else is radians. `shz_sinf_deg()`, `shz_sincosf_deg()`, `shz_vec2_from_angle_deg()`. `SHZ_DEG_TO_RAD()` and `SHZ_RAD_TO_DEG()` convert.

### `u16`

Takes the angle as a 16-bit fixed-point value where 0..65535 covers a full turn, which is the native input format of `FSCA`. `shz_sincosu16()`.

### `_unaligned`

Works on matrix data that is not 8-byte aligned, usually taken as a plain `float[16]` array. `shz_mat4x4_t` and `shz_mat2x2_t` must otherwise be 8-byte aligned because the SH4 routines load and store register pairs with 64-bit `FMOV`. `shz_xmtrx_load_unaligned_4x4(const float matrix[16])`, `shz_xmtrx_store_unaligned_4x4(float matrix[16])`, `shz_mat4x4_copy_unaligned()`.

### `_transpose`

Works with the transpose of the matrix: loading a row-major matrix, or applying the inverse of a pure rotation. `shz_xmtrx_load_transpose_4x4()`, `shz_mat4x4_transform_vec3_transpose()`.

### `_reverse`

Reverses the multiplication order (pre-multiply instead of post-multiply). `shz_xmtrx_apply_reverse_4x4()`, `shz_xmtrx_translate_reverse()`.

### `_wxyz`, `_yzwx`, `_wzyx`

Register or column permutations. `FTRV` produces X, Y, Z, W on cycles 4, 5, 6, 7; a permutation puts W first so perspective division can start three cycles earlier. `shz_xmtrx_load_wxyz_4x4()`, `shz_xmtrx_init_permutation_wxyz()`. See [XMTRX](https://sh4zam.com/concepts/xmtrx/#getting-w-first).

### `_xmtrx`

Memory routines with this suffix use the XMTRX register bank as a 64-byte scratch buffer, so they **clobber XMTRX**. `shz_sq_memcpy32_xmtrx()`, `shz_memswap32_1_xmtrx()`.

### `sq_`

Writes through the SH4 store queues: burst writes of 32 bytes at a time, used for submitting to the PVR or copying to VRAM. `shz_sq_memcpy32()`, `shz_sq_memcpy32_1()`.

### Numbers on memory routines

The number is the granularity or count. `shz_memcpy4()` copies 4-byte units, `shz_memcpy32()` 32-byte chunks, `shz_memcpy2_16()` sixteen 2-byte units, and the `_1` routines copy exactly one 32-byte line (`shz_memcpy32_1()`).

### `dot2`, `dot3`

Compute 2 or 3 dot products of one left-hand vector against several right-hand vectors in one pipelined `FIPR` sequence, returning a `shz_vec2_t` or `shz_vec3_t`. `shz_vec3_dot2()`, `shz_vec4_dot3()`, `shz_quat_dot3()`.

## Verbs on matrices and XMTRX

| Verb | Meaning |
| --- | --- |
| `init_*` | Initialize the whole matrix to the transform; other components become identity. |
| `set_*` | Set only the components the transform touches; leave the rest alone. |
| `apply_*` | Apply the transform to the affected components based on their current values (add for translation, multiply the submatrix for scale and rotation). |
| `translate`, `scale`, `rotate_*` | GL-style: full multiply by a matrix initialized to the transform. The most general form. |
| `load_*` / `store_*` | Memory to XMTRX and back. `load_apply_*` and `load_apply_store_*` fuse them. |
| `transform_vec*` / `transform_point*` | Transform vectors; for 3D, `point` implies w = 1 and `vec` implies w = 0. |
| `get_*`, `read*`, `write*`, `swap_*` | Element and row/column access. |

Worked example in [Matrix Transforms](https://sh4zam.com/guides/matrix-transforms/#the-verb-model).

## Related

- [Conventions](https://sh4zam.com/concepts/conventions/)
- [C and C++ APIs](https://sh4zam.com/concepts/c-and-cpp/)
- [Cheatsheet](https://sh4zam.com/cheatsheet/)
- [For Agents](https://sh4zam.com/for-agents/)


---
# The SH4 FPU

Source: https://sh4zam.com/concepts/sh4-fpu/

> Glossary of the Dreamcast SH4 floating-point hardware SH4ZAM is built on - FIPR, FTRV, FSCA, FSRRA, FMAC, XMTRX, precision modes, store queues, prefetch

SH4ZAM's hot paths are hand-written SH4 assembly exploiting the Dreamcast CPU's vector-ish FPU instructions, its back-bank of 16 FP registers, its store queues and its prefetch. Below is a short glossary of that hardware; the deep dives are on [Resources](https://sh4zam.com/resources/).

## Instructions

| Instruction | What it does | Where SH4ZAM uses it |
| --- | --- | --- |
| `FIPR fvA, fvB` | 4-component dot product of two front-bank vectors. Reduced precision. | `shz_vec4_dot()`, magnitudes, `shz_dot8f()`, `shz_mag_sqr4f()`, the `dot2`/`dot3` batch routines. |
| `FTRV XMTRX, fvN` | Multiplies a 4-vector by the 4x4 matrix in the back bank. X, Y, Z, W are ready on cycles 4, 5, 6, 7. | Every `shz_xmtrx_transform_*`, and matrix routines that go through XMTRX. |
| `FSCA FPUL, drN` | Sine and cosine of a 16-bit fixed-point angle (65536 = one turn), both at once. | `shz_sincosf()`, `shz_sinf()`, `shz_cosf()`, `shz_sincosu16()`, rotations. |
| `FSRRA frN` | Approximate 1/sqrt(x) in one instruction. Input must be positive. | Everything ending in `_fsrra`, normalization, fast inverse and division. |
| `FMAC` | Multiply-accumulate: `frN = fr0 * frM + frN`. | Hand-scheduled XMTRX routines (rotation setup, for example). `shz_fmaf()` is written as `a * b + c` so GCC can pick it. |
| `FRCHG` | Swaps the front and back register banks. | Moving data in and out of XMTRX. |

`FSCA` has a maximum error of `SHZ_FSCA_ERROR_MAX`; `FIPR` results are compared in the tests with `shz::fipr_max_error`.

## Register banks and XMTRX

In single-precision mode the FPU has two banks of 16 registers. The front bank (`FR0`..`FR15`, also addressed as the four vectors `fv0`, `fv4`, `fv8`, `fv12`) does ordinary math. The back bank (`XF0`..`XF15`) is XMTRX, the 4x4 matrix `FTRV` multiplies by. SH4ZAM's [XMTRX API](https://sh4zam.com/concepts/xmtrx/) keeps your matrix there across calls.

## Precision modes

The SH4 back-end requires the FPU in single-precision mode: compile with `-m4-single-only` or `-m4-single`. Other FPU modes need the software back-end; see [Back-ends](https://sh4zam.com/concepts/backends/#targets-are-not-back-ends). With `-m4-single`, never let `double` values near SH4ZAM's inline assembly, or the FPU can enter it in double mode. Details in [Optimization Tips](https://sh4zam.com/guides/optimization/#fp-precision-modes).

## Fast trig without -ffast-math

With `-ffast-math`, `-mfsca` and `-mfsrra`, GCC emits `FSCA` and `FSRRA` itself and allocates registers around them well, so SH4ZAM uses the compiler builtins. Without fast math, SH4ZAM falls back to inline assembly that emits the instructions explicitly, so you get the hardware either way.

## Store queues

The SH4 has two 32-byte store queues (SQ). Filling one and flushing it writes a whole 32-byte burst to memory or to the PowerVR's tile accelerator, which is far faster than individual stores to uncached memory. SH4ZAM's `sq_` routines copy through them: `shz_sq_memcpy32()` for buffers, `shz_sq_memcpy32_1()` for exactly one 32-byte block (a PVR polygon header or vertex).

## Cache, prefetch, line allocation

Cache lines are 32 bytes.

- `SHZ_PREFETCH(ptr)` issues `PREF` to start loading a line before you need it. Only one prefetch is in flight at a time.
- `shz_dcache_alloc_line(ptr)` wraps `MOVCA.L`: it allocates the data-cache line for `ptr` without reading RAM first. It is a win when you are about to overwrite all 32 bytes, and it corrupts any other data in that line if you do not own the full line.

## Integer and double gotchas

- `float` with `uint32_t` arithmetic is slow: the SH4 only converts signed integers to float, so both sides get promoted to `double`. `uint16_t` is fine.
- `10.0` is a `double`. Write `10.0f`.

## Related

- [XMTRX](https://sh4zam.com/concepts/xmtrx/)
- [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/)
- [Optimization Tips](https://sh4zam.com/guides/optimization/)
- [Resources](https://sh4zam.com/resources/)


---
# Types and Memory Layout

Source: https://sh4zam.com/concepts/types-and-layout/

> Memory layout of SH4ZAM vector, quaternion, matrix, sincos and complex types, alignment rules, and how the C++ types relate

SH4ZAM's interop story rests on bit-compatibility: every type is a plain struct of `float`s with a documented layout, the C++ types derive from the C structs without adding data, and conversion to and from your own types is a zero-cost reinterpretation.

## Vectors

```text
shz_vec2_t   8 bytes    [ x | y ]
shz_vec3_t  12 bytes    [ x | y | z ]
shz_vec4_t  16 bytes    [ x | y | z | w ]
```

Each is a union, so the same storage is reachable several ways:

| Type | Members |
| --- | --- |
| `shz_vec2_t` | `x`, `y`, `e[2]` |
| `shz_vec3_t` | `x`, `y`, `z`, `e[3]`, `xy` (a `shz_vec2_t`) |
| `shz_vec4_t` | `x`, `y`, `z`, `w`, `e` (indexable like `e[4]`), `xyz` (a `shz_vec3_t`), `xy` and `zw` (two `shz_vec2_t`) |

`shz_vec4_t`'s `e` is declared `float e SHZ_SIMD(16)`: a 16-byte GCC vector (`vector_size`) on GCC-compatible compilers, a plain `float[4]` elsewhere. The exact definitions are on the [`shz_vec2_t`](https://sh4zam.com/api/vector/shz_vec2_t/), [`shz_vec3_t`](https://sh4zam.com/api/vector/shz_vec3_t/) and [`shz_vec4_t`](https://sh4zam.com/api/vector/shz_vec4_t/) pages.

## Quaternion

```text
shz_quat_t  16 bytes    [ w | x | y | z ]      W first
```

Members: `w`, `x`, `y`, `z`, `axis` (a `shz_vec3_t` over x, y, z), `e[4]`. The W-first order is the one to watch when converting from libraries that store X, Y, Z, W.

## Matrices

All matrices are column-major. Columns are vectors:

```text
shz_mat4x4_t  64 bytes, 8-byte aligned
  col[0] = left     [ x | y | z | w ]
  col[1] = up       [ x | y | z | w ]
  col[2] = forward  [ x | y | z | w ]
  col[3] = pos      [ x | y | z | w ]   translation lives here
  elem[16], elem2D[4][4]  indexed [column][row]
```

| Type | Size | Alignment | Columns | Named columns |
| --- | --- | --- | --- | --- |
| `shz_mat4x4_t` | 64 | 8 | `shz_vec4_t col[4]` | `left`, `up`, `forward`, `pos` |
| `shz_mat4x3_t` | 48 | natural | `shz_vec4_t col[3]` | `left`, `up`, `forward` |
| `shz_mat3x4_t` | 48 | natural | `shz_vec3_t col[4]` | `left`, `up`, `forward`, `pos` |
| `shz_mat3x3_t` | 36 | natural | `shz_vec3_t col[3]` | `left`, `up`, `forward` |
| `shz_mat2x2_t` | 16 | 8 | `shz_vec2_t col[2]` | |

`shz_mat4x4_t` and `shz_mat2x2_t` are declared `SHZ_ALIGNAS(8)` and must stay 8-byte aligned, because the SH4 routines move them with 64-bit paired `FMOV`. If a matrix comes from somewhere that doesn't guarantee that (a packed file format, another library's struct), use the `_unaligned` routines such as `shz_xmtrx_load_unaligned_4x4()`.

The 2x2, 3x3, 3x4 and 4x3 types sit in a block upstream marks as undocumented "until API is complete"; they are usable, but expect them to change.

## Small types

```text
shz_sincos_t   8 bytes   [ sin | cos ]         one FSCA result
shz_complex_t  8 bytes   [ real | imag ]
```

`shz_sincos_t` is what `shz_sincosf()` returns: the SH4 computes both values in one `FSCA`, so when you need both, grab them as a pair. `shz_complex_t` is built with `SHZ_CMPLXF(x, y)`; `SHZ_I` is the unit imaginary.

## Alternate names

Every struct has two C names: `shz_vec3_t` and `shz_vec3` (the "for those who hate POSIX-style" typedef). They are the same type.

## C++ types

`shz::vec2`, `shz::vec3`, `shz::vec4`, `shz::quat`, `shz::mat4x4`, `shz::sincos` and `shz::complex` derive from the matching C struct and add only methods and operators, so a `shz::vec3*` is usable anywhere a `shz_vec3_t*` is expected and the C API accepts C++ objects directly. The vector types share a CRTP base, [`shz::vecN`](https://sh4zam.com/api/cpp/vecn/), which provides `from()`, `to<T>()`, `deref()`, `swizzle<...>()` and the common math.

## Cache lines

The SH4 has 32-byte cache lines. A `shz_mat4x4_t` is exactly two of them, which is why Bruce's Balls calls `shz_dcache_alloc_line()` on each half before storing a freshly built matrix into it. See [Examples](https://sh4zam.com/guides/examples/#cache-line-sized-data).

## Related

- [Interop with Existing APIs](https://sh4zam.com/guides/interop/)
- [Conventions](https://sh4zam.com/concepts/conventions/)
- [C and C++ APIs](https://sh4zam.com/concepts/c-and-cpp/)
- [Vector API](https://sh4zam.com/api/vector/), [Matrix API](https://sh4zam.com/api/matrix/)


---
# XMTRX

Source: https://sh4zam.com/concepts/xmtrx/

> The SH4's register-resident 4x4 active matrix, how SH4ZAM's XMTRX API uses it, FTRV timing, the WXYZ trick and thread safety

`XMTRX` is the name given to the 16 FP registers contained within the back-bank of the SH4's FPU. Together they represent the SH4's 4x4 "active matrix", which vectors can be transformed against with a single `FTRV` instruction. For maximum FP performance on the SH4, strategic usage of XMTRX to batch transform operations together, without having to reload FP registers, is key. SH4ZAM's [XMTRX API](https://sh4zam.com/api/xmtrx/) is a set of functions that operate on this global register state directly.

## The register banks

```text
SH4 FPU, single-precision mode
+---------------------------------------------+
| front bank  FR0 .. FR15                     |  ordinary float math,
|             fv0  fv4  fv8  fv12             |  four 4-vectors for FIPR/FTRV
+---------------------------------------------+
| back bank   XF0 .. XF15   = XMTRX           |  the 4x4 active matrix
|             col 0: XF0  XF1  XF2  XF3       |
|             col 1: XF4  XF5  XF6  XF7       |
|             col 2: XF8  XF9  XF10 XF11      |
|             col 3: XF12 XF13 XF14 XF15      |
+---------------------------------------------+
FRCHG swaps the banks.  FTRV XMTRX, fvN  computes  fvN = XMTRX * fvN.
```

Because the matrix lives in registers, a sequence like "load, apply rotation, apply scale, set translation, transform 500 vertices" never touches memory for the matrix. Every function in `shz_xmtrx.h` reads or writes this state; the only ones taking a matrix argument are the `load_*`, `store_*`, `apply_*` (2x2, 3x3, 3x4, 4x4) and fused `load_apply_*` families that move data in and out. The individual registers are named by the `shz_xmtrx_reg` enum (`SHZ_XMTRX_XF0` .. `SHZ_XMTRX_XF15`) for `shz_xmtrx_read()` and `shz_xmtrx_write()`.

## When to use XMTRX vs the Matrix API

Typically, for one-off operations, the in-memory [Matrix API](https://sh4zam.com/api/matrix/) is what should be used. When operations can be batched, using XMTRX to hold your matrix within registers gives the best performance. Examples of such scenarios:

- Applying multiple operations to a source matrix before storing the result.
- Transforming batches of vectors against a single matrix.

Some `shz_mat4x4_*` routines load into XMTRX to do their work and so clobber whatever was there. Their pages carry the warning "This routine clobbers XMTRX." So do the memory routines ending in `_xmtrx`.

## A typical sequence

```c
#include <sh4zam/shz_sh4zam.h>

void draw_mesh(const shz_mat4x4_t* view_proj, shz_vec3_t pos, float yaw,
               const shz_vec3_t* verts, shz_vec4_t* out, unsigned count) {
    shz_xmtrx_load_4x4(view_proj);              // memory -> XMTRX
    shz_xmtrx_translate(pos.x, pos.y, pos.z);   // GL-style multiply, in registers
    shz_xmtrx_apply_rotation_y(yaw);            // only touches the rotation submatrix

    for (unsigned i = 0; i < count; ++i)        // one FTRV per vertex
        out[i] = shz_xmtrx_transform_vec4(shz_vec3_vec4(verts[i], 1.0f));
}
```

The same in C++, where `shz::xmtrx` has only static members:

```cpp
#include <sh4zam/shz_sh4zam.hpp>

void draw_mesh(const shz::mat4x4& view_proj, shz::vec3 pos, float yaw,
               const shz::vec3* verts, shz::vec4* out, unsigned count) {
    shz::xmtrx::load(view_proj);
    shz::xmtrx::translate(pos.x, pos.y, pos.z);
    shz::xmtrx::apply_rotation_y(yaw);

    for (unsigned i = 0; i < count; ++i)
        out[i] = shz::xmtrx::transform(shz::vec4(verts[i], 1.0f));
}
```

For building a model matrix, see the init / apply / set / store pattern in [Matrix Transforms](https://sh4zam.com/guides/matrix-transforms/).

## FTRV timing

`FTRV` produces each component of the result one cycle after another:

| Component | Ready on cycle |
| --- | --- |
| X | 4 |
| Y | 5 |
| Z | 6 |
| W | 7 |

## Getting W first

Transform-and-lighting needs W first, to divide the other components by it, but W comes out last. Two ways around it:

1. `shz_xmtrx_load_wxyz_4x4()` loads a 4x4 matrix with the W column coming first, allowing you to use its result on cycle 4 rather than waiting until cycle 7.
2. Build the projection on top of a permutation matrix, as Bruce's Balls does, then swizzle each result back:

```c
#include <sh4zam/shz_sh4zam.h>

void setup_projection(shz_mat4x4_t* out, float fov, float aspect, float near_z) {
    shz_xmtrx_init_permutation_wxyz();
    shz_xmtrx_apply_screen(640.0f, 480.0f);
    shz_xmtrx_apply_perspective(fov, aspect, near_z);
    shz_xmtrx_store_4x4(out);
}

shz_vec4_t project(shz_vec3_t p) {   // XMTRX holds the matrix built above
    shz_vec4_t v = shz_xmtrx_transform_vec4(shz_vec3_vec4(p, 1.0f));
    v = shz_vec4_swizzle(v, 1, 2, 3, 0);   // undo the WXYZ permutation
    v.w = shz_invf_fsrra(v.w);             // W > 0 for visible points
    return shz_vec4_init(v.x * v.w, v.y * v.w, v.w, 1.0f);
}
```

The full version, with store-queue submission, is in [Examples](https://sh4zam.com/guides/examples/#bruces-balls).

## Thread safety and the software back-end

Unless TLS has been disabled, the XMTRX API is thread-safe, with each thread getting its own unique copy of XMTRX. On the software back-end, XMTRX is emulated as a 16-float state block declared with `SHZ_TLS_DECL()`, so how "per thread" works depends on `SHZ_TLS_MODEL`: compiler `thread_local`, pthread keys, C11 `tss_t`, or disabled (one shared copy). See [Back-ends](https://sh4zam.com/concepts/backends/).

## Related

- [XMTRX API](https://sh4zam.com/api/xmtrx/), [`shz::xmtrx`](https://sh4zam.com/api/cpp/xmtrx/)
- [Matrix Transforms](https://sh4zam.com/guides/matrix-transforms/)
- [The SH4 FPU](https://sh4zam.com/concepts/sh4-fpu/)
- [Matrix API](https://sh4zam.com/api/matrix/)


---
# Contributing

Source: https://sh4zam.com/contributing/

> How to contribute to SH4ZAM, and to this documentation site

So you want to contribute in some way to SH4ZAM? Sweet. The project is pretty casual and easy-going; nothing super formal is required. Just a bunch of nerds trying to give the Dreamcast and SH4 communities some fast math.

## Desired contributions

Pretty much anything that could be seen as adding value to the library, examples, documentation, or anything tangentially related to it will happily be accepted, no matter how large or small. Some examples:

- Adding new API routines
- Optimizing existing API routine implementations
- Adding new examples
- Improving unit test coverage
- Improving documentation in any way
- Adding or fixing code comments (including fixing typos)

## Opening a PR

Try to be as descriptive as you can in summarizing your changes, as that makes them easier to review. There is no formal requirement on PR format, so don't sweat it too much. Just get some gainz and help make the lib kick ass.

If you're unsure about something or want early feedback before it's ready for a full PR, open the PR as a draft.

## Coding style

The project makes an effort to keep the coding style consistent throughout the codebase, but it isn't going to turn down some juicy optimizations over nit-picking little style inconsistencies. Falco can fix it up as part of the PR or a later commit.

## Doxygen comments

Everything that is part of the public API should be fully Doxygen commented. If this is too much of a PITA, if English isn't your first language, if you're allergic to writing, or if you simply don't have time, mention it in the PR and you'll be covered. Those header comments are also the source for the [API reference](https://sh4zam.com/api/) on this site.

## Unit testing

The project is striving hard to hit 100% unit test coverage, but not everyone contributing is going to have time to fully unit test everything, which is fine. Make sure to run the currently implemented unit tests so you haven't broken anything that does have coverage. How: [Testing and Contributing](https://sh4zam.com/guides/testing-and-contributing/).

## C++ bindings

The C++ bindings are kept in sync with the C API; however, SH4 and C contributors are not expected to provide idiomatic C++ bindings for their contributions. Falco will handle it.

## This documentation site

This site lives in `doc/site/` of the SH4ZAM repo, linked as "Site source" in the footer of every page. The API pages are generated from the SH4ZAM headers, so fixes to API descriptions belong in the header comments. Guides and concept pages are plain Markdown in `doc/site/src/content/docs/`; every handwritten page has an edit link at the bottom.

## Related

- [Testing and Contributing](https://sh4zam.com/guides/testing-and-contributing/)
- [Community](https://sh4zam.com/community/)
- [Changelog](https://sh4zam.com/changelog/)


---
# For Agents

Source: https://sh4zam.com/for-agents/

> How LLMs, coding agents and scripts should read this site - llms.txt, Markdown twins, the JSON symbol index, URL patterns and the facts that matter

For LLMs, coding agents and scripts, and the people wiring them up. Everything on this site is static HTML with a plain Markdown twin of every page, plus a JSON index of every public symbol. No JavaScript is needed to read any of it.

## Start here

1. Fetch [`/llms.txt`](https://sh4zam.com/llms.txt). It is a short map of the site with the key facts inline.
2. Fetch [`/cheatsheet.md`](https://sh4zam.com/cheatsheet.md) for every symbol's signature and one-line description on one page.
3. Fetch individual symbol pages only when you need parameters, notes or warnings.

Bigger bundles, if your context allows: [`/llms-api.txt`](https://sh4zam.com/llms-api.txt) (all API pages) and [`/llms-full.txt`](https://sh4zam.com/llms-full.txt) (the whole site).

## URL patterns

| What | HTML | Markdown |
| --- | --- | --- |
| Any page | `/<path>/` | `/<path>.md` |
| Home | `/` | `/index.md` |
| Module | `/api/<module>/` | `/api/<module>.md` |
| Symbol | `/api/<module>/<name>/` | `/api/<module>/<name>.md` |
| C++ class | `/api/cpp/<class>/` | `/api/cpp/<class>.md` |

`<module>` is one of `scalar`, `trig`, `vector`, `quat`, `matrix`, `xmtrx`, `complex`, `memory`, `cdefs`, `version`. `<name>` is the exact, case-sensitive C identifier: `/api/vector/shz_vec3_cross.md`, `/api/trig/SHZ_F_PI.md`. One exception: when two names in a module differ only by case, the second gets a `-<kind>` suffix (`/api/version/shz_version-typedef/` next to `/api/version/SHZ_VERSION/`). The `url` field in the JSON index is always authoritative.

If you know a name but not its module, use the prefix: `shz_vec*` vector, `shz_quat_*` quat, `shz_mat*` matrix, `shz_xmtrx_*` xmtrx, `shz_c*f` complex, `shz_mem*`/`shz_sq_*`/`shz_dcache_*` memory, trig names (`sinf`, `atan2f`, `sincos...`) trig, other `shz_*f` scalar. Or look it up in the index.

## JSON index

[`/api/index.json`](https://sh4zam.com/api/index.json) lists every symbol with `name`, `kind`, `module`, `section`, `header`, `line`, `signature`, `params`, `brief`, `detail`, `returns`, `notes`, `warnings`, `sa` (see also), `backends`, `generic` (the type-generic C macro, if any), `cpp` (C++ equivalents), `url`, `md` and `source_url`. It also has a `conventions` block, the `suffixes` vocabulary and the full C++ class/alias mapping under `cpp`. The schema is [`/api/schema.json`](https://sh4zam.com/api/schema.json); per-module files are `/api/<module>.json`.

## Facts to get right

- **Prefixes:** C functions and types start with `shz_`, macros with `SHZ_`, C++ lives in `namespace shz` with the `shz_` prefix dropped (`shz_sinf` is `shz::sinf`, `shz_vec3_t` is `shz::vec3`, `shz_xmtrx_store_4x4()` is `shz::xmtrx::store()`).
- **Matrices are column-major.** `shz_mat4x4_t.col[3]` (also `.pos`) is translation. `shz_mat4x4_t` must be 8-byte aligned unless you use an `_unaligned` routine.
- **Quaternions are stored `<W, X, Y, Z>`**, W first. Build them with `shz_quat_init(w, x, y, z)`.
- **Angles are radians** unless the name ends in `_deg`; `u16` names take a 16-bit fixed-point angle.
- **Single precision only.** Every API is `float`. Write `1.0f`, never `1.0`.
- **Coordinates:** right-handed world/view space, left-handed screen/clip space, like OpenGL.
- **XMTRX is global register state.** `shz_xmtrx_*` functions take no matrix argument; they operate on whatever was last loaded or initialized. Many `shz_mat4x4_*` routines and all `*_xmtrx` memory routines clobber it.
- **Link with `-lsh4zam`.** Without it, code compiles and fails to link.

## Suffix vocabulary

| Suffix | Meaning |
| --- | --- |
| `_fsrra` | Fast approximation via the `FSRRA` instruction. Argument or denominator must be positive; `shz_invf_fsrra(x)` returns 1/abs(x). |
| `_safe` | Guards degenerate input (zero length, zero denominator). |
| `_deg` | Angle in degrees. |
| `u16` | 16-bit fixed-point angle, 65536 = one turn. |
| `_unaligned` | Accepts matrices that are not 8-byte aligned. |
| `_transpose` | Uses the transposed matrix. |
| `_reverse` | Reversed multiplication order. |
| `_wxyz`, `_yzwx`, `_wzyx` | Permuted register/column order, e.g. W first from `FTRV`. |
| `_xmtrx` | Memory routine that uses XMTRX as scratch and clobbers it. |
| `sq_` | Writes through the SH4 store queues. |
| `init_` / `set_` / `apply_` / GL-style | Matrix verbs: initialize all, set only some components, apply to affected components, full multiply. |

Full explanations: [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes.md).

## Things that do not exist

Do not generate calls to these; they are planned-but-unimplemented items or stale names in upstream comments:

- `shz_memset()`, `shz_memset2()`, `shz_memset4()`, `shz_memset32()`, `shz_macw()`: planned in `shz_mem.h`, not implemented. The only memset in the API is `shz_memset8()` (plus `shz_memset2_16()`).
- `shz_xmtrx_trans_vec4()` and friends: old names. Use `shz_xmtrx_transform_vec4()`, `shz_xmtrx_transform_vec3()`, `shz_xmtrx_transform_vec2()`.
- `shz_xmtrx_load_4x4_wxyz()`: the real name is `shz_xmtrx_load_wxyz_4x4()`.
- `shz_xmtrx_angles()`, `shz_xmtrx_position()`, `shz_xmtrx_size()`, an inverse FFT: planned upstream, not implemented. (`shz_xmtrx_invert()` does exist; it round-trips through memory. A register-only version is what is planned.)
- Optimized PowerPC/ARM/x86 back-ends: those targets use the portable software back-end.

When unsure whether a symbol exists, check `/api/index.json`. If it is not there, it is not in the public headers.

## Verifying a signature

Every symbol page has a "Defined in" line with the header and line number (`sh4zam/shz_vector.h:556`) linking to the exact upstream commit the site was generated from. The signature block on the page is copied from that header line. That commit is in `upstream_commit` in the JSON index.

## Two examples to pattern-match

Model matrix, optimal form (from [Matrix Transforms](https://sh4zam.com/guides/matrix-transforms.md)):

```c
#include <sh4zam/shz_sh4zam.h>

void updateModel(shz_mat4x4_t* model, const Transform* transform) {
    shz_xmtrx_init_rotation_xyz(transform->xRot, transform->yRot, transform->zRot);
    shz_xmtrx_apply_scale(transform->scale, transform->scale, transform->scale);
    shz_xmtrx_set_translation(transform->pos.x, transform->pos.y, transform->pos.z);
    shz_xmtrx_store_4x4(model);
}
```

Wrapping an existing math type (from [Interop](https://sh4zam.com/guides/interop.md)):

```c
return shz_vec4_to(Vec4, shz_vec4_add(shz_vec4_from(lhs), shz_vec4_from(rhs)));
```

## Crawling

`/robots.txt` allows all crawlers, including AI crawlers. `/sitemap-index.xml` lists every page. Pages are server-rendered; navigation is plain links.

## Related

- [Cheatsheet](https://sh4zam.com/cheatsheet/)
- [API Reference](https://sh4zam.com/api/)
- [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/)
- [Conventions](https://sh4zam.com/concepts/conventions/)


---
# Examples

Source: https://sh4zam.com/guides/examples/

> Walkthrough of Bruce's Balls, the 4.5 million polygons per second SH4ZAM benchmark, and the PVR DMA renderer example

Examples can be found within the `example` subdirectory of the SH4ZAM repo, and new examples are always welcome to be contributed. If you installed SH4ZAM through kos-ports, the examples are installed to `kos-ports/examples/sh4zam`; type `make` in an example's folder to build it.

| Example | Description |
| --- | --- |
| Bruce's Balls | Pushes up to 4.5 million PPS, rendering Bruce's balls. |
| PVR DMA | Real-world, complex renderer using KOS's PVR DMA API. |

## Bruce's Balls

Source: [`example/bruces_balls/bruces_balls.c`](https://github.com/gyrovorbis/sh4zam/blob/master/example/bruces_balls/bruces_balls.c) (C23).

The program renders a series of high-polygon balls (93 by default, 20 stacks by 20 slices each) and reports back the rendering performance in polygons per second. It uses KOS's "Direct Rendering" PVR API, which submits geometry to the PowerVR GPU by filling and flushing the two store queues to the TA in alternation. This is the fastest rendering path, and with the right build flags it pushes 4.5 million polygons per second.

### Cache-line-sized data

The secret to high performance is keeping your data cache-friendly. Each ball is exactly one 32-byte cache line:

```c
typedef struct {
    alignas(32)             // Align to cache-line sizes
        shz_vec3_t pos;     //!< 3D Position of a ball.
        shz_vec2_t rot;     //!< X/Y orientation of a ball.
        shz_vec2_t vel;     //!< X/Y velocity of a ball.
        uint32_t   color;   //!< ARGB8888 color of a ball.
} Ball;

static_assert(sizeof(Ball)  == 32); // Ensure we are exactly the size of a cache-line.
static_assert(alignof(Ball) == 32); // Ensure we are exactly aligned to start on cache-line boundaries.
```

Because a `Ball` fills a whole line, initialization calls `shz_dcache_alloc_line(&balls[idx])` first: it allocates the cache line without fetching the old contents from RAM. You can only do this when your data fits perfectly into cache lines, or you will corrupt whatever else shares the line.

### Projection matrix, built once

```c
static void setup_projection_view(shz_mat4x4_t* mat) {
    constexpr float screen_width  = 640.0f;
    constexpr float screen_height = 480.0f;
    constexpr float near_z        = 0.0f;
    constexpr float fov           = SHZ_DEG_TO_RAD(60.0f);
    constexpr float aspect        = screen_width / screen_height;

    shz_dcache_alloc_line(mat);
    shz_xmtrx_init_permutation_wxyz();
    shz_xmtrx_apply_screen(screen_width, screen_height);
    shz_dcache_alloc_line(((void*)mat) + 32);
    shz_xmtrx_apply_perspective(fov, aspect, near_z);
    shz_xmtrx_store_4x4(mat);
}
```

XMTRX starts as a permutation matrix, so every vector transformed by it comes out with W first, which is what perspective division needs immediately. A screen-space transform and the perspective projection are applied on top, and the result is stored once. (KOS's `mat_perspective()` does the screen mapping for you; SH4ZAM does it explicitly for fine-grained control.)

### Per ball: load, translate, apply

```c
static void apply_model_matrix(shz_vec3_t pos, shz_vec2_t rot, const shz_mat4x4_t* proj_view) {
    shz_xmtrx_load_4x4(proj_view);
    shz_xmtrx_translate(pos.x, pos.y, -pos.z);
    shz_xmtrx_apply_rotation_x(rot.x);
    shz_xmtrx_apply_rotation_y(rot.y);
}
```

### Per vertex: sincos, FTRV, FSRRA, store queues

```c
shz_sincos_t sc_slice = shz_sincosf(sliceAngle);
shz_vec3_t local_pos1 = shz_vec3_scale(shz_vec3_init(sc_slice.cos * r2, sc_slice.sin * r2, z2), radius);

shz_vec4_t trans_pos1 = shz_xmtrx_transform_vec4(shz_vec3_vec4(local_pos1, 1.0f));
// Undo the WXYZ permutation baked into the projection matrix.
trans_pos1 = shz_vec4_swizzle(trans_pos1, 1, 2, 3, 0);

pvr_vertex_t* vert1 = pvr_dr_target(*dr_state);
SHZ_MEMORY_BARRIER_SOFT();

trans_pos1.w = shz_invf_fsrra(trans_pos1.w);
vert1->x = trans_pos1.x * trans_pos1.w;
vert1->y = trans_pos1.y * trans_pos1.w;
vert1->z = trans_pos1.w;
pvr_dr_commit(vert1);
```

- `shz_sincosf()` gets sine and cosine from one `FSCA`.
- `shz_xmtrx_transform_vec4()` is one `FTRV` against the matrix held in XMTRX.
- `SHZ_MEMORY_BARRIER_SOFT()` stops GCC from reordering memory accesses so it doesn't read the transformed position before it's ready.
- `shz_invf_fsrra()` is the fast inverse. Upstream's comment is worth repeating: this inversion trick only returns the ABSOLUTE value, so it has the wrong sign when inverting negatives. It is fine here because Z is positive.
- Polygon headers go out with `SHZ_PREFETCH()` followed by `shz_sq_memcpy32_1()`, a single 32-byte copy through the store queues.

### Build flags

```make
CFLAGS += -std=gnu2x -O3 \
          -fomit-frame-pointer -flto -fbuiltin -ffast-math -ffp-contract=fast -mfsrra -mfsca \
          -fmerge-all-constants -funroll-loops -fno-PIC -fipa-pta  \
          -ftree-vectorize -I$(KOS_BASE)/utils
```

It links with `-lsh4zam -lkosutils -lm -Wl,--gc-sections`.

## PVR DMA

Source: [`example/pvr_dma/`](https://github.com/gyrovorbis/sh4zam/tree/master/example/pvr_dma), by jnmartin64.

A real-world renderer that loads an OBJ model with textures from a romdisk and draws it through KOS's PVR DMA path:

- Uses KOS's `pvr_vertbuf_tail()`/`pvr_vertbuf_written()` API for DMA scene submission.
- Uses SH4ZAM to perform all matrix math and transforms.
- Provides a real-world tested implementation of near-Z clipping.
- Shows off PVR hardware fog.

To build: compile and install KOS, install `sh4zam`, `zlib`, `libjpeg`, `libpng` and `libkmg` from kos-ports, then run `make`.

Controls: analog stick moves and turns, d-pad up/down moves vertically, d-pad left/right and the L/R triggers adjust the fog far and near planes, A toggles texturing off for debug vertex coloring, Y resets the scene, Start exits.

## More references

The projects on the [Showcase](https://sh4zam.com/showcase/) page have been accelerated with SH4ZAM and make great references, especially [SH4ZAM PVR](https://github.com/dfchil/sh4zam_pvr), a set of advanced PVR Direct Rendering examples.

## Related

- [Matrix Transforms](https://sh4zam.com/guides/matrix-transforms/)
- [XMTRX](https://sh4zam.com/concepts/xmtrx/)
- [Memory API](https://sh4zam.com/api/memory/)
- [Showcase](https://sh4zam.com/showcase/)


---
# Getting Started

Source: https://sh4zam.com/guides/getting-started/

> Install SH4ZAM, include it, link it, and build a first program in C and C++ for the Sega Dreamcast

SH4ZAM is a hand-optimized, general-purpose math and linear algebra library for harnessing the floating-point power of the SH4 processor in the Sega Dreamcast. Install it, include one header, link `libsh4zam.a`, and make some `gainz`.

## Install

Pick one:

- **KallistiOS (Dreamcast).** SH4ZAM is an official part of [kos-ports](https://github.com/KallistiOS/kos-ports). If you followed the standard KallistiOS setup, it is already installed. Otherwise run `make install` from `kos-ports/sh4zam`. Details: [Install with KallistiOS](https://sh4zam.com/guides/install-kallistios/).
- **CMake (any platform).** `mkdir build && cd build && cmake .. && make && make install` from the repo root. On anything that is not a Dreamcast this builds the portable software back-end. Details: [Install with CMake](https://sh4zam.com/guides/install-cmake/).

## Include and link

In order to use SH4ZAM within your project, you must do two things:

1. Include the header file(s) within your code.
   - `#include <sh4zam/shz_sh4zam.h>` globally includes the whole SH4ZAM C API.
   - `#include <sh4zam/shz_sh4zam.hpp>` globally includes the whole SH4ZAM C++ API.
2. Link to the statically linked library, `libsh4zam.a`, within your build system.

Unless you link to SH4ZAM, your project will compile correctly, yet fail to link. With a KallistiOS `Makefile`, add `-lsh4zam`:

```make
$(TARGET): $(OBJS)
	kos-cc -o $(TARGET) $(OBJS) -lsh4zam
```

With CMake:

```cmake
target_link_libraries(MyProject PUBLIC -lsh4zam)
```

More on this in [Using Within a Project](https://sh4zam.com/guides/using-in-a-project/).

## First program

These are the usage samples from the upstream README. Both build an XMTRX transform, store it, and transform a vector by it.

### C

```c
#include <sh4zam/shz_sh4zam.h>

int main(int argc, const char *argv[]) {
    shz_vec4_t vec1 = shz_vec4_init(2.0f, 3.0f, 4.0f, 1.0f);
    shz_vec4_t vec2 = shz_vec4_normalize(shz_vec4_scale(vec1, shz_sinf(SHZ_F_PI)));
    shz_mat4x4_t mat = {};

    shz_xmtrx_init_diagonal(vec2.x, vec2.y, vec2.z, vec2.w);
    shz_xmtrx_apply_rotation_x(shz_vec4_dot(vec1, vec2));
    shz_xmtrx_apply_translation(vec1.x, vec1.y, vec1.z);
    shz_xmtrx_store_4x4(&mat);

    shz_vec4_t vec3 = shz_xmtrx_transform_vec4(vec2);

    return 0;
}
```

Where applicable, the C API also includes type-generic routines which resolve to the proper function based on argument type. For example, `shz_vec_dot()` forwards to `shz_vec2_dot()`, `shz_vec3_dot()` or `shz_vec4_dot()` depending on the vectors passed to it.

### C++

```cpp
#include <sh4zam/shz_sh4zam.hpp>

int main(int argc, const char* argv[]) {
    shz::vec4 vec1(2.0f, 3.0f, 4.0f, 1.0f);
    shz::vec4 vec2 = shz::vec4(vec1 * shz::sinf(shz::pi_f)).direction();
    shz::mat4x4 mat {};

    shz::xmtrx::init_diagonal(vec2.x, vec2.y, vec2.z, vec2.w);
    shz::xmtrx::apply_rotation_x(vec1.dot(vec2));
    shz::xmtrx::apply_translation(vec1.x, vec1.y, vec1.z);
    shz::xmtrx::store(&mat);

    shz::vec4 vec3 = shz::xmtrx::transform(vec2);

    return 0;
}
```

Upstream's README passes `vec2.y, vec2.z` to `apply_translation()` in the C++ version; it is fixed to match the C version here. C++ can still use the C API by design, and every C++ type is also compatible with its corresponding C type and the C API, so you can mix and match.

The C sample uses `{}` empty initialization, which is C23. With an older C standard, write `shz_mat4x4_t mat = {0};`.

## Run Bruce's Balls

At this point it is advised that you check out and attempt to run the examples provided with SH4ZAM. If you installed through kos-ports they live in `kos-ports/examples/sh4zam`; type `make` in an example's folder to build it. You can quickly verify the integrity of your SH4ZAM install by playing with Bruce's Balls, which renders 93 high-polygon spheres and reports polygons per second. See [Examples](https://sh4zam.com/guides/examples/) for a walkthrough of what it does.

## Next

- [Matrix Transforms](https://sh4zam.com/guides/matrix-transforms/): where the easiest gainz usually are.
- [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/): what `_fsrra`, `_safe`, `_unaligned` and friends mean.
- [Conventions](https://sh4zam.com/concepts/conventions/): column-major matrices, `<W, X, Y, Z>` quaternions, radians.

## Related

- [Install with KallistiOS](https://sh4zam.com/guides/install-kallistios/)
- [Install with CMake](https://sh4zam.com/guides/install-cmake/)
- [API Reference](https://sh4zam.com/api/)
- [Cheatsheet](https://sh4zam.com/cheatsheet/)


---
# Install with CMake

Source: https://sh4zam.com/guides/install-cmake/

> Build and install SH4ZAM with CMake on any platform, with the SH4, SPU or portable software back-end

SH4ZAM builds with plain CMake in any environment, independently of KallistiOS. On a Dreamcast toolchain it builds the SH4 back-end; everywhere else it builds the portable software back-end, so cross-platform engines can use one math API on every target.

## Build and install

To quickly build the project with CMake in any environment, run the following from the repo root:

```sh
mkdir build
cd build
cmake ..
make
make install
```

This builds and installs the statically linked library as well as the public headers.

If you would like to also build and run the unit tests, include `-DSHZ_ENABLE_TESTS=on` within the `cmake` command. A separate unit test executable, `Sh4zamTests`, is built as well.

For KOS users, use `kos-cmake` instead of your system `cmake` command.

## Options

| Option | Values | Default | Notes |
| --- | --- | --- | --- |
| `SHZ_BACKEND` | `SH4`, `SPU`, `SW` | `SH4` when `PLATFORM_DREAMCAST`, `SPU` when `SPU`, else `SW` | Back-end implementation. Exported to users as `SHZ_BACKEND=SHZ_<value>`. |
| `SHZ_TLS_MODEL` | `DISABLED`, `IMPLICIT`, `PTHREAD`, `CTHREAD` | `IMPLICIT` on Dreamcast or MSVC, `DISABLED` for SPU, else `PTHREAD` | How the per-thread XMTRX state is stored. Exported as `SHZ_TLS_MODEL=SHZ_TLS_<value>`. `PTHREAD`/`CTHREAD` link `Threads::Threads`. |
| `SHZ_ENABLE_TESTS` | `ON`/`OFF` | `OFF` | Adds the `test/` directory and the `Sh4zamTests` target. |
| `SHZ_SAVE_TEMPS` | `ON`/`OFF` | `OFF` | GCC/Clang only. Keeps intermediate files (`-save-temps=obj`) and disables LTO. |
| `SHZ_ENABLE_PIC` | `ON`/`OFF` | `OFF` | Position-independent code. |
| `SHZ_LIBRARY_TYPE` | `STATIC`, `OBJECT`, ... | `STATIC` | Set by a parent project. Simulant builds SH4ZAM as an `OBJECT` library embedded in its own archive; in that case nothing is installed. |

`SHZ_BACKEND` and `SHZ_TLS_MODEL` are added to the library's `PUBLIC` compile definitions, so anything linking the `sh4zam` target sees the same values the library was built with.

The project builds as C11 and C++20 (`CMAKE_C_STANDARD 11`, `CMAKE_CXX_STANDARD 20`, GNU extensions on). Your own code can use C17, C23, C++20 or C++23; some API features are only available with C23 or C++23.

## Software back-end on desktop

On a desktop compiler `SHZ_BACKEND` defaults to `SW`: every routine runs portable C, and XMTRX is emulated in a thread-local array, so the same code compiles and runs on x86_64, ARM, PowerPC and friends. The Meese Engine runs on GameCube this way. See [Back-ends](https://sh4zam.com/concepts/backends/) for what the software back-end guarantees.

## As a subproject

Because the target exports its include directory and compile definitions, adding SH4ZAM with `add_subdirectory()` and linking the `sh4zam` target is enough:

```cmake
add_subdirectory(external/sh4zam)
target_link_libraries(MyProject PUBLIC sh4zam)
```

## Related

- [Install with KallistiOS](https://sh4zam.com/guides/install-kallistios/)
- [Using Within a Project](https://sh4zam.com/guides/using-in-a-project/)
- [Back-ends](https://sh4zam.com/concepts/backends/)
- [Testing and Contributing](https://sh4zam.com/guides/testing-and-contributing/)


---
# Install with KallistiOS

Source: https://sh4zam.com/guides/install-kallistios/

> Install SH4ZAM through kos-ports or DreamSDK, update it, and use the upstream Makefile targets

SH4ZAM is an official part of [kos-ports](https://github.com/KallistiOS/kos-ports), so it is integrated with the [KallistiOS](https://github.com/KallistiOS/KallistiOS) ecosystem and is set up as part of the regular KOS installation process.

## Standard KallistiOS setup

If you're following the standard community guide for [Setting up KallistiOS](https://dreamcast.wiki/Getting_Started_with_Dreamcast_development), SH4ZAM will be installed as part of the [Building KOS Ports](https://dreamcast.wiki/Getting_Started_with_Dreamcast_development#Building_kos-ports) step. Nothing else to do.

## DreamSDK

If you're using [DreamSDK](https://dreamsdk.org/) to manage your KallistiOS development environment, SH4ZAM may be installed from the `KallistiOS Ports` tab.

## Manual install or update

To get started within a preexisting KallistiOS environment, use `git pull` from within the folder containing the `kos-ports` git repository, which is typically installed to `/opt/toolchains/dc/kos-ports`. Then `cd` into the `sh4zam` folder and run `make install` to build and install the latest version of SH4ZAM as a statically linked library:

```sh
cd /opt/toolchains/dc/kos-ports
git pull
cd sh4zam
make install
```

Source your `environ.sh` first; the Makefile refuses to run without `KOS_BASE` set. `make install` symlinks `libsh4zam.a` into `$(KOS_PORTS)/lib` and the `sh4zam` header folder into `$(KOS_PORTS)/include`.

Once this succeeds, your KOS application can begin leveraging SH4ZAM to make big performance `gainz`.

## Makefile targets

The upstream `Makefile` wraps `kos-cmake`. Run these from a SH4ZAM checkout:

| Target | What it does |
| --- | --- |
| `lib` | Builds the static library only. |
| `tests` | Builds the unit test binary. |
| `all` | Builds library and unit test binary. |
| `run` | Runs the unit tests using KOS's default loader (`$(KOS_LOADER)`). |
| `rerun` | Cleans, rebuilds and reruns the unit tests. |
| `flycast` | Runs the unit tests with the flycast emulator. |
| `install` | Installs the static library as a KOS port. |
| `uninstall` | Removes the library and headers from KOS ports. |
| `reinstall` | `uninstall` then `install`. |
| `clean` | Deletes all build artifacts. |
| `rebuild` | Cleans, then rebuilds the static library. |
| `check-sw` | Rebuilds and runs the software back-end unit tests on the host (needs Ninja). |
| `docs` | Regenerates the Doxygen documentation. |
| `update` | Checks out `master` and pulls the latest. |

Two variables can be overridden on the command line: `SHZ_BACKEND` (default `SH4`) and `SHZ_SAVE_TEMPS` (default `off`). For example, `make clean lib SHZ_BACKEND=SW` builds the portable software back-end with the Dreamcast toolchain. The variables only take effect when `build/` is configured, so run `make clean` before switching.

## Using kos-cmake

For KOS users building with CMake, use `kos-cmake` instead of your system `cmake` command. It sets up the Dreamcast toolchain so `PLATFORM_DREAMCAST` is defined and the SH4 back-end is selected. The options are listed in [Install with CMake](https://sh4zam.com/guides/install-cmake/).

## Examples

The examples are installed to `kos-ports/examples/sh4zam`. You should be able to type `make` to build any example. See [Examples](https://sh4zam.com/guides/examples/).

## Related

- [Getting Started](https://sh4zam.com/guides/getting-started/)
- [Using Within a Project](https://sh4zam.com/guides/using-in-a-project/)
- [Install with CMake](https://sh4zam.com/guides/install-cmake/)
- [Optimization Tips](https://sh4zam.com/guides/optimization/): compiler flags to set in `environ.sh`


---
# Interop with Existing APIs

Source: https://sh4zam.com/guides/interop/

> Accelerate an existing C or C++ math API with SH4ZAM using zero-cost conversions, without changing client code

One of the most common and important use-cases of SH4ZAM is for it to be pulled into an existing codebase, with its own vector math types and abstractions, with the goal of using SH4ZAM to accelerate the back-end implementation without breaking the API and needing to change client code. SH4ZAM aims to make such interop noninvasive and zero-overhead, and it rigorously validates that any conversion or adapting of its types to existing types gets cleanly optimized away.

## The three steps

SH4ZAMification of an existing codebase usually involves taking the following steps in order to leverage the gainz it has to offer without breaking an existing codebase or math interface:

1. Convert incoming arguments from existing math types to SH4ZAM's math types.
2. Forward arguments to the equivalent accelerated SH4ZAM routine.
3. Convert the return value from SH4ZAM's math types back to the existing math types.

The conversions only require that your type is layout-compatible with the SH4ZAM type: same size, same order of `float` components.

## Adapting C codebases

The following adapts SH4ZAM to accelerate the math behind an existing, idiomatic C API with support for multiple targets, such as CGLM or raymath:

```c
// Only introduce SH4ZAM for supported targets within cross-platform codebases.
#ifdef GAINZ
     // Include all of SH4ZAM, using the .h header for the C APIs.
#    include <sh4zam/shz_sh4zam.h>
#endif

// The existing 4D vector structure used within the codebase.
typedef struct {
    // Type-compatible layout with SH4ZAM's shz_vec4_t.
    float value[4];
} Vec4;

// 4D vector addition operation provided by the existing math API.
Vec4 AddVec4(Vec4 lhs, Vec4 rhs) {
#ifdef GAINZ
    /* 1) Convert incoming arguments to equivalent SH4ZAM types using shz_vec4_from().
       2) Call SH4ZAM's equivalent routine, shz_vec4_add(), with the converted arguments.
       3) Convert SH4ZAM's return value back to existing API type with shz_vec4_to(). */
    return shz_vec4_to(Vec4, shz_vec4_add(shz_vec4_from(lhs), shz_vec4_from(rhs)));
#else
    // The original, unaccelerated path is here for platforms without SH4ZAM.
    return (Vec4){{ lhs.value[0] + rhs.value[0], lhs.value[1] + rhs.value[1],
                    lhs.value[2] + rhs.value[2], lhs.value[3] + rhs.value[3] }};
#endif
}
```

## Adapting C++ codebases

The following adapts SH4ZAM to accelerate the math behind an existing, idiomatic C++ API with support for multiple targets, such as GLM or the Simulant engine:

```cpp
// Only introduce SH4ZAM for supported targets within cross-platform codebases.
#ifdef GAINZ
     // Include all of SH4ZAM, using the .hpp header for the C++ APIs.
#    include <sh4zam/shz_sh4zam.hpp>
#endif

namespace Math {
    // The existing 4D vector structure used within the codebase.
    struct Vec4 {
        // Type-compatible layout with SH4ZAM's shz::vec4.
        float value[4];
        // Overloaded operator providing 4D vector addition operation.
        friend Vec4 operator+(Vec4 lhs, Vec4 rhs);
    };
}

namespace Math {
    // Implementation of 4D vector addition operator.
    Vec4 operator+(Vec4 lhs, Vec4 rhs) {
    #ifdef GAINZ
        /* 1) Convert incoming arguments to SH4ZAM types using shz::vec4::from().
           2) Call SH4ZAM's equivalent addition operator with the converted arguments.
           3) Convert SH4ZAM's return value back with shz::vec4::to<>(). */
        return (shz::vec4::from(lhs) + shz::vec4::from(rhs)).to<Vec4>();
    #else
        // The original, unaccelerated path is here for platforms without SH4ZAM.
        return Vec4({ lhs.value[0] + rhs.value[0], lhs.value[1] + rhs.value[1],
                      lhs.value[2] + rhs.value[2], lhs.value[3] + rhs.value[3] });
    #endif
    }
}
```

Both samples are upstream's, from `doc/guide.dox`. One fix: upstream defines the C++ operator as `Vec4::operator+`, but it is declared as a `friend` (a free function), so here the definition goes inside `namespace Math` without the `Vec4::` qualifier, which is what makes it compile.

## The conversion toolbox

| Need | C | C++ |
| --- | --- | --- |
| Your value to a SH4ZAM value | `shz_vec2_from()`, `shz_vec3_from()`, `shz_vec4_from()` | `shz::vec2::from()`, `shz::vec3::from()`, `shz::vec4::from()` |
| SH4ZAM value back to your type | `shz_vec2_to(Type, v)`, `shz_vec3_to()`, `shz_vec4_to()` | `v.to<Type>()` |
| A pointer to N floats viewed as a SH4ZAM vector | `shz_vec2_deref(ptr)`, `shz_vec3_deref()`, `shz_vec4_deref()` | the same macros, or the `deref()` member of [`shz::vecN`](https://sh4zam.com/api/cpp/vecn/#deref) |
| Any same-size bit-cast | `SHZ_CONVERT(type, value)` | `SHZ_CONVERT(type, value)` |

`SHZ_CONVERT()` is the zero-overhead conversion macro the adapters are built on. In C it goes through a union; in C++ through a `reinterpret_cast` inside a lambda, with a `static_assert` that both types have the same size. It also handles pointers and references. The `_deref` macros cast through `SHZ_ALIASING` pointers so they don't trip strict aliasing.

For matrices, `shz_mat4x4_t` is column-major and must be 8-byte aligned; if your matrix type is not, use the `_unaligned` load/store routines, which take a plain `float[16]` (`shz_xmtrx_load_unaligned_4x4((const float*)&m)`, `shz_xmtrx_store_unaligned_4x4((float*)&m)`). See [Types and Memory Layout](https://sh4zam.com/concepts/types-and-layout/).

## Related

- [Types and Memory Layout](https://sh4zam.com/concepts/types-and-layout/)
- [C and C++ APIs](https://sh4zam.com/concepts/c-and-cpp/)
- [Matrix Transforms](https://sh4zam.com/guides/matrix-transforms/)
- [`SHZ_CONVERT`](https://sh4zam.com/api/cdefs/SHZ_CONVERT/)


---
# Matrix Transforms

Source: https://sh4zam.com/guides/matrix-transforms/

> Turn a CGLM-style model matrix into an optimal XMTRX sequence with init, apply, set and a single store

Some of the largest, easiest-to-exploit gainz for a project lie within its matrix multiplication and transformation code. It is important to understand how to SH4ZAMify such code optimally in order to achieve the highest gainz. Below is upstream's before-and-after: a CGLM model matrix, a direct port, and the version that keeps everything in XMTRX.

## The CGLM original

The following code snippet was taken from a real-world application which was using the CGLM library to create a model-view matrix:

```c
void updateModel(mat4 model, const Transform* transform) {
    glm_mat4_identity(model);
    glm_translate(model, transform->pos);
    glm_rotate_x(model, transform->xRot);
    glm_rotate_y(model, transform->yRot);
    glm_rotate_z(model, transform->zRot);
    glm_scale(model, transform->scale);
}
```

## A direct port

The most straightforward way to accelerate such a routine is to simply do a direct, 1:1 translation between the CGLM and SH4ZAM APIs:

```c
void updateModel(shz_mat4x4_t* model, const Transform* transform) {
    shz_mat4x4_init_identity(model);
    shz_mat4x4_translate(model, transform->pos.x, transform->pos.y, transform->pos.z);
    shz_mat4x4_rotate_x(model, transform->xRot);
    shz_mat4x4_rotate_y(model, transform->yRot);
    shz_mat4x4_rotate_z(model, transform->zRot);
    shz_mat4x4_scale(model, transform->scale, transform->scale, transform->scale);
}
```

While this will work, it's still leaving a MASSIVE amount of gainz on the table. Each `shz_mat4x4_*` GL-style call is a full matrix multiply against memory.

## Stay in XMTRX

The following will perform far better:

```c
void updateModel(shz_mat4x4_t* model, const Transform* transform) {
    /* Don't waste time initializing to the identity matrix just to overwrite it.
       Initialize directly to a compound rotation matrix. */
    shz_xmtrx_init_rotation_xyz(transform->xRot, transform->yRot, transform->zRot);
    // Only "apply" scale to the inner 3x3 submatrix with scaling components.
    shz_xmtrx_apply_scale(transform->scale, transform->scale, transform->scale);
    // Directly set the translational component values of XMTRX.
    shz_xmtrx_set_translation(transform->pos.x, transform->pos.y, transform->pos.z);
    // Only write to our in-memory matrix after we're done operating within XMTRX.
    shz_xmtrx_store_4x4(model);
}
```

We are now leveraging the following:

1. All matrix operations are performed within **XMTRX** registers, rather than within memory.
2. We directly **initialize** XMTRX into the first transform, rather than identity.
3. We use **apply** operations for when a transform only needs to be applied over a submatrix.
4. We directly **set** the translational component rather than applying it as a transform.

These three snippets are upstream's own, from `doc/guide.dox`. The `Transform` struct is the application's; `pos` is anything with `x`, `y`, `z` floats.

## The same thing in C++

`shz::xmtrx` exposes the active matrix as static member functions with the `shz_xmtrx_` prefix dropped:

```cpp
#include <sh4zam/shz_sh4zam.hpp>

void updateModel(shz::mat4x4* model, const Transform& transform) {
    shz::xmtrx::init_rotation_xyz(transform.xRot, transform.yRot, transform.zRot);
    shz::xmtrx::apply_scale(transform.scale, transform.scale, transform.scale);
    shz::xmtrx::set_translation(transform.pos.x, transform.pos.y, transform.pos.z);
    shz::xmtrx::store(model);
}
```

## The verb model

Every transform comes in up to four versions. Using translation as the example:

| Call | Meaning |
| --- | --- |
| `shz_xmtrx_init_translation()` | **Initializes** the whole matrix to the transform; everything else becomes identity. |
| `shz_xmtrx_set_translation()` | **Sets** only the translation components, leaving the others alone. |
| `shz_xmtrx_apply_translation()` | **Applies** the transform to the affected components based on their current values (adds for translation, multiplies the submatrix for scale/rotation). |
| `shz_xmtrx_translate()` | **GL-style**: multiplies the whole matrix by a matrix initialized to the transform. |

The in-memory `shz_mat4x4_*` API uses the same verbs. When order of operations matters (you need a true matrix product), use the GL-style call or `shz_xmtrx_apply_4x4()` with a matrix you prepared earlier.

## Batching: transform many vectors

Once the matrix is in XMTRX, transforming vectors against it is a single `FTRV` each. Load once, transform many:

```c
#include <sh4zam/shz_sh4zam.h>

void transform_points(const shz_mat4x4_t* mvp, const shz_vec3_t* in, shz_vec4_t* out, unsigned count) {
    shz_xmtrx_load_4x4(mvp);
    for (unsigned i = 0; i < count; ++i)
        out[i] = shz_xmtrx_transform_vec4(shz_vec3_vec4(in[i], 1.0f));
}
```

For perspective division, load the matrix with `shz_xmtrx_load_wxyz_4x4()` (or build it on top of `shz_xmtrx_init_permutation_wxyz()`, as Bruce's Balls does) so the W component comes out of `FTRV` first. See [XMTRX](https://sh4zam.com/concepts/xmtrx/#getting-w-first).

## When not to use XMTRX

For a one-off operation with no batching, the in-memory Matrix API is what should be used, especially when you don't want to clobber whatever is currently loaded in XMTRX. Note that some `shz_mat4x4_*` routines still load into XMTRX to do their work; their pages say so in a warning.

## Related

- [XMTRX](https://sh4zam.com/concepts/xmtrx/)
- [XMTRX API](https://sh4zam.com/api/xmtrx/)
- [Matrix API](https://sh4zam.com/api/matrix/)
- [Examples](https://sh4zam.com/guides/examples/): Bruce's Balls builds its projection the same way


---
# Optimization Tips

Source: https://sh4zam.com/guides/optimization/

> Compiler flags, mixed -O levels, selective fast math, SH4 FPU precision modes, double promotion and fast division for SH4ZAM

Before we even begin discussing how to make the most out of this library, it is *imperative* that you know how to get the most out of the SH GCC toolchain to get your regular C and C++ code as fast as possible.

## Compiler flags

Only a total newb would leave free, universal gainz on the table before jumping directly into hand-optimizing critical code, as it's possible your bottleneck may not even exist with the proper flags. If you are using KallistiOS, you can control which of these flags are enabled or disabled globally for your entire environment by toggling them within your `environ.sh` file.

| Flag(s) | Description |
| --- | --- |
| `-ffast-math` | Allows the compiler to perform optimizations which break strict IEEE compliance of floating-point numbers. |
| `-mfsca` | Allows the compiler to replace `sinf()` and `cosf()` stdlib calls with the `FSCA` instruction. Requires `-ffast-math` to take effect. |
| `-mfsrra` | Allows the compiler to replace `1.0f / sqrtf(x)` patterns with the `FSRRA` instruction. Requires `-ffast-math` to take effect. |
| `-O[0-3, s]` | Sets the optimization level. Default is typically `-O2`, with `-O3` typically offering speed for more bloated code. `-Os` prioritizes smaller code size above performance. Below `-O2` is useless for release performance but is easier to debug during development. |
| `-flto` | Enables link-time optimizations, which allows the linker to perform function inlining of regular out-of-line functions. This is *extremely* important for performance but increases build times. |
| `-fipa-pta` | Enables interprocedural pointer analysis optimizations in GCC, which allows GCC to analyze beyond the boundaries of a single function body when optimizing. |
| `-fomit-frame-pointer` | Tells the compiler not to reserve one of the general-purpose registers for holding the frame pointer, allowing it to be used for other things. |
| `-m4-single(-only)` | Sets the SH4 FPU mode. `-m4-single-only` implicitly converts every single `double` to `float`. `-m4-single` still supports `double` precision but defaults to single precision upon function entry. |
| `-fno-pic/-fno-pie` | Disables position-independent code, which can lose a bit of performance due to indirection and relative offsetting. |
| `-DNDEBUG` | Denotes a release build; disables assertion checks within codebases. |

For reference, the Bruce's Balls example builds with `-std=gnu2x -O3 -fomit-frame-pointer -flto -fbuiltin -ffast-math -ffp-contract=fast -mfsrra -mfsca -fmerge-all-constants -funroll-loops -fno-PIC -fipa-pta -ftree-vectorize`.

## Mixing optimization levels

While it may seem obvious that your entire project should be compiled at the highest optimization level for maximum performance (`-O3`), real-world projects can rarely afford such a luxury due to this bloating the code segment size and wasting space. For this reason, Falco typically opts to use `-Os` for the entire codebase as the default optimization level, favoring small code size, then creates an explicit list of "hot path" files within the build which get the `-O3` treatment. Good candidates are typically translation units involving rendering, collision, and physics.

By using `-Os` globally with a static list of hand-picked translation units getting `-O3`, the GTA3 and Vice City ports were able to achieve within 1 FPS of the performance from compiling everything with `-O3` while simultaneously saving nearly a megabyte of RAM on code size.

## Selective fast math

Ideally, you would enable `-ffast-math` along with `-mfsca` and `-mfsrra` globally for KOS, any kos-ports you are using, SH4ZAM, and within your codebase. Unfortunately, because it no longer ensures strict IEEE floating-point compliance, sometimes doing so can result in very broken builds, typically manifesting in rendering, collision, physics, or other FP-heavy code.

Should this happen, and you need to disable `-ffast-math`, SH4ZAM is smart enough to fall back to inline asm for `FSCA` and `FSRRA` rather than relying on the compiler to emit them. It is still advised that you isolate the offending source files and add them to an explicit list that does not use `-ffast-math` within your build system, allowing everything else that doesn't break to still use it.

## FP precision modes

Typically, a regular C or C++ programmer should never have to care about the precision modes, unless they are relying on some high-precision `double` value that gets inadvertently truncated to `float` when using `-m4-single-only`.

`-m4-single` allows you to mix `double` and `float` variables, swapping the SH4's FPU mode as needed, allowing you to use `float` for speed and `double` for precision, with the compiler automatically switching back to single-precision `float` mode upon each function entry.

There is a trap with `-m4-single` when doing low-level programming with inline assembly routines such as those in SH4ZAM. All of SH4ZAM's inline asm routines assume they are called with the SH4 in single-precision mode, which is the default on function entry. But since these functions are largely inlined, a `double` used within the function making the SH4ZAM call can leave the CPU in double-precision mode, breaking the program.

The golden rule when mixing `-m4-single`, `double` variables and inline asm: NEVER let `double` precision variables get anywhere near your inline SH4 assembly routines which do FP calculations, ensuring the SH4 is always in single-precision mode when entering such routines.

Upstream's tips describe `assert()` checks of the FP precision mode around the inline asm routines. The debug asserts in the SH4 routines cover alignment, sizes and indices, not the FPU mode, so don't count on a debug build to catch a stray `double`.

### Double promotion

Be aware of the circumstances under which single-precision floating-point values get promoted to double precision, as this is an insidious way to lose performance without realizing it. ALWAYS use the `f` suffix with floating-point literals, such as `10.0f` rather than `10.0`, which is a `double`, not a `float`.

Beware of binary arithmetic between a `float` and a `uint32_t`: the SH4's integer-to-float conversion can only convert *signed* integers, so math between a `float` and a 32-bit *unsigned* integer takes a slow path where both values are promoted to `double` first. Since the SH4 has an instruction, `extu.w`, to extend a 16-bit unsigned integer to a 32-bit signed integer, arithmetic between a `float` and a `uint16_t` does not have the same penalty.

## Non-debug builds

KallistiOS, SH4ZAM, and many other libraries use `assert()` to add extra validation and sanity checks, so that potential bugs are caught immediately in debug builds for the price of a little performance. When profiling and releasing, build everything with `-DNDEBUG` to disable those checks. If you run into issues and need help debugging, rebuild a debug binary with `assert()` enabled to see if it catches anything bad.

## Fast division and inversion

When you know the denominator will always be positive, and some precision loss is acceptable, multiply the numerator by `shz_invf_fsrra(denominator)`. When the denominator is not guaranteed to be positive, use `shz_invf(denominator)`. This trick is most commonly leveraged for perspective division during T&L.

```c
#include <sh4zam/shz_scalar.h>

// w is known to be > 0 here (points in front of the camera).
float inv_w = shz_invf_fsrra(w);
float sx = x * inv_w;
float sy = y * inv_w;
```

Bruce's Balls warns about why the precondition matters: the `FSRRA` trick only returns the absolute value, so it has the wrong sign when inverting negatives. See [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/#_fsrra).

## Faster perspective division

The `FTRV` instruction for transforming a vector by a matrix produces each component of the resulting vector, going from X to W, one cycle after another:

| Component | Cycle |
| --- | --- |
| X | 4 |
| Y | 5 |
| Z | 6 |
| W | 7 |

Unfortunately, T&L typically necessitates dividing each component by W, which means its result is needed first, despite it coming last.

You can use `shz_xmtrx_load_wxyz_4x4()` to load a 4x4 matrix with the W column coming first, allowing you to use its result first, on cycle 4, rather than having to wait until cycle 7. Bruce's Balls gets the same effect by building its projection on top of `shz_xmtrx_init_permutation_wxyz()` and swizzling each result back with `shz_vec4_swizzle(v, 1, 2, 3, 0)`. The [XMTRX concept page](https://sh4zam.com/concepts/xmtrx/#getting-w-first) walks through it.

## Cache and FPU details

For prefetching and cache-line allocation see [`SHZ_PREFETCH`](https://sh4zam.com/api/memory/SHZ_PREFETCH/) and [`shz_dcache_alloc_line`](https://sh4zam.com/api/memory/shz_dcache_alloc_line/); for `FIPR` and `FTRV` behavior see [The SH4 FPU](https://sh4zam.com/concepts/sh4-fpu/) and the deep dives on [Resources](https://sh4zam.com/resources/).

## Related

- [The SH4 FPU](https://sh4zam.com/concepts/sh4-fpu/)
- [Matrix Transforms](https://sh4zam.com/guides/matrix-transforms/)
- [Examples](https://sh4zam.com/guides/examples/)
- [Resources](https://sh4zam.com/resources/)


---
# Testing and Contributing

Source: https://sh4zam.com/guides/testing-and-contributing/

> Build and run the SH4ZAM unit tests on Dreamcast or on the host, and what to know before opening a PR

SH4ZAM's unit tests live in `test/` and build into a single binary, `Sh4zamTests`, which runs on real hardware, in an emulator, or on your host machine with the software back-end. The contribution policy fits in a sentence: pretty casual and easy-going, nothing super formal required.

## How the tests work

- One test suite per module: `shz_scalar_test_suite.cpp`, `shz_trig_test_suite.cpp`, `shz_vector_test_suite.cpp`, `shz_quat_test_suite.cpp`, `shz_matrix_test_suite.cpp`, `shz_xmtrx_test_suite.cpp`, `shz_complex_test_suite.cpp`, `shz_mem_test_suite.cpp`, plus shared helpers in `shz_test.{c,h,hpp}`.
- The harness is [libGimbal](https://github.com/gyrovorbis/libgimbal)'s test framework (`GBL_TEST_CASE`, `GBL_TEST_VERIFY`).
- [cglm](https://github.com/recp/cglm) is linked as a reference implementation that results are compared against. On Dreamcast it is built with `-fno-fast-math`.
- Both are git submodules (`test/libgimbal`, `test/cglm`), so clone with `--recurse-submodules` or run `git submodule update --init`.
- The suites build as C17 and C++23.
- Benchmarks are reported alongside the tests (perf counters on SH4, `std::chrono` elsewhere). Configure with `-DSHZ_DISABLE_BENCHMARKS=ON` to turn them off.

## Run on Dreamcast

From a SH4ZAM checkout with your KOS `environ.sh` sourced:

```sh
make run        # build Sh4zamTests.elf and run it with $(KOS_LOADER)
make flycast    # or run it in the flycast emulator
make rerun      # clean, rebuild and run
```

`make tests` only builds the binary (`build/test/Sh4zamTests.elf`). Pass `SHZ_BACKEND=SW` to test the software back-end on the Dreamcast itself.

## Run on the host

The software back-end runs everywhere, which makes it the quick sanity check:

```sh
make check-sw
```

That configures a fresh `build-sw` directory with `-DSHZ_ENABLE_TESTS=on` using Ninja, builds, and runs `build-sw/test/Sh4zamTests`. Without the Makefile:

```sh
cmake -S . -B build-sw -G Ninja -DSHZ_ENABLE_TESTS=on
ninja -C build-sw
build-sw/test/Sh4zamTests
```

## Before you open a PR

From upstream's contributing guide:

- **Anything that adds value is welcome**: new API routines, optimizing existing implementations, new examples, better test coverage, documentation of any kind, code comments and typo fixes. Don't be shy.
- **Describe your changes** as well as you can; there is no formal PR template. If you want early feedback, open the PR as a draft.
- **Coding style** should stay consistent, but juicy optimizations won't be turned down over little style inconsistencies.
- **Doxygen comments**: everything in the public API should be fully Doxygen commented. If that's too much of a PITA, say so in the PR and you'll be covered.
- **Unit tests**: the project is striving for 100% coverage. At minimum, run the existing tests to make sure you haven't broken anything that does have coverage.
- **C++ bindings** are kept in sync with the C API, but C and SH4 contributors aren't expected to write idiomatic C++ bindings themselves; Falco will handle it.

The [Code of Conduct](https://github.com/gyrovorbis/sh4zam/blob/master/CODE_OF_CONDUCT.md) is one line: don't be a dick.

## Related

- [Contributing](https://sh4zam.com/contributing/)
- [Install with CMake](https://sh4zam.com/guides/install-cmake/)
- [Back-ends](https://sh4zam.com/concepts/backends/)
- [Community](https://sh4zam.com/community/)


---
# Using Within a Project

Source: https://sh4zam.com/guides/using-in-a-project/

> Include the SH4ZAM headers and link libsh4zam.a from a KallistiOS Makefile or CMake project

In order to use SH4ZAM within your KOS-based Dreamcast project, you must do two things: include the header file(s) within your code, and link to the statically linked library, `libsh4zam.a`, within your build system. Unless you link to SH4ZAM, your project will compile correctly, yet fail to link.

## Include

| Header | Gives you |
| --- | --- |
| `<sh4zam/shz_sh4zam.h>` | The whole C API. |
| `<sh4zam/shz_sh4zam.hpp>` | The whole C++ API (which includes the C API). |
| `<sh4zam/shz_<module>.h>` | One C module: `shz_scalar.h`, `shz_trig.h`, `shz_vector.h`, `shz_quat.h`, `shz_matrix.h`, `shz_xmtrx.h`, `shz_complex.h`, `shz_mem.h`, `shz_cdefs.h`, `shz_version.h`. |
| `<sh4zam/shz_<module>.hpp>` | The same module's C++ API. |

```c
#include <sh4zam/shz_sh4zam.h>     // C
```

```cpp
#include <sh4zam/shz_sh4zam.hpp>   // C++
```

Headers with the `.h` extension hold only documented declarations; implementations live in `inline/` and are pulled in automatically. You never include anything from `inline/` yourself. See [Architecture](https://sh4zam.com/concepts/architecture/).

## Link with a Makefile

To link to SH4ZAM using a standard, KallistiOS-style `Makefile`, pass the `-lsh4zam` flag to the compiler along with any other libraries you are using, which typically looks something like this:

```make
$(TARGET): $(OBJS)
	kos-cc -o $(TARGET) $(OBJS) -lsh4zam
```

The Bruce's Balls example links with `-lsh4zam -lkosutils -lm -Wl,--gc-sections`.

## Link with CMake

To link to SH4ZAM using `cmake` as your build system, add the following line to your `CMakeLists.txt`:

```cmake
target_link_libraries(MyProject PUBLIC -lsh4zam)
```

If SH4ZAM is part of your CMake tree (`add_subdirectory()`), link the `sh4zam` target instead so you also inherit its include path and its `SHZ_BACKEND` / `SHZ_TLS_MODEL` definitions:

```cmake
target_link_libraries(MyProject PUBLIC sh4zam)
```

## Build flags

The SH4 back-end assumes the FPU is in single-precision mode (`-m4-single` or `-m4-single-only`); see [Back-ends](https://sh4zam.com/concepts/backends/#targets-are-not-back-ends) for other modes. Release builds should define `NDEBUG`: SH4ZAM asserts alignment and sizes in debug builds. The rest of the flags that matter are in [Optimization Tips](https://sh4zam.com/guides/optimization/).

## Check the version you linked

`shz_version.h` lets you compare the headers you compiled against with the library you linked:

```c
#include <assert.h>
#include <sh4zam/shz_version.h>

void check_sh4zam(void) {
    assert(shz_version_linked() == SHZ_VERSION);
}
```

## Related

- [Getting Started](https://sh4zam.com/guides/getting-started/)
- [Install with KallistiOS](https://sh4zam.com/guides/install-kallistios/)
- [Install with CMake](https://sh4zam.com/guides/install-cmake/)
- [Version API](https://sh4zam.com/api/version/)


---
# Resources

Source: https://sh4zam.com/resources/

> SH4 instruction set references, manuals, ABI docs, pipeline simulators and optimization guides for Dreamcast development

The following is a compilation of additional resources for low-level development and optimizations targeting the SH4 processor. Many of these were used to aid in the development of SH4ZAM itself. The list is upstream's, from `doc/resources.dox`.

| Link | Description |
| --- | --- |
| [SH Instruction Set Summary](https://shared-ptr.com/sh_insns.html) | Easy-to-navigate instruction set reference for the SuperH processor line. |
| [Compiler Explorer Templates](https://dreamcast.wiki/SH4_in_Compiler_Explorer) | Preconfigured templates for viewing SH4 disassembly from KOS-based C/C++ source code within the web browser. |
| [SH4 Programming Manual](https://0x04.net/~mwk/doc/sh/e602156_sh4.pdf) | Detailed information on the SH4's instruction set. |
| [SH4A Hardware Manual](https://www.renesas.cn/zh/document/mah/sh-4a-core-extended-functions-users-manual-hardware) | Detailed information about the SH4's peripherals and HW. |
| [SH4 C ABI Specification](https://www.st.com/resource/en/reference_manual/rm0197-sh4-generic-and-c-specific-application-binary-interface-stmicroelectronics.pdf) | Documents the C binary interface and calling convention. |
| [SH4 Pipeline Simulator](https://sh4-sim.dreamcast.wiki/) | Low-level SH4 pipeline simulator for manually scheduling instructions. |
| [SH4 Optimization Tips](https://dreamcast.wiki/Development#Optimization) | Dreamcast.wiki's list of useful optimization tips. |
| [Reversing SH4 Vector Instructions](https://drk.emudev.org/blog/sh4-fpu/) | Deep-dive into how FIPR, FTRV, FSCA, and FSRRA actually work on the HW. |
| [SH4 Vector FPU Calculator](https://drk.emudev.org/sh4-vector-calculator/) | Interactive calculator, visualizing the circuitry of the SH4 VFPU. |
| [SuperH Manuals](https://github.com/KitsunebiGames/SuperH-Manuals) | GitHub repository containing a collection of manuals for the SuperH architecture. |

## On this site

- [The SH4 FPU](https://sh4zam.com/concepts/sh4-fpu/): a short glossary of `FIPR`, `FTRV`, `FSCA`, `FSRRA`, XMTRX, store queues and prefetch.
- [Optimization Tips](https://sh4zam.com/guides/optimization/): compiler flags and FPU precision modes.
- [Getting Started with Dreamcast development](https://dreamcast.wiki/Getting_Started_with_Dreamcast_development): the community guide to setting up KallistiOS.

## Related

- [The SH4 FPU](https://sh4zam.com/concepts/sh4-fpu/)
- [Optimization Tips](https://sh4zam.com/guides/optimization/)


---
# Showcase

Source: https://sh4zam.com/showcase/

> Dreamcast ports, engines and demos accelerated with SH4ZAM, from Mario Kart 64 DC to Quake 2 DC and the Simulant engine

The following projects have been successfully accelerated with SH4ZAM and make great references. The list is upstream's, from the SH4ZAM README.

| Project | Description |
| --- | --- |
| [SH4ZAM PVR](https://github.com/dfchil/sh4zam_pvr) | Advanced PVR DR rendering examples with SH4ZAM acceleration. |
| [Mario Kart 64 DC](https://github.com/jnmartin84/mk64-dc) | jnmartin's Mario Kart 64 DC port with SH4ZAM acceleration. |
| [Star Fox 64 DC](https://github.com/jnmartin84/sf64-dc) | jnmartin's Star Fox 64 DC port with SH4ZAM acceleration. |
| [Super Mario 64 DC](https://github.com/jnmartin84/sm64-dc) | Super Mario 64 DC port with SH4ZAM acceleration. |
| [FFFFTT](https://github.com/meisei4/fffftt) | Audio signal visualizations, with SH4ZAM accelerated FFT and more. |
| [Sonic Mania DC](https://github.com/michael-fadely/Sonic-Mania-Decompilation) | Sonic Mania DC port with SH4ZAM acceleration. |
| [Simulant Engine](https://gitlab.com/simulant/simulant) | General-purpose cross-platform engine backed by SH4ZAM math. |
| [Meese Engine](https://meese4.github.io/) | Open-world voxel game built for the GC, using the SH4ZAM SW back-end. |
| [Quake 2 DC](https://github.com/Bruceleeto/Quake2) | Port of Quake 2 to the DC, with SH4ZAM accelerated matrix math. |
| [DCSinge](https://github.com/GPF/DCSinge) | Singe API + FMV playback engine on DC using SH4ZAM memory routines. |
| [Xash3D DC](https://github.com/maximqaxd/xash3d-fwgs_dc/tree/pvrrender) | SH4ZAM'd up DC port of the Half-Life compatible Xash3D engine. |
| [Gael Force](https://mrtheplague1.itch.io/gael-force) | Stylized tactical RPG with sprites, 3D worlds, and dynamic lighting effects. |
| [DMS-Engine](https://github.com/Bruceleeto/DMS-Engine) | Bruceleet's "Dreamcast Mesh Shit" Engine, SH4ZAM'd to hell with skinning. |
| [The Cave](https://freakdave.itch.io/dreamcast-the-cave-tech-demo) | FreakDave's SH4ZAM-boosted DC tech demo with impressive lighting and effects. |
| [Audio Visualizer](https://www.youtube.com/watch?v=2KR_PtF_33c) | Brielle Garcia's CD Audio Visualizer for Dreamcast, using SH4ZAM math routines. |
| [DemoTek](https://youtu.be/GfbITGBcHHY?si=TwwZWQhc9E8sfbyi) | Crash Bandicoot-style 3D platformer, with SH4ZAM'd up 3D transform math. |
| [QuakeSpasm DC](https://github.com/maximqaxd/quakespasm) | Sega Dreamcast port of QuakeSpasm, with native PVR renderer + SH4ZAM math. |
| [Monkey Ball DC](https://www.youtube.com/watch?v=277AUBanFAQ) | Reimplementation of Monkey Ball using GameCube assets from Super MB. |
| [Elias Daler Work](https://www.youtube.com/watch?v=8S58Di7aMEk) | Renowned PS1 homebrew dev uses SH4ZAM for his beautiful DC experiments. |
| [Diddy Kong Racing DC](https://github.com/Bruceleeto/Diddy-Kong-Racing) | Rare's renowned N64 kart racer, ported to the DC. SH4ZAMed to all hell for gainz. |

## Examples in the repo

| Example | Description |
| --- | --- |
| [Bruce's Balls](https://sh4zam.com/guides/examples/#bruces-balls) | Pushes up to 4.5 million PPS, rendering Bruce's balls. |
| [PVR DMA](https://sh4zam.com/guides/examples/#pvr-dma) | Real-world, complex renderer using KOS's PVR DMA API. |

Shipped something with SH4ZAM? Say so in `#sh4zam` on the [Simulant Discord](https://discord.gg/G2Ay9kxec2) or open a PR adding it to the upstream README.

## Related

- [Examples](https://sh4zam.com/guides/examples/)
- [Community](https://sh4zam.com/community/)