# 🧑🎤 glam
[![Build Status]][github-ci] [![Coverage Status]][coveralls.io]
[![Latest Version]][crates.io] [![docs]][docs.rs]
[![Minimum Supported Rust Version]][Rust 1.68.2]
A simple and fast 3D math library for games and graphics.
## Features
* `f32` types
* vectors: `Vec2`, `Vec3`, `Vec3A` and `Vec4`
* square matrices: `Mat2`, `Mat3`, `Mat3A` and `Mat4`
* a quaternion type: `Quat`
* affine transformation types: `Affine2`, `Affine3` and `Affine3A`
* camera view and projection constructors: `camera` module
* `f64` types
* vectors: `DVec2`, `DVec3` and `DVec4`
* square matrices: `DMat2`, `DMat3` and `DMat4`
* a quaternion type: `DQuat`
* affine transformation types: `DAffine2` and `DAffine3`
* camera view and projection constructors: `dcamera` module
* `i8` types
* vectors: `I8Vec2`, `I8Vec3` and `I8Vec4`
* `u8` types
* vectors: `U8Vec2`, `U8Vec3` and `U8Vec4`
* `i16` types
* vectors: `I16Vec2`, `I16Vec3` and `I16Vec4`
* `u16` types
* vectors: `U16Vec2`, `U16Vec3` and `U16Vec4`
* `i32` types
* vectors: `IVec2`, `IVec3` and `IVec4`
* `u32` types
* vectors: `UVec2`, `UVec3` and `UVec4`
* `i64` types
* vectors: `I64Vec2`, `I64Vec3` and `I64Vec4`
* `u64` types
* vectors: `U64Vec2`, `U64Vec3` and `U64Vec4`
* `isize` types
* vectors: `ISizeVec2`, `ISizeVec3` and `ISizeVec4`
* `usize` types
* vectors: `USizeVec2`, `USizeVec3` and `USizeVec4`
* `bool` types
* vectors: `BVec2`, `BVec3` and `BVec4`
All types are enabled by default. Only `f32` and `bool` types are built-in.
All other types are optional and can be disabled if not needed for faster
compile times.
### 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`/`wasm64` 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`][mathbench] project.
[mathbench]: https://github.com/bitshifter/mathbench-rs
### Enabling SIMD
SIMD is supported on `x86`, `x86_64`, `wasm32` and `wasm64` targets.
* `SSE2` is enabled by default on `x86_64` targets.
* To enable `SSE2` on `x86` targets add `-C target-feature=+sse2` to
`RUSTFLAGS`.
* `NEON` is enabled by default on `aarch64` targets.
* To enable `simd128` on `wasm32` or `wasm64` targets add `-C target-feature=+simd128` to
`RUSTFLAGS`.
* 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`/`wasm64` passes tests but has not been benchmarked,
performance may or may not be better than scalar math.
[portable simd]: https://doc.rust-lang.org/core/simd/index.html
### `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:
```toml
[dependencies]
glam = { default-features = false, features = ["libm"] }
```
To support both `std` and `no_std` builds in project, you can use the following
in your `Cargo.toml`:
```toml
[features]
default = ["std"]
std = ["glam/std"]
libm = ["glam/libm"]
[dependencies]
glam = { default-features = false }
```
Alternatively, you can use the `nostd-libm` feature. This will always include a
`libm` dependency, but allows the user to still override it with `std` if they
prefer. This will allow your crate to compile with default features disabled,
instead of forcing the user to enable either `std` or `libm`.
```toml
[features]
default = ["std"]
std = ["glam/std"]
libm = ["glam/libm"]
[dependencies]
glam = { default-features = false, features = ["nostd-libm"] }
```
### Feature gates
* `std` - the default feature, has no dependencies.
* `all-types` - a default feature, enables `float-types`, `integer-types`
and `size-types`
* `float-types` - enables `f64` types
* `integer-types` - enables `i8`, `i16`, `i32`, `i64`, `u8`, `u16`, `u32`
and `u64` types
* `size-types` - enables `isize` and `usize` types
* `f64`, `i8`, `i16`, `i32`, `i64`, `isize`, `u8`, `u16`, `u32`, `u64`, `usize`
- enables glam types for the given intrinsic type
* `nostd-libm` - uses `libm` math functions if `std` is not available
* `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
* `cuda` - forces `glam` types to match expected [cuda alignment]
* `fast-math` - **Deprecated.** This feature no longer has any effect and will
be removed in a future release.
* `core-simd` - enables SIMD support via the [portable simd] module. This is an
unstable feature which requires a nightly Rust toolchain and `std` support.
[cuda alignment]: https://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#built-in-vector-types
### Optional dependencies
Pre-1.0 dependencies that appear in `glam`'s public API use versioned feature names
(e.g. `rand-010`), so a new version can be added without a breaking change.
* [`approx`] - **Deprecated.** Alias for the `approx-05` feature, will be removed
in the next major release.
* [`approx-05`] - `approx` 0.5 traits and macros for approximate float comparisons.
* [`arbitrary`] - `arbitrary` trait implementations for `glam` types.
* [`bytemuck`] - for casting into slices of bytes
* [`encase`] - **Deprecated.** Alias for the `encase-012` feature, will be removed
in the next major release.
* [`encase-012`] - `encase` 0.12 trait implementations for `glam` types.
* [`encase-013`] - `encase` 0.13 trait implementations for `glam` types.
* [`float_eq`] - traits and macros for comparing float types using various tolerances.
* [`libm`] - uses `libm` math functions instead of `std`
* [`mint`] - **Deprecated.** Alias for the `mint-05` feature, will be removed in
the next major release.
* [`mint-05`] - `mint` 0.5 for interoperating with other 3D math libraries.
* [`rand`] - **Deprecated.** Alias for the `rand-010` feature, will be removed in
the next major release.
* [`rand-010`] - `rand` 0.10 `Distribution` implementations for all `glam` types.
* [`rkyv`] - **Deprecated.** The current implementation is unsound and will be
removed in the next major release. Use `rkyv-08` instead.
* [`rkyv-08`] - `rkyv` 0.8 `Archive`, `Serialize` and `Deserialize` implementations
for all `glam` types, archiving to `glam::rkyv_08` types instead of the native type.
* [`bytecheck`] - enables `rkyv`'s archive validation; only has an effect when an
`rkyv` feature is enabled
* [`serde`] - implementations of `Serialize` and `Deserialize` for all `glam`
types. Note that serialization should work between builds of `glam` with and
without SIMD enabled
* [`speedy`] - **Deprecated.** Alias for the `speedy-08` feature, will be removed
in the next major release.
* [`speedy-08`] - `speedy` 0.8 implementations of `Readable` and `Writable` for all
`glam` types.
* [`zerocopy`] - **Deprecated.** Alias for the `zerocopy-08` feature, will be removed
in the next major release.
* [`zerocopy-08`] - `zerocopy` 0.8 implementations of zerocopy traits for safe
transmutes.
[`approx`]: https://docs.rs/approx
[`approx-05`]: https://docs.rs/approx/0.5
[`arbitrary`]: https://docs.rs/arbitrary
[`bytecheck`]: https://github.com/rkyv/bytecheck
[`bytemuck`]: https://docs.rs/bytemuck
[`encase`]: https://github.com/teoxoy/encase
[`encase-012`]: https://docs.rs/encase/0.12
[`encase-013`]: https://docs.rs/encase/0.13
[`float_eq`]: https://docs.rs/float_eq
[`libm`]: https://github.com/rust-lang/libm
[`mint`]: https://github.com/kvark/mint
[`mint-05`]: https://docs.rs/mint/0.5
[`rand`]: https://github.com/rust-random/rand
[`rand-010`]: https://docs.rs/rand/0.10
[`rkyv`]: https://github.com/rkyv/rkyv
[`rkyv-08`]: https://docs.rs/rkyv/0.8
[`serde`]: https://serde.rs
[`speedy`]: https://docs.rs/speedy
[`speedy-08`]: https://docs.rs/speedy/0.8
[`zerocopy`]: https://github.com/google/zerocopy
[`zerocopy-08`]: https://docs.rs/zerocopy/0.8
### Minimum Supported Rust Version (MSRV)
The minimum supported version of Rust for `glam` is `1.68.2`.
Raising the MSRV is treated as a non-breaking change, following Cargo's
[semver guidance].
`glam` itself and all of its features are expected to build with the MSRV
unless otherwise documented. Optional dependencies are exempt, per Cargo's
[support expectations]: they are not required to build with `glam`'s MSRV, so a
feature that enables one may require a newer toolchain than `glam` itself.
[semver guidance]: https://doc.rust-lang.org/cargo/reference/semver.html#env-new-rust
[support expectations]: https://doc.rust-lang.org/cargo/reference/rust-version.html#support-expectations
## 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.
### Camera
`glam` provides a `camera` module with view matrix (`look_at`, `look_to`)
and projection matrix (`perspective`, `orthographic`, `frustum`) constructors.
Pick the `rh` or `lh` sub-module based on your world space handedness,
then the API-specific constructor for your target graphics API convention
(OpenGL, DirectX, Vulkan, or WebGPU).
## 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` and `serde`)
* Follows the [Rust API Guidelines] where possible
* Aiming for 100% test [coverage]
* Common functionality is benchmarked using [Criterion.rs] and [Gungraun]
[Rust API Guidelines]: https://rust-lang-nursery.github.io/api-guidelines/
[coverage]: coveralls.io
[Criterion.rs]: https://criterion-rs.github.io/book/index.html
[Gungraun]: https://gungraun.github.io/gungraun/
## Architecture
See [ARCHITECTURE.md] for details on `glam`'s internals.
[ARCHITECTURE.md]: ARCHITECTURE.md
## 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]
[How to write a maths library in 2016]: http://www.codersnotes.com/notes/maths-lib-2016/
[Realtime Math]: https://github.com/nfrechette/rtm
[DirectXMath]: https://docs.microsoft.com/en-us/windows/desktop/dxmath/directxmath-portal
[GLM]: https://glm.g-truc.net
## License
Licensed under either of
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)
or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](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]!
[Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html
[start a discussion]: https://github.com/bitshifter/glam-rs/discussions
[CONTRIBUTING.md]: CONTRIBUTING.md
[codegen README]: tools/codegen/README.md
[contributors]: https://github.com/bitshifter/glam-rs/graphs/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`.
[Game Development in Rust Discord]: https://discord.gg/yNtPTb2
[Bevy Engine Discord]: https://discord.gg/gMUk5Ph
## 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.
[ATTRIBUTION.md]: ATTRIBUTION.md
[Build Status]: https://github.com/bitshifter/glam-rs/actions/workflows/ci.yml/badge.svg
[github-ci]: https://github.com/bitshifter/glam-rs/actions/workflows/ci.yml
[Coverage Status]: https://coveralls.io/repos/github/bitshifter/glam-rs/badge.svg?branch=main
[coveralls.io]: https://coveralls.io/github/bitshifter/glam-rs?branch=main
[Latest Version]: https://img.shields.io/crates/v/glam.svg
[crates.io]: https://crates.io/crates/glam/
[docs]: https://docs.rs/glam/badge.svg
[docs.rs]: https://docs.rs/glam/
[Minimum Supported Rust Version]: https://img.shields.io/badge/Rust-1.68.2-blue?color=fc8d62&logo=rust
[Rust 1.68.2]: https://github.com/rust-lang/rust/blob/master/RELEASES.md#version-1682-2023-03-28