SH4ZAM! 0.9.1

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. Or by hand:

cd kos-ports/sh4zam && make install

CMake (any platform):

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.

Usage

C23

#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

#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

Scalar math operations, including faster <math.h> replacements.

Trigonometry

Trig, inverse trig and hyperbolic functions, with FSCA sine/cosine pairs.

Vector

2D, 3D and 4D vector types and operations.

Matrix

2x2, 3x3, 3x4, 4x3 and 4x4 matrix types, in memory.

Quaternion

Quaternion math operations, including slerp and squad.

XMTRX

API for manipulating the 4x4 back-bank of FP registers, the SH4's active matrix.

Complex

Complex and imaginary math API, including an accelerated FFT.

Memory

Memory routines: memcpy() and memmove() replacements, store queues, cache control.

Every public symbol has its own page. The 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 and Naming and Suffixes.

Showcase

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

Project	Description
Mario Kart 64 DC	jnmartin's Mario Kart 64 DC port with SH4ZAM acceleration.
Super Mario 64 DC	Super Mario 64 DC port with SH4ZAM acceleration.
Sonic Mania DC	Sonic Mania DC port with SH4ZAM acceleration.
Quake 2 DC	Port of Quake 2 to the DC, with SH4ZAM accelerated matrix math.
Simulant Engine	General-purpose cross-platform engine backed by SH4ZAM math.
Diddy Kong Racing DC	Rare's renowned N64 kart racer, ported to the DC. SH4ZAMed to all hell for gainz.

All twenty projects are on the Showcase page.

Community

The #sh4zam channel within the Simulant Discord Server 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 for any issues or feature requests.