Skip to main content

Crate ggmath

Crate ggmath 

Source
Expand description

§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>.
  • Quaternions (todo): Quat<T>.
  • Affine Transformations (todo): Affine2<T>, Affine3<T>.
  • Masks: Mask2<T>, Mask3<T>, Mask4<T>.

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

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

Because unaligned types are not SIMD-aligned, 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>.

Where:

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

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

§Another Math Crate???

ggmath distinguishes itself from other math crates by having both generics and SIMD. Existing crates either have generics but not SIMD, or have SIMD but not generics.

Generics make it possible to use custom types inside math types (e.g., Vec3<FixedPoint>), and reduce code duplication when code needs to work for multiple types and or dimensions. Keep in mind that generics also increase compile times, and are unnecessary if you only intend to use one scalar type (e.g., f32).

SIMD, or more specifically SIMD-aligned types usually result in better performance than normal types.

ggmath also (todo, not yet) supports SoA (Struct of Arrays, e.g., Vec3<f32x4>) SIMD via integration with the crate wide. SoA types are harder to use but have even better performance than normal AoS (e.g., SIMD-aligned Vec3<f32>) types.

ggmath doesn’t have high level, controversial types (e.g., point types). ggmath is designed so that an external crate could add those types on top of ggmath.

Featureggmathglamultravioletcgmath
Generics✅❌❌✅
SIMD-aligned types✅✅✅❌
SoA(todo)❌✅❌
Controversial Types❌❌✅✅

§Development Status

ggmath is not mature yet but is under active development.

Feature List:

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

Crate Support:

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>

§Usage

Add this to your Cargo.toml:

[dependencies]
ggmath = "0.16.0"

For no_std support, enable the libm feature:

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

For no_std without libm, disable default features:

[dependencies]
ggmath = { version = "0.16.0", 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
Creates a 2-dimensional vector from the provided arguments.
vec3
Creates a 3-dimensional vector from the provided arguments.
vec4
Creates 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.
Mask
A generic vector mask.
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 elements of math types.
ScalarBackend
Controls the implementation of math functions.
SupportedLength
Marker trait restricting the length of math types.

Type Aliases§

Mask2
A 2-component vector mask.
Mask3
A 3-component vector mask.
Mask4
A 4-component vector mask.
Mask2U
A 2-component vector mask.
Mask3U
A 3-component vector mask.
Mask4U
A 4-component vector mask.
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.