| commit | 18bdbf00dc7d41bf4549b0542ced9c11d813e9b9 | [log] [tgz] |
|---|---|---|
| author | Hyun Jae Moon <hyunjaemoon@google.com> | Fri Feb 02 19:52:30 2024 +0000 |
| committer | Gerrit Code Review <noreply-gerritcodereview@google.com> | Fri Feb 02 19:52:30 2024 +0000 |
| tree | f180a22cde2ef26fbc2b1c0d81d69f4bae8b34ac | |
| parent | d1e8231d94f24ff16fcb69e51e235c0da52c6b8c [diff] |
Revert^2 "Upgrade glam to 0.25.0" This reverts commit d1e8231d94f24ff16fcb69e51e235c0da52c6b8c. Reason for revert: Resolved with pica's pr for upgrading glam crate Change-Id: I312e695101bc6b3489765afc2c36e1fb72890052
A simple and fast 3D math library for games and graphics.
glam is in beta stage. Base functionality has been implemented and the look and feel of the API has solidified.
f32 typesVec2, Vec3, Vec3A and Vec4Mat2, Mat3, Mat3A and Mat4QuatAffine2 and Affine3Af64 typesDVec2, DVec3 and DVec4DMat2, DMat3 and DMat4DQuatDAffine2 and DAffine3i16 typesI16Vec2, I16Vec3 and I16Vec4u16 typesU16Vec2, U16Vec3 and U16Vec4i32 typesIVec2, IVec3 and IVec4u32 typesUVec2, UVec3 and UVec4i64 typesI64Vec2, I64Vec3 and I64Vec4u64 typesU64Vec2, U64Vec3 and U64Vec4bool typesBVec2, BVec3 and BVec4The 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.
SIMD is supported on x86, x86_64 and wasm32 targets.
SSE2 is enabled by default on x86_64 targets.SSE2 on x86 targets add -C target-feature=+sse2 to RUSTCFLAGS.simd128 on wasm32 targets add -C target-feature=+simd128 to RUSTFLAGS.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 supportno_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.25", 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.25", default-features = false }
approx - traits and macros for approximate float comparisonsbytemuck - for casting into slices of byteslibm - uses libm math functions instead of std, required to compile with no_stdmint - for interoperating with other 3D math librariesrand - implementations of Distribution trait for all glam types.serde - implementations of Serialize and Deserialize for all glam types. Note that serialization should work between builds of glam with and without SIMD enabledrkyv - implementations of Archive, Serialize and Deserialize for all glam types. Note that serialization is not interoperable with and without the scalar-math feature. It should work between all other builds of glam. Endian conversion is currently not supportedbytecheck - to perform archive validation when using the rkyv featurescalar-math - compiles with SIMD support disableddebug-glam-assert - adds assertions in debug builds which check the validity of parameters passed to glam to help catch runtime errorsglam-assert - adds validation assertions to all buildscuda - forces glam 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 and std support.The minimum supported version of Rust for glam is 1.58.1.
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.
Matrices are stored in column major format. Each column vector is stored in contiguous memory.
glam is co-ordinate system agnostic and intends to support both right-handed and left-handed conventions.
The design of this library is guided by a desire for simplicity and good performance.
mint, rand and serde)See ARCHITECTURE.md for details on glam's internals.
There were many inspirations for the interface and internals of glam from the Rust and C++ worlds. In particular:
Vec3A implementationglam is a play on the name of the popular C++ library GLMLicensed under either of
at your option.
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!
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.
glam contains code ported from the following C++ libraries:
See ATTRIBUTION.md for details.