This document describes the high-level architecture of glam
. While glam
is not a large library there are some complexities to its implementation. The rational and explanation of these follows.
There overarching design goals of glam are:
One of the core premises of glam
was that using SSE2 instructions on x86
and x86_64
architectures gave better performance than using Rust's built in f32
type. For more on this finding see Optimising path tracing with SIMD.
I also wanted to have a f32
fallback when SIMD was not available.
Because internally storage could be a SIMD vector intrinsic like __m128
on x86
or say an array of f32
if SSE2 was not available, a simple generic parameter like Vec4<T>
could not be used. The T
would specify the public facing type, but not storage. Perhaps this could be achieved with a second generic parameter for storage, e.g. Vec4<f32, __m128>
or Vec4<f32, [f32; 4]>
but I felt that such a design would introduce a lot of complexity that end users would ultimately be burdened with, so it's not something that was pursued.
Generics can also increase compile time and code size which is something glam wants to avoid.
glam
also mostly avoids using traits in the public interface. Primarily because there wasn't a good reason to. A Vec3
is not an interface, it is a concrete type. The secondary reason is traits fragment documentation. If the functionality of a Vec3
is implemented across a number of different traits then the documentation of all of the Vec3
methods will be on the individual traits, not the Vec3
itself. This makes it harder for users to find what methods a struct actually implements as the documentation is not in one place.
Conversely glam
does use traits for swizzle methods so that the documentation for these methods is on the trait and not the Vec2
, Vec3
, Vec4
and so on structs. There are many swizzle methods which would clutter the documentation, making them a trait means they won't pollute documentation.
Initially glam
only supported f32
which kept the internal implementation relatively simple. However users also wanted support for other primitives types like f64
, i32
and u32
. Because glam
avoids using generics
adding support for other primitive types without a lot of code duplication required some additional complexity in implementation.
glam
supports a number of permutations of vector, quaternion and matrix types for f32
, f64
, i32
and u32
primitives, with SSE2 or wasm32 for some f32
types and scalar fallbacks if SIMD is not available.
The Deref
trait is used to provide direct access to SIMD vector components like .x
, .y
and so on. The Deref
implementation will return XYZ<T>
structure on which the vector components are accessible. Unfortunately if users dereference the public types they will see confusing errors messages about XYZ
types but this on balance seemed preferable to needing to setter and getting methods to read and write component values.
See [codegen/README.md] for information on glam
's code generation process.