Realtime Math 2.4 is out!

The latest release of Realtime Math (RTM) contains many changes. I’ll highlight the most important ones here. See the changelog for the full list.

Browsable documentation

RTM now has a documentation site. It has the guides of the docs directory and an API reference with one page for each public header. Previously, the documentation of each function could only be found in the comments of the headers. Now, Doxygen reads the /// comments, a script converts its output to Markdown, and MkDocs makes the site.

The site has one version for the develop branch and one version for each release, starting with 2.4. A version selector at the top of each page switches between them.

ARM64 float64 uses SIMD

Prior to this releasee, all the float64 types used scalar math. A vector4d or a quatd held 4 double values, and the code processed one lane at a time. Now, RTM uses SIMD for them as well just like it does with SSE/AVX.

ARMv8 added float64 instructions to NEON, but a NEON register holds only 2 float64 lanes. SSE2 has the same limit, and so both use two registers to hold four values.

The new layout also changes how a function receives these types. ARM64 passes an aggregate of up to 4 vector registers in registers. A vqd or a vqsd holds 4 registers, thus RTM now passes both inputs of their functions by register. Previously, the caller wrote the second input to the stack and passed a pointer. The larger types, vqvd and the float64 matrices, now go by reference, and this removes a copy to the stack.

WASM now supports SIMD

RTM now supports WebAssembly SIMD128. Compile with -msimd128 to enable it, and RTM then defines RTM_WASM128_INTRINSICS. The Emscripten unit tests now use WebAssembly SIMD by default.

QV, QVS, and QVV have been renamed

I originally named these types for their memory layout, but this brought little value because the layout is an implementation detail. Now, the transform types follow the names of the mathematics literature: VQ, VQS, VQV, and the new VQM. This makes it easier for people who search for them to find RTM. The old types and functions remain, but they are all deprecated, and RTM 2.5 will remove them.

VQM support

Michael Aristidou and Xin Li introduced VQM in The VQM-Group and its Applications. I came across it over a decade ago, and it took me many years to find the time to study it. A VQM transform is similar to a VQS: both hold a rotation in a quaternion and a translation in a 3D vector. But where a VQS holds a uniform scale in a single scalar, a VQM holds a 3x3 matrix with a non-uniform scale and shear. As with an affine matrix, the product of two VQM transforms is exact. As with a VQS, a VQM interpolates well, and thus it is very useful for gamedev applications (e.g. gameplay, animation). To my knowledge, RTM is the first open source math library to implement it. The types are vqmf and vqmd, in rtm/vqmf.h and rtm/vqmd.h.

In the coming weeks, I will be posting about affine transforms and how to represent them. I’ll cover how they work, why they work, and the tradeoffs of each variant.