# SH4ZAM > Fast math library for the Sega Dreamcast's SH4 CPU. Hand-optimized C17/C++20 linear algebra, trig, scalar, complex/FFT and memory routines using FIPR/FTRV/FSCA/FSRRA and the XMTRX register bank, with a portable software back-end. Version 0.9.1, generated from upstream commit ba1e30c (2026-10-18). Source: https://github.com/gyrovorbis/sh4zam. MIT license. Key facts: C prefix `shz_`, macros `SHZ_`, C++ namespace `shz::` with the `shz_` prefix dropped (`shz_sinf` -> `shz::sinf`, `shz_vec3_t` -> `shz::vec3`, `shz_quat_slerp` -> `shz::quat::slerp`, `shz_xmtrx_*` -> static members of `shz::xmtrx`). Column-major matrices; `shz_mat4x4_t` must be 8-byte aligned (`_unaligned` variants take `float[16]`). Quaternions stored W,X,Y,Z (W first). Radians by default. Single-precision `float` only. Right-handed world/view, left-handed clip space, like GL. XMTRX = the SH4 FPU back-bank 4x4 matrix: `shz_xmtrx_*` functions operate on that global (per-thread) register state, no matrix argument. Include `` (C) or `` (C++), link `-lsh4zam`. Suffixes: `_fsrra` (fast FSRRA approximation; argument/denominator must be positive), `_safe` (guards zero length/denominator), `_deg` (degrees), `u16` (16-bit fixed-point angle), `_unaligned` (no 8-byte alignment needed), `_transpose`, `_reverse` (reversed multiply order), `_wxyz` (W first out of FTRV), `_xmtrx` (memory routine that clobbers XMTRX), `sq_` (store queues). Matrix verbs: `init_*` (whole matrix), `set_*` (only those components), `apply_*` (to affected components), GL-style `translate/scale/rotate_*` (full multiply). Do not invent: `shz_memset()` does not exist (use `shz_memset8()`); `shz_xmtrx_trans_vec4()` is an old name for `shz_xmtrx_transform_vec4()`. Every symbol is listed in the JSON index; if it is not there, it is not public API. URL patterns: page `//`, Markdown twin `/.md`; symbol `/api//.md` with the exact C identifier. ## Start here - [For Agents](https://sh4zam.com/for-agents.md): 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 - [Cheatsheet](https://sh4zam.com/cheatsheet.md): The whole SH4ZAM C API on one page: every symbol with its signature and a one-line description - [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes.md): How SH4ZAM names functions, types and C++ wrappers, and what every suffix (_fsrra, _safe, _deg, _unaligned, _wxyz, sq_) means - [Conventions](https://sh4zam.com/concepts/conventions.md): Coordinate systems, column-major matrices, W-first quaternions, radians, single precision and epsilon in SH4ZAM - [XMTRX](https://sh4zam.com/concepts/xmtrx.md): The SH4's register-resident 4x4 active matrix, how SH4ZAM's XMTRX API uses it, FTRV timing, the WXYZ trick and thread safety - [Matrix Transforms](https://sh4zam.com/guides/matrix-transforms.md): Turn a CGLM-style model matrix into an optimal XMTRX sequence with init, apply, set and a single store - [Interop with Existing APIs](https://sh4zam.com/guides/interop.md): Accelerate an existing C or C++ math API with SH4ZAM using zero-cost conversions, without changing client code - [Getting Started](https://sh4zam.com/guides/getting-started.md): Install SH4ZAM, include it, link it, and build a first program in C and C++ for the Sega Dreamcast ## API reference (one page per module) - [scalar](https://sh4zam.com/api/scalar.md): Scalar functions and utilities, including faster replacements. `sh4zam/shz_scalar.h`, 56 symbols. - [trig](https://sh4zam.com/api/trig.md): Trig functions and utilities built around the SH4 FSCA instruction. `sh4zam/shz_trig.h`, 51 symbols. - [vector](https://sh4zam.com/api/vector.md): API for vector math: 2D, 3D and 4D vector types and operations. `sh4zam/shz_vector.h`, 229 symbols. - [quat](https://sh4zam.com/api/quat.md): Routines for quaternion math. `sh4zam/shz_quat.h`, 47 symbols. - [matrix](https://sh4zam.com/api/matrix.md): In-memory matrix manipulation for 4x4 and smaller matrices. `sh4zam/shz_matrix.h`, 120 symbols. - [xmtrx](https://sh4zam.com/api/xmtrx.md): API for managing the SH4's "active matrix", the 16 back-bank FP registers. `sh4zam/shz_xmtrx.h`, 156 symbols. - [complex](https://sh4zam.com/api/complex.md): API for representing and operating on complex numbers, plus an SH4-optimized FFT. `sh4zam/shz_complex.h`, 52 symbols. - [memory](https://sh4zam.com/api/memory.md): Routines for copying memory, store queues, cache operations and prefetching. `sh4zam/shz_mem.h`, 23 symbols. - [cdefs](https://sh4zam.com/api/cdefs.md): Preprocessor definitions: back-end and target detection, TLS model, utilities and aliasing types. `sh4zam/shz_cdefs.h`, 67 symbols. - [version](https://sh4zam.com/api/version.md): Compile-time and link-time version checking of the SH4ZAM library. `sh4zam/shz_version.h`, 9 symbols. - [C++ API](https://sh4zam.com/api/cpp.md): classes `shz::vecN`, `shz::vec2`, `shz::vec3`, `shz::vec4`, `shz::quat`, `shz::mat4x4`, `shz::xmtrx`, `shz::sincos`, `shz::complex`, `shz::version` and the free-function aliases, each mapped to the C function it calls. - [API overview](https://sh4zam.com/api.md): module table and how to navigate. ## Guides - [Getting Started](https://sh4zam.com/guides/getting-started.md): Install SH4ZAM, include it, link it, and build a first program in C and C++ for the Sega Dreamcast - [Install with KallistiOS](https://sh4zam.com/guides/install-kallistios.md): Install SH4ZAM through kos-ports or DreamSDK, update it, and use the upstream Makefile targets - [Install with CMake](https://sh4zam.com/guides/install-cmake.md): Build and install SH4ZAM with CMake on any platform, with the SH4, SPU or portable software back-end - [Using Within a Project](https://sh4zam.com/guides/using-in-a-project.md): Include the SH4ZAM headers and link libsh4zam.a from a KallistiOS Makefile or CMake project - [Interop with Existing APIs](https://sh4zam.com/guides/interop.md): Accelerate an existing C or C++ math API with SH4ZAM using zero-cost conversions, without changing client code - [Matrix Transforms](https://sh4zam.com/guides/matrix-transforms.md): Turn a CGLM-style model matrix into an optimal XMTRX sequence with init, apply, set and a single store - [Optimization Tips](https://sh4zam.com/guides/optimization.md): Compiler flags, mixed -O levels, selective fast math, SH4 FPU precision modes, double promotion and fast division for SH4ZAM - [Examples](https://sh4zam.com/guides/examples.md): Walkthrough of Bruce's Balls, the 4.5 million polygons per second SH4ZAM benchmark, and the PVR DMA renderer example - [Testing and Contributing](https://sh4zam.com/guides/testing-and-contributing.md): Build and run the SH4ZAM unit tests on Dreamcast or on the host, and what to know before opening a PR ## Concepts - [Architecture](https://sh4zam.com/concepts/architecture.md): 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 - [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes.md): How SH4ZAM names functions, types and C++ wrappers, and what every suffix (_fsrra, _safe, _deg, _unaligned, _wxyz, sq_) means - [Types and Memory Layout](https://sh4zam.com/concepts/types-and-layout.md): Memory layout of SH4ZAM vector, quaternion, matrix, sincos and complex types, alignment rules, and how the C++ types relate - [Conventions](https://sh4zam.com/concepts/conventions.md): Coordinate systems, column-major matrices, W-first quaternions, radians, single precision and epsilon in SH4ZAM - [XMTRX](https://sh4zam.com/concepts/xmtrx.md): The SH4's register-resident 4x4 active matrix, how SH4ZAM's XMTRX API uses it, FTRV timing, the WXYZ trick and thread safety - [The SH4 FPU](https://sh4zam.com/concepts/sh4-fpu.md): Glossary of the Dreamcast SH4 floating-point hardware SH4ZAM is built on - FIPR, FTRV, FSCA, FSRRA, FMAC, XMTRX, precision modes, store queues, prefetch - [C and C++ APIs](https://sh4zam.com/concepts/c-and-cpp.md): 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 - [Back-ends](https://sh4zam.com/concepts/backends.md): SH4ZAM's SH4, software and SPU back-ends, how one is selected, targets versus back-ends, and the precision you can expect from each ## More - [Showcase](https://sh4zam.com/showcase.md): Dreamcast ports, engines and demos accelerated with SH4ZAM, from Mario Kart 64 DC to Quake 2 DC and the Simulant engine - [Resources](https://sh4zam.com/resources.md): SH4 instruction set references, manuals, ABI docs, pipeline simulators and optimization guides for Dreamcast development - [Community](https://sh4zam.com/community.md): Where to ask about SH4ZAM - the #sh4zam channel on the Simulant Discord, GitHub issues - and the people who built it - [Contributing](https://sh4zam.com/contributing.md): How to contribute to SH4ZAM, and to this documentation site - [Changelog](https://sh4zam.com/changelog.md): SH4ZAM release notes - v0.9.1, v0.9.0 and earlier ## Optional - [llms-full.txt](https://sh4zam.com/llms-full.txt): every page on this site concatenated as Markdown - [llms-api.txt](https://sh4zam.com/llms-api.txt): every API page (all 810 symbols) concatenated - [api/index.json](https://sh4zam.com/api/index.json): machine-readable symbol index ([schema](https://sh4zam.com/api/schema.json)); per-module files at `/api/.json` - [Upstream repository](https://github.com/gyrovorbis/sh4zam): headers in `include/sh4zam/`, generated from `ba1e30c88d49df0311870b229e1dd860ef26c477`