sh4zam

---

Overview

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.

Features

• Dual, modern, interoperable C11 and C++17 APIs
• Extra API features supported for C23, C++20 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 and external Doxygen site
• Software back-end for using SH4ZAM in cross-platform codebases

APIs

• Scalar math operations, including faster <math.h> replacements
• Trigonometry functions, inverse and hyperbolic trig functions
• Vector types: 2D, 3D, 4D
• Matrix types: 2x2, 3x2, 3x3, 3x4, 4x3, and 4x4
• Quaternion math operations
• XMTRX API for manipulating 4x4 back-bank of FP registers
• Complex and imaginary math API, including accelerated FFT
• Memory routines (memcpy(), memset(), memmove(), etc)

Usage

C23

For C code, include the header files with the .h extensions or sh4zam/shz_sh4zam.h to include everything.

#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_rotate_x(shz_vec4_dot(vec1, vec2));
    shz_xmtrx_add_translation(vec1.x, vec1.y, vec1.z);
    shz_xmtrx_store_4x4(&mat);

    shz_vec4_t vec3 = shz_xmtrx_transform_vec4(vec2);

    return 0;
}

NOTE: Where applicable, the C API also includes a variety of type-generic routines which will automatically resolve to calling the proper functions based on argument type. for example, shz_vec_dot() will automatically forward to the proper routine based on the type of vectors passed to it.

C++23

For C++ code, include the header files with the .hpp extensions or sh4zam/shz_sh4zam.hpp to include everything.

#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::rotate_x(vec1.dot(vec2));
    shz::xmtrx::add_translation(vec1.x, vec1.y, vec1.z);
    shz::xmtrx::store(&mat);

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

    return 0;
}

NOTE: C++ 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.

Installation

KallistiOS

SH4ZAM is now an official part of kos-ports, meaning that it is now directly integrated within the KallistiOS ecosystem and will be automatically set up as part of the regular KOS installation process. If you’re following the standard community guide for Setting up KallistiOS, SH4ZAM will be installed as part of the Building KOS Ports step. If you’re using DreamSDK to manage your KallistiOS development environment, SH4ZAM may be installed from the KallistiOS Ports tab.

CMake

To quickly build the project with CMake in any environment, independently of KOS, run the following from the repo root:

mkdir build
cd build
cmake ..
make
make install

This will build and install 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. Now a separate binary for the unit test executable should be built as well.

NOTE: For KOS users, use kos-cmake instead of your system cmake command!

Git Submodule

To pin a specific version of SH4ZAM, or to use it outside of KallistiOS, add it to your project as a git submodule:

git submodule add https://github.com/gyrovorbis/sh4zam.git external/sh4zam

Then add it to your CMake build and link against the sh4zam target, which exports its include directory:

add_subdirectory(external/sh4zam)
target_link_libraries(<your_target> PRIVATE sh4zam)

Examples

Examples can be found within the example subdirectory. New examples are always welcome to be contributed!

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.

NOTE: If you’ve installed SH4ZAM through KOS-ports, the examples should get installed to kos-ports/examples/sh4zam.

Showcase

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

Project	Description
SH4ZAM PVR	Advanced PVR DR rendering examples with SH4ZAM acceleration.
Mario Kart 64 DC	jnmartin’s Mario Kart 64 DC port with SH4ZAM acceleration.
Star Fox 64 DC	jnmartin’s Star Fox 64 DC port with SH4ZAM acceleration.
Super Mario 64 DC	Super Mario 64 DC port with SH4ZAM acceleration.
FFFFTT	Audio signal visualizations, with SH4ZAM accelerated FFT and more.
Sonic Mania DC	Sonic Mania DC port with SH4ZAM acceleration.
Simulant Engine	General-purpose cross-platform engine backed by SH4ZAM math.
Meese Engine	Open-world voxel game built for the GC, using the SH4ZAM SW back-end.
Quake 2 DC	Port of Quake 2 to the DC, with SH4ZAM accelerated matrix math.
DCSinge	Singe API + FMV playback engine on DC using SH4ZAM memory routines.
Xash3D DC	SH4ZAM’d up DC port of the Half-Life compatible Xash3D engine.
Gael Force	Stylized tactical RPG with sprites, 3D worlds, and dynamic lighting effects.
DMS-Engine	Bruceleet’s “Dreamcast Mesh Shit” Engine, SH4ZAM’d to hell with skinning.
The Cave	FreakDave’s SH4ZAM-boosted DC tech demo with impressive lighting and effects.
Audio Visualizer	Brielle Garcia’s CD Audio Visualizer for Dreamcast, using SH4ZAM math routines.
DemoTek	Crash Bandicoot-style 3D platformer, with SH4ZAM’d up 3D transform math.
QuakeSpasm DC	Sega Dreamcast port of QuakeSpasm, with native PVR renderer + SH4ZAM math.
Monkey Ball DC	Reimplementation of Monkey Ball using GameCube assets from Super MB.
Elias Daler Work	Renowned PS1 homebrew dev uses SH4ZAM for his beautiful DC experiments.
Diddy Kong Racing DC	Rare’s renowned N64 kart racer, ported to the DC. SH4ZAMed to all hell for gainz.
World of Warcraft DC	WoW DC port by CYPRESS, with SH4ZAM-based math gainz.
Resident Evil 4 DC	lamb2k’s RE4 port to DC, features a build flag SH4ZAM-ing TnL.

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.

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!

Acknowledgements

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
• TechProGabe
• LobotomyDC
• Haikuno
• Brendan “Cypress” Lawson