Skip to main content

Crate ggmath

Crate ggmath 

Source
Expand description

A linear algebra library for games and graphics with generic SIMD types.

The library provides:

§SIMD

Appropriate types have increased memory alignment in order to take advantage of SIMD instructions that improve performance. For example, Vec3<f32>, Vec4<f32>, Mat3<f32> and Mat4<f32> are aligned to 16 bytes on x86 targets in order to take advantage of the SSE instruction set.

Although SIMD alignment generally results better performance, it can also result in wasted space. For example, due to 16-byte alignment, Vec3<f32> has 4 bytes of padding, and consequently Mat3<f32> has 12 bytes of padding. For scenarios where better performance is not worth wasted space, math types have non-SIMD, unaligned variants:

Unaligned types are optimal in memory-critical scenarios, for example when storing 3D models. In all other cases, aligned types are optimal and result in better performance than unaligned types.

Integration with wide enables SoA (Structure of Arrays) SIMD, which lets you perform operations concurrently on multiple values, for example with Vec3<f32x4> which represents four values of Vec3<f32>. SoA requires modeling algorithms in a very specific way, but can be much faster than normal types.

§Generics

Because types are generic over T, they support non-primitive scalar types (see Scalar). Integration with fixed enables support for fixed-point numbers, and integration with wide enables support for SoA.

When Rust’s type system is powerful enough, integration with num-primitive will enable writing math code that is generic over primitive types, for example functions generic over T: PrimitiveFloat will have access to float-vector functionality.

Types relative to each other (e.g., Vec2<T>, Vec3<T>, Vec4<T> and unaligned variants) are not distinct types, instead they are all type aliases to these const-generic structs:

Where:

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

Const generics eliminate the need for macros, making it easier to implement functionality for all lengths (and both alignments). For example, instead of defining seperate Ray2 and Ray3 types, it is possible to define a single Ray<N, T, A> type then define type aliases for it.

§Math conventions

The library is coordinate-system agnostic, and should work for both right-handed and left-handed coordinate systems.

Vectors are treated as column matrices, meaning when transforming a vector with a matrix, the matrix goes on the left.

Matrices are stored in column-major order, meaning each column is continuous in memory.

Angles are in radians, but can be converted to and from degrees using standard-library functions.

§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. Assertions should only be controlled by binary crates. Library crates should not set this flag directly.

  • bytemuck: Implements bytemuck traits for ggmath types.

  • fixed: Implements Scalar for fixed-point numbers.

  • fixp: Implements Scalar for fixed-point numbers.

  • libm: Uses libm as the backend for float functionality. This makes the crate no_std even if the std feature is not disabled. Without std or libm, the crate compiles but all float functionality that relies on a backend is disabled.

  • mint: Implements conversions between ggmath and mint types.

  • serde: Implements Serialize and Deserialize for ggmath types.

  • wide: Implements Scalar for SIMD types.

Modules§

constants
A module with traits for scalar constants like ZERO, ONE and NAN.

Macros§

mat2Deprecated
Creates a 2x2 column-major matrix from the provided arguments.
mat3Deprecated
Creates a 3x3 column-major matrix from the provided arguments.
mat4Deprecated
Creates a 4x4 column-major matrix from the provided arguments.
vec2Deprecated
Creates a 2-dimensional vector from the provided arguments.
vec3Deprecated
Creates a 3-dimensional vector from the provided arguments.
vec4Deprecated
Creates a 4-dimensional vector from the provided arguments.

Structs§

Affine
An N-dimensional affine transform which can represent translation, rotation, scaling and shear of type T.
Aligned
A marker type specifying SIMD alignment.
Length
A marker type to restrict const N: usize to 2, 3 and 4.
Mask
An N-element vector mask optimized for type T.
Matrix
An NxN column-major matrix of type T.
Quaternion
A quaternion representing an orientation of type T.
Unaligned
A marker type specifying lack of SIMD alignment.
Vector
An N-dimensional vector of type T.

Traits§

Alignment
A marker trait controlling SIMD alignment for types.
FloatExt
Extends floating-point primitives with extra functionality.
Scalar
A trait for elements of math types.
ScalarBackend
Controls the implementation of math functions.
SupportedLength
A marker trait to restrict const N: usize to 2, 3 and 4.

Type Aliases§

Affine2
A 2D affine transform which can represent translation, rotation, scaling and shear.
Affine3
A 3D affine transform which can represent translation, rotation, scaling and shear.
Affine2U
A 2D affine transform which can represent translation, rotation, scaling and shear.
Affine3U
A 3D affine transform which can represent translation, rotation, scaling and shear.
Mask2
A 2-element vector mask.
Mask3
A 3-element vector mask.
Mask4
A 4-element vector mask.
Mask2U
A 2-element vector mask.
Mask3U
A 3-element vector mask.
Mask4U
A 4-element vector mask.
Mat2
A 2x2 column-major matrix.
Mat3
A 3x3 column-major matrix.
Mat4
A 4x4 column-major matrix.
Mat2U
A 2x2 column-major matrix.
Mat3U
A 3x3 column-major matrix.
Mat4U
A 4x4 column-major matrix.
Quat
A quaternion representing an orientation.
QuatU
A quaternion representing an orientation.
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.