Lib.rs

› 游戏开发
#vector #matrix-vector #simd-vector #matrix #quaternions #game-engine #gamedev

无需std revier-glam

游戏引擎Revier的库glam-rs的修改版

由GDev268拥有。

3个版本 (稳定版)

1.1.0 2023年10月21日
1.0.0 2023年10月20日
0.24.2 2023年10月20日

#286 in 游戏开发

MIT/Apache

2MB
63K SLoC

revier-glam

Build Status Coverage Status Latest Version docs Minimum Supported Rust Version

revier-glam 是著名的3D库 glam 的修改版，为Rust游戏引擎 Revier 提供额外功能

功能

  • f32 类型
    • 向量：Vec2，Vec3，Vec3A 和 Vec4
    • 方阵：Mat2，Mat3，Mat3A 和 Mat4
    • 四元数类型：Quat
    • 仿射变换类型：Affine2 和 Affine3A
  • f64 类型
    • 向量：DVec2，DVec3 和 DVec4
    • 方阵：DMat2，DMat3 和 DMat4
    • 四元数类型：DQuat
    • 仿射变换类型：DAffine2 和 DAffine3
  • i32 类型
    • 向量：IVec2，IVec3 和 IVec4
  • u32 类型
    • 向量：UVec2，UVec3 和 UVec4
  • i64 类型
    • 向量：I64Vec2，I64Vec3 和 I64Vec4
  • u64 类型
    • 向量：U64Vec2，U64Vec3 和 U64Vec4
  • bool 类型
    • 向量：BVec2，BVec3 和 BVec4

SIMD

类型 Vec3A、Vec4、Quat、Mat2、Mat3A、Mat4、Affine2 和 Affine3A 在 x86、x86_64 和 wasm32 架构上使用 128 位宽的 SIMD 向量类型进行存储。因此，这些类型都是 16 字节对齐的，并且根据类型或类型成员的大小，它们可能包含内部填充。这导致在 Vec3A、Mat3A、Affine2 和 Affine3A 的情况下存在一些浪费的空间。然而，SIMD 的使用通常比标量数学的性能更好。

根据 mathbench 项目的测试，glam 在常见操作上优于类似的 Rust 库。

启用 SIMD

SIMD 支持 x86、x86_64 和 wasm32 目标。

  • SSE2 在 x86_64 目标上默认启用。
  • 要在 x86 目标上启用 SSE2，请向 RUSTCFLAGS 添加 -C target-feature=+sse2。
  • 要在 wasm32 目标上启用 simd128，请向 RUSTFLAGS 添加 -C target-feature=+simd128。
  • 可以使用 core-simd 功能启用实验性的 可移植 SIMD 支持。这需要夜间编译器，因为它在 Rust 中仍然不稳定。

请注意，wasm32 上的 SIMD 已经通过了测试，但尚未进行基准测试，性能可能或可能不会比标量数学更好。

no_std 支持

可以通过使用 --no-default-features 来禁用 std 支持，并使用 --features libm 为仅定义在 std 中的数学函数编译来启用 no_std 支持。例如

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

要在一个项目中同时支持 std 和 no_std 构建，您可以在您的 Cargo.toml 中使用以下内容

[features]
default = ["std"]

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

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

可选功能

  • approx - 用于近似浮点比较的特性和宏
  • bytemuck - 用于将类型转换为字节数组
  • libm - 使用 libm 数学函数而不是 std，需要与 no_std 一起编译
  • mint - 用于与其他 3D 数学库交互
  • rand - 为所有 glam 类型实现 Distribution 特性。
  • serde - 为所有 glam 类型实现 Serialize 和 Deserialize。请注意，序列化应在启用和禁用 SIMD 的 glam 构建之间工作
  • rkyv - 为所有 glam 类型实现了 Archive、Serialize 和 Deserialize。请注意，序列化与不带或带 scalar-math 功能的互操作性。它应与其他所有 glam 构建兼容。目前不支持端序转换
  • bytecheck - 在使用 rkyv 功能时进行存档验证

功能门

  • scalar-math - 禁用 SIMD 支持进行编译
  • debug-glam-assert - 在调试构建中添加断言，检查传递给 glam 的参数的有效性，以帮助捕获运行时错误
  • glam-assert - 向所有构建添加验证断言
  • cuda - 强制 glam 类型与预期的 cuda 对齐 匹配
  • fast-math - 默认情况下，glam 尝试在所有平台上提供位对位的相同结果。使用此功能将启用特定于平台的优化，这些优化可能与其他平台不匹配。中间库不应使用此功能，并将决策推迟到最终二进制构建。
  • core-simd - 通过 可移植 SIMD 模块启用 SIMD 支持。这是一个不稳定的功能，需要 nightly Rust 工具链和 std 支持。

最低支持的 Rust 版本 (MSRV)

glam 最低支持的 Rust 版本是 1.58.1。

约定

列向量

glam 将向量解释为列矩阵（也称为“列向量”），这意味着当将矩阵与向量转换时，矩阵位于左侧，例如 v' = Mv。DirectX 使用行向量，OpenGL 使用列向量。两者都有优点和缺点。

列主序

矩阵以列主序格式存储。每个列向量存储在连续的内存中。

坐标系

glam 不受坐标系限制，旨在支持右手和左手惯例。

设计理念

该库的设计受到简单性和良好性能的指导。

  • 为简化使用，公共 API 中没有泛型和最小 traits
  • 所有依赖项都是可选的（例如 mint、rand 和 serde）
  • 尽可能遵循 Rust API 指南
  • 目标达到 100% 测试 覆盖率
  • 使用 Criterion.rs 对常用功能进行基准测试

架构

有关 glam 内部结构的详细信息，请参阅 ARCHITECTURE.md

灵感

glam 的接口和内部结构的灵感来自 Rust 和 C++ 世界。特别是

  • 如何在 2016 年编写数学库 启发了最初的 Vec3A 实现
  • 实时数学 - 仅包含头文件的 C++11，具有 SSE 和 NEON SIMD 内置支持
  • DirectXMath - 仅包含头文件的 SIMD C++ 线性代数库，用于游戏和图形应用程序
  • glam 是对流行的 C++ 库 GLM 命名的恶搞。

许可证

根据以下任意一项许可

由您选择。

贡献

对项目的任何形式（问题、拉取请求等）的贡献必须遵守 Rust 的 行为准则。

除非您明确表示，否则根据 Apache-2.0 许可证定义，您有意提交以包含在作品中的任何贡献将如上双许可，不附加任何额外条款或条件。

如果您有兴趣贡献或有所请求或建议，请在 GitHub 上 发起讨论。有关贡献者的更多信息，请参阅 CONTRIBUTING.md。

glam 中的大部分代码都是生成的，有关详细信息，请参阅 codegen README。

感谢所有 glam 贡献者！

支持

Rust 游戏开发 Discord 服务器 和 Bevy 引擎 Discord 服务器 不是官方支持渠道，但可以是很好的寻求 glam 帮助的地方。

归属

glam 包含从以下 C++ 库移植的代码

  • DirectXMath - MIT 许可证 - 版权所有 (c) 2011-2020 微软公司
  • 实时数学 - MIT 许可证 - 版权所有 (c) 2018 Nicholas Frechette
  • GLM - MIT 许可证 - 版权所有 (c) 2005 - G-Truc Creation

有关详细信息，请参阅 ATTRIBUTION.md。

依赖项

~0–730KB
~16K SLoC