Crate ggmath 

ggmath

A math library for games and graphics with support for generics and SIMD.

The library features:

• Vectors: Vec2<T>, Vec3<T>, Vec4<T>.
• Square Matrices (todo): Mat2<T>, Mat3<T>, Mat4<T>.
• Quaternion (todo): Quat<T>.
• Affine Transformations (todo): Affine2<T>, Affine3<T>.
• Masks (todo): Mask2<T>, Mask3<T>, Mask4<T>.

For appropriate scalars, these types are aligned for SIMD to improve performance. The library also features unaligned types:

• Vectors: Vec2U<T>, Vec3U<T>, Vec4U<T>.
• Square Matrices (todo): Mat2U<T>, Mat3U<T>, Mat4U<T>.
• Quaternion (todo): QuatU<T>.
• Affine Transformations (todo): Affine2U<T>, Affine3U<T>.
• Masks (todo): Mask2U<T>, Mask3U<T>, Mask4U<T>.

Unaligned types have the same functionality as aligned types, but are not aligned for SIMD meaning they take less memory but have slower operations.

All types are type aliases to these generic structs:

• Vector<N, T, A>.
• Matrix<N, T, A> (todo).
• Quaternion<T, A> (todo).
• Affine<N, T, A> (todo).
• Mask<N, T, A> (todo).

Where:

• N is the length (2, 3, or 4).
• T is the scalar type.
• A is either Aligned or Unaligned.

Generic structs are used to implement functionality for all lengths and or both alignments without duplicating code or using macros.

Development Status

ggmath is not mature yet but is under active development.

Feature List:

• Vectors
• Square Matrices
• Quaternion
• Affine Transformations
• Masks
• Sufficient Float-Vector functionality
• Sufficient Int-Vector functionality
• Sufficient Matrix functionality
• Sufficient Quaternion functionality
• Sufficient Affine functionality

Crate Support:

• bytemuck
• fixed
• libm
• mint
• serde
• wide

Performance:

• f32 SSE2 optimizations
• f32 SSE4.2+ optimizations
• f64 AVX+ optimizations
• i32 u32 SSE2+ optimizations
• i8 u8 bool SSE2+ optimizations for Mat4<T>
• i16 u16 AVX2+ optimizations for Mat4<T>
• f32 NEON optimizations
• i32 u32 NEON optimizations
• i8 u8 bool NEON optimizations for Mat4<T>
• f32 WASM optimizations
• i32 u32 WASM optimizations
• i8 u8 bool WASM optimizations for Mat4<T>

Comparison to glam

glam is more mature than ggmath. This comparison assumes ggmath has reached the maturity of glam. If you need any of the features missing from ggmath, you should use glam.

The primary difference between the two crates is that ggmath uses generics and glam intentionally doesn’t. You should pick a crate based on these pros and cons:

Code Duplication

Generics eliminate code duplication by enabling code that is generic over scalar type, vector length, and alignment.

This is primarily useful for writing math functions that need to work for multiple scalar types, all lengths, or both SIMD and no SIMD. For example, a cross platform deterministic implementation of sin would need to be duplicated multiple times when using glam, but will only need to be written once using ggmath.

Custom Scalar Types

Generics make it possible to define custom scalar types.

This is primarily useful for either fixed point numbers (e.g., support for the fixed crate), or SoA storage (Struct of Arrays) (e.g., Vec3<f32x4> using the wide crate).

Compile Times

To properly support generics, ggmath internally uses many language tricks that unfortunately add work for the compiler not only when compiling ggmath, but also when compiling math code that uses it.

If you need the fastest compile times possible you should use glam.

Complexity

Generics make ggmath harder to understand in advance scenarios.

While the API is mostly similar (Vec3<f32> vs Vec3A), ggmath has some advanced features that are harder to understand than anything in glam (e.g., the full generic form Vector<N, T, A>).

Usage

Add this to your Cargo.toml:

[dependencies]
ggmath = "0.15.1"

For no_std support, enable the libm feature:

[dependencies]
ggmath = { version = "0.15.1", features = ["libm"] }

For no_std without libm, disable default features:

[dependencies]
ggmath = { version = "0.15.1", default-features = false }

Without std or libm, the crate compiles but all float functionality that relies on a backend is disabled.

Optional Features

• std (default feature): Uses std as the backend for float functionality.

• assertions: Enables assertions in release mode. Assertions are panics that catch invalid input and are enabled by default in debug mode.

• no-assertions: Disables assertions in debug mode. Library crates should not directly enable assertions or no-assertions and should leave the decision to binary crates.

• bytemuck: Implements bytemuck traits for all ggmath types.

• libm: Uses libm as the backend for float functionality. This makes the crate no_std even if the std feature isn’t disabled.

• mint: Implements conversions between ggmath and mint types.

• serde: Implements Serialize and Deserialize for all ggmath types.

Attribution

The design of ggmath is heavily influenced by glam, as it serves the same purpose as glam but with generics.

Most optimizations in ggmath are taken directly from glam and wide.

License

Licensed under either Apache License Version 2.0 or MIT license at your option.

Modules

constants

Traits for scalar constants like ZERO, ONE and NAN.

Macros

vec2

Constructs a 2-dimensional vector from the provided arguments.

vec3

Constructs a 3-dimensional vector from the provided arguments.

vec4

Constructs a 4-dimensional vector from the provided arguments.

Structs

Aligned

Marker type indicating SIMD-aligned math types.

Length

Marker type representing the length of a math type.

Unaligned

Marker type indicating non SIMD-aligned math types.

Vector

A generic vector type.

Traits

Alignment

Marker trait controlling SIMD alignment for math types.

FloatExt

An extension trait for float primitives.

Scalar

A trait for types that can be stored in vectors.

ScalarBackend

A trait to control the implementation of math types.

ScalarDefault

A default implementation for ScalarBackend.

SupportedLength

Marker trait restricting the length of math types.

Type Aliases

Vec2

A 2-dimensional vector.

Vec3

A 3-dimensional vector.

Vec4

A 4-dimensional vector.

Vec2U

A 2-dimensional vector.

Vec3U

A 3-dimensional vector.

Vec4U

A 4-dimensional vector.