Awesome
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:
i8
types- vectors:
I8Vec2
,I8Vec3
andI8Vec4
- vectors:
u8
types- vectors:
U16Vec2
,U16Vec3
andU16Vec4
- vectors:
i16
types- vectors:
I16Vec2
,I16Vec3
andI16Vec4
- vectors:
u16
types- vectors:
U16Vec2
,U16Vec3
andU16Vec4
- vectors:
i32
types- vectors:
IVec2
,IVec3
andIVec4
- vectors:
u32
types- vectors:
UVec2
,UVec3
andUVec4
- vectors:
i64
types- vectors:
I64Vec2
,I64Vec3
andI64Vec4
- vectors:
u64
types- vectors:
U64Vec2
,U64Vec3
andU64Vec4
- 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
. NEON
is enabled by default onaarch64
targets.- To enable
NEON
onaarch64
targets add-C target-feature=+neon
toRUSTFLAGS
. - To enable
simd128
onwasm32
targets add-C target-feature=+simd128
toRUSTFLAGS
. - Experimental portable simd support can be enabled with the
core-simd
feature. This requires the nightly compiler as it is still unstable in Rust.
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.29.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.29.2", default-features = false }
Optional features
approx
- traits and macros for approximate float comparisonsbytemuck
- for casting into slices of byteslibm
- useslibm
math functions instead ofstd
, required to compile withno_std
mint
- for interoperating with other 3D math librariesrand
- 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 alignmentfast-math
- By default, glam attempts to provide bit-for-bit identical results on all platforms. Using this feature will enable platform specific optimizations that may not be identical to other platforms. Intermediate libraries should not use this feature and defer the decision to the final binary build.core-simd
- enables SIMD support via the portable simd module. This is an unstable feature which requires a nightly Rust toolchain andstd
support.
Minimum Supported Rust Version (MSRV)
The minimum supported version of Rust for glam
is 1.68.2
.
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.
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.
Most code in glam
is generated, see the codegen README for details.
Thank you to all of the glam
contributors!
Support
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.