# 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.