Crate ggmath

Crate ggmath 

Source
Expand description

Crates.io Docs.rs

§ggmath

A games/graphics math library with generic SIMD types.

This crate is a work in progress, so features like matrices and quaternions are missing.

§Generics

Instead of having a separate vector/matrix/etc type for each combination of dimensions and element type, ggmath has single Vector, Matrix, Quaternion, and Aabb types that are parameterized over their properties.

This approach has several advantages: it allows code to be generic over dimensions or element type, and makes it easy for users to define their own custom element types.

For non-generic use cases, ggmath has convenient type aliases like FVec3, that make the API simpler to use.

§SIMD

ggmath allows vector element types to override the storage and function implementations of vectors in order to enable SIMD optimizations.

Primitive types like f32, f64, and u64 have SIMD backends on appropriate build targets.

Custom element types can also take advantage of SIMD without using low-level intrinsics by reusing existing primitive vector types as backends.

§Features

  • Vectors of length 2, 3, or 4, with either SIMD or scalar backends
  • Type aliases for primitive vectors
  • Partially optimized SIMD backends for f32, i32 and u32

Planned Features:

  • Matrices (non-square, column-major or row-major)
  • Aabb (multiple representations, e.g., min+max or center+extents)
  • Quaternions
  • Possibly rotors

§Benchmarks & Testing

ggmath is benchmarked against glam and wide, using both microbenchmarks (with gungraun) and larger, composite benchmarks (with criterion). Currently ggmath is not optimized and benchmarked enough to beat glam.

ggmath aims for high test coverage that ensures SIMD optimizations behave correctly.

§Installation

A Rust compiler version of at least 1.90.0 is required.

Simply add the following to your Cargo.toml:

[dependencies]
ggmath = "0.13.0"

§Cargo Features

Default Features:

  • primitive_aliases: enables type aliases for primitives (e.g., FVec3).
  • std: enables features that depend on std (disable for no_std).
  • swizzle: enables functions for all swizzle combinations (e.g., wzyx).

Optional Features:

  • right, left, up, down, forwards, and backwards: enable direction constants where the given direction is positive. For example, right enables RIGHT and LEFT constants where right is positive.

Re-exports§

pub use vector::*;

Modules§

bool
Type aliases for bool math types.
f32
Type aliases for f32 math types.
f64
Type aliases for f64 math types.
i8
Type aliases for i8 math types.
i16
Type aliases for i16 math types.
i32
Type aliases for i32 math types.
i64
Type aliases for i64 math types.
i128
Type aliases for i128 math types.
isize
Type aliases for isize math types.
u8
Type aliases for u8 math types.
u16
Type aliases for u16 math types.
u32
Type aliases for u32 math types.
u64
Type aliases for u64 math types.
u128
Type aliases for u128 math types.
usize
Type aliases for usize math types.
vector
Vector related items.

Macros§

declare_vector_aliases
Declares vector type aliases for a custom scalar type.
vec2
Creates a [Simd] vector2 from two elements.
vec3
Creates a [Simd] vector3 from three elements.
vec4
Creates a [Simd] vector4 from four elements.
vec2g
Creates a vector2 from two elements, where type inference determines if it is [Simd] or [NonSimd].
vec2s
Creates a [NonSimd] vector2 from two elements.
vec3g
Creates a vector3 from three elements, where type inference determines if it is [Simd] or [NonSimd].
vec3s
Creates a [NonSimd] vector3 from three elements.
vec4g
Creates a vector4 from four elements, where type inference determines if it is [Simd] or [NonSimd].
vec4s
Creates a [NonSimd] vector4 from four elements.

Traits§

Construct
The base trait for all ggmath types. Is automatically implemented for all types that implement Send, Sync, Copy, and ['static].