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.