#gamedev #math #matrix #vector #quaternion

no-std glam

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

29 releases

new 0.11.0 Nov 25, 2020
0.10.0 Oct 31, 2020
0.9.2 Jul 9, 2020
0.8.6 Feb 18, 2020
0.7.1 Jul 8, 2019

#1 in Game dev

Download history 4145/week @ 2020-08-09 3804/week @ 2020-08-16 5300/week @ 2020-08-23 5158/week @ 2020-08-30 4615/week @ 2020-09-06 4256/week @ 2020-09-13 4765/week @ 2020-09-20 5407/week @ 2020-09-27 6058/week @ 2020-10-04 5762/week @ 2020-10-11 5507/week @ 2020-10-18 6005/week @ 2020-10-25 7604/week @ 2020-11-01 8030/week @ 2020-11-08 8459/week @ 2020-11-15 10343/week @ 2020-11-22

26,321 downloads per month
Used in 76 crates (20 directly)

MIT/Apache

470KB
15K SLoC

glam

Build Status Coverage Status Latest Version docs

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

Development status

glam is in beta stage. 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, Vec3A Vec4
  • square matrices: Mat2, Mat3, Mat4
  • a quaternion type: Quat

SIMD

The Vec3A, 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 Vec3A as the SIMD vector type is 16 bytes large and 16 byte aligned.

glam outperforms similar Rust libraries for common operations as tested by the mathbench project.

no_std support

no_std support can be enabled by compiling with --no-default-features to disable std support and --features libm for math functions that are only defined in std. For example:

[dependencies]
glam = { version = "0.10.1", default-features = false, features = ["libm"] }

To support both std and no_std builds in project, you can use the following in your Cargo.toml:

[features]
default = ["std"]

std = ["glam/std"]
libm = ["glam/libm"]

[dependencies]
glam = { version = "0.10.1", default-features = false }

Optional features

  • bytemuck - for casting into slices of bytes
  • libm - required to compile with no_std
  • mint - for interoperating with other 3D math libraries
  • num-traits - required to compile no_std, will be included when enabling the libm feature
  • 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
  • debug-glam-assert - adds assertions in debug builds which check the validity of parameters passed to glam to help catch runtime errors
  • glam-assert - adds validation assertions to all builds

Minimum Supported Version of Rust (MSVR)

The minimum supported version of Rust for glam is 1.36.0.

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.

Design Philosophy

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

  • No traits or generics for simplicity of implementation and usage
  • Only single precision floating point f32 arithmetic is supported for now
  • 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

  • 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
  • wasm support

Inspirations

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

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.

The Game Development in Rust Discord and Bevy Engine Discord servers can are also good places to ask for help with glam.

Attribution

glam contains code ported from the following C++ libraries:

  • DirectXMath - MIT License - Copyright (c) 2011-2020 Microsoft Corp
  • Realtime Math - MIT License - Copyright (c) 2018 Nicholas Frechette
  • GLM - MIT License - Copyright (c) 2005 - G-Truc Creation

See ATTRIBUTION.md for details.

Dependencies

~0–410KB