Skip to content
A simple and fast linear algebra library for games and graphics
Rust
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Add cargo-deny GitHub CI action Dec 15, 2019
benches Renamed some methods and fixed errors for transform-types. Dec 12, 2019
src Added link to libs that have been the source of some internals Jan 19, 2020
tests Changed tests for `is_nan` to use `assert!`. Dec 29, 2019
.gitignore Do no panic on any zero scale, only on all zero (#31) Nov 7, 2019
.travis.yml Added Mat4::to_scale_rotation_translation (#37) Dec 17, 2019
CHANGELOG.md
CONTRIBUTING.md Added some contribution guidelines. Jul 18, 2019
Cargo.toml
LICENSE-APACHE Prepare for 0.8.5 release. Jan 2, 2020
LICENSE-MIT Made a start on extracting pathtrace-rs math. Mar 8, 2019
README.md Added link to libs that have been the source of some internals Jan 19, 2020
deny.toml Ignore duplicate dependencies inside criterion Jan 17, 2020

README.md

glam

Build Status Coverage Status Latest Version docs

A simple and fast 3D math library for games and graphics.

Development status

glam is in alpha stage. Minimal base functionality has been implemented and the look and feel of the API has solidified.

Features

  • Only single precision floating point (f32) arithmetic is supported
  • vectors: Vec2, Vec3, Vec4
  • square matrices: Mat2, Mat3, Mat4
  • a quaternion type: Quat

SIMD

The Vec3, Vec4 and Quat types use SSE2 on x86/x86_64 architectures. Mat2, Mat3 and Mat4 also use SSE2 for some functionality. Not everything has a SIMD implementation yet.

Note that this does result in some wasted space in the case of Vec3 and Mat3 as the SIMD vector type is 16 bytes large and 16 byte aligned.

glam outperforms similar Rust libraries such as cgmath, nalgebra-glm and others for common operations as tested by the mathbench project.

If you are more concerned with size than speed you can build glam with the feature scalar-math enabled to disable SIMD usage.

Due to the use of SIMD, vector elements may only be get and set via accessor methods, e.g. Vec3::x() and Vec3::set_x(). If getting or setting more than one element it is more efficient to convert from tuples or arrays:

let (x, y, z) = v.into();

Optional features

  • mint - for interoperating with other 3D math libraries
  • rand - implementations of Distribution trait for all glam types. This is primarily used for unit testing
  • serde - implementations of Serialize and Deserialize for all glam types. Note that serialization should work between builds of glam with and without SIMD enabled

Feature gates

  • scalar-math - compiles with SIMD support disabled
  • glam-assert - adds assertions which check the validity of parameters passed to glam to help catch runtime errors

Conventions

Column vectors

glam interprets vectors as column matrices (also known as "column vectors") meaning when transforming a vector with a matrix the matrix goes on the left, e.g. v' = Mv. DirectX uses row vectors, OpenGL uses column vectors. There are pros and cons to both.

Column-major order

Matrices are stored in column major format. Each column vector is stored in contiguous memory.

Co-ordinate system

glam is co-ordinate system agnostic and intends to support both right handed and left handed conventions.

Rotations follow the left-hand rule.

Design Philosophy

The design of this library is guided by a desire for simplicity and good performance.

  • Only single precision floating point (f32) arithmetic is supported
  • No traits or generics for simplicity of implementation and usage
  • All dependencies are optional (e.g. mint, rand and serde)
  • Follows the Rust API Guidelines where possible
  • Aiming for 100% test coverage
  • Common functionality is benchmarked using Criterion.rs

Future work

  • Writing documentation
  • Experiment with a using a 4x3 matrix as a 3D transform type that can be more efficient than Mat4 for certain operations like inverse and multiplies
  • no-std support

Inspirations

There were many inspirations for the interface and internals of glam from the Rust and C++ worlds. In particular:

  • How to write a maths library in 2016 inspired the initial Vec3 implementation
  • Realtime Math - header only C++11 with SSE and NEON SIMD intrinsic support
  • DirectXMath - header only SIMD C++ linear algebra library for use in games and graphics apps
  • glam is a play on the name of the popular C++ library glm

License

Licensed under either of

at your option.

Contribution

Contributions in any form (issues, pull requests, etc.) to this project must adhere to Rust's Code of Conduct.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Thank you to all of the glam contributors!

Support

If you are interested in contributing or have a request or suggestion create an issue on github.

You can’t perform that action at this time.