glam
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
f32
types- vectors:
Vec2
,Vec3
,Vec3A
andVec4
- square matrices:
Mat2
,Mat3
,Mat3A
andMat4
- a quaternion type:
Quat
- affine transformation types:
Affine2
andAffine3A
- vectors:
f64
types- vectors:
DVec2
,DVec3
andDVec4
- square matrices:
DMat2
,DMat3
andDMat4
- a quaternion type:
DQuat
- affine transformation types:
DAffine2
andDAffine3
- vectors:
i32
types- vectors:
IVec2
,IVec3
andIVec4
- vectors:
u32
types- vectors:
UVec2
,UVec3
andUVec4
- vectors:
bool
types- vectors:
BVec2
,BVec3
andBVec4
- vectors:
SIMD
The Vec3A
, Vec4
, Quat
, Mat2
, Mat3A
, Mat4
, Affine2
and Affine3A
types use 128-bit wide SIMD vector types for storage on x86
, x86_64
and wasm32
architectures. As a result, these types are all 16 byte aligned and depending on the size of the type or the type's members, they may contain internal padding. This results in some wasted space in the cases of Vec3A
, Mat3A
, Affine2
and Affine3A
. However, the use of SIMD generally results in better performance than scalar math.
glam
outperforms similar Rust libraries for common operations as tested by the mathbench
project.
Enabling SIMD
SIMD is supported on x86
, x86_64
and wasm32
targets.
SSE2
is enabled by default onx86_64
targets.- To enable
SSE2
onx86
targets add-C target-feature=+sse2
toRUSTCFLAGS
. - To enable
simd128
onwasm32
targets add-C target-feature=+simd128
toRUSTFLAGS
.
Note that SIMD on wasm32
passes tests but has not been benchmarked, performance may or may not be better than scalar math.
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.20.2", 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.20.2", default-features = false }
Optional features
approx
- traits and macros for approximate float comparisonsbytemuck
- for casting into slices of byteslibm
- required to compile withno_std
mint
- for interoperating with other 3D math librariesnum-traits
- required to compileno_std
, will be included when enabling thelibm
featurerand
- implementations ofDistribution
trait for allglam
types.serde
- implementations ofSerialize
andDeserialize
for allglam
types. Note that serialization should work between builds ofglam
with and without SIMD enabledrkyv
- implementations ofArchive
,Serialize
andDeserialize
for allglam
types. Note that serialization is not interoperable with and without thescalar-math
feature. It should work between all other builds ofglam
. Endian conversion is currently not supportedbytecheck
- to perform archive validation when using therkyv
feature
Feature gates
scalar-math
- compiles with SIMD support disableddebug-glam-assert
- adds assertions in debug builds which check the validity of parameters passed toglam
to help catch runtime errorsglam-assert
- adds validation assertions to all buildscuda
- forcesglam
types to match expected cuda alignment
Minimum Supported Rust Version (MSRV)
The minimum supported version of Rust for glam
is 1.52.1
.
wasm32
SIMD intrinsics require Rust 1.54.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 generics and minimal traits in the public API for simplicity of usage
- All dependencies are optional (e.g.
mint
,rand
andserde
) - Follows the Rust API Guidelines where possible
- Aiming for 100% test coverage
- Common functionality is benchmarked using Criterion.rs
Architecture
See ARCHITECTURE.md for details on glam
's internals.
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
Vec3A
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
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
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 start a discussion on GitHub. See CONTRIBUTING.md for more information for contributors.
The Game Development in Rust Discord and Bevy Engine Discord servers are not official support channels but can be 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.