Switching vector crates

[zesterer]

While using Bevy, I've been a little disappointed with the choice of glam for vector types. While it fulfills minimal criteria, it lacks a number of useful features that I've personally found are very useful in gamedev.

Missing features (inexhaustive)

• Very few element-wise operations (no map, fold, reduce, etc.)
• No generic vectors (VecN<bool> and VecN<VecM<T>> crop up a lot in a number of algorithms and not being able to use them without abandoning the vector types entirely is quite the sharp edge)
• No utility vector types like Rgb/Rgba
• No bounding box types like Aabr/Aabb
• No line segment types like LineSegmentN
• No curve types (quadratic and cubic bezier curves are very often relevant in the gamedev world and having a common interop in Bevy for dependencies to use when talking about things like camera/entity paths is important)
• No SIMD support (at least, support for SIMD appears to only incidentally exist, hidden behind the spirv feature flag)
• No RotorN (rotors are often more ergonomic/easier to reason about than quaternions, and generalise to N-dimensional space)

Proposed alternatives

The vek crate solves most of the problems I listed above, and the author is very receptive toward changes. As a little anecdotal testimony: we use vek in Veloren and we've always found it to be pleasantly ergonomic, even for particularly complex cases.

Beyond vek, there are a myriad of other crates. Of particular note are nalgebra and ultraviolet, although both have their respective problems:

• nalgebra's documentation is very difficult to navigating owing to its intense focus on type composition and this, in addition to its lack of useful utility methods, makes it a difficult crate to use in practical gamedev scenarios
• ultraviolet's API is inspired by vek, so exhibits some of its API features (map, for example) but its intense focus on performance and SIMD means that it drops a number of important features on the floor, such as generic types

Possible solution

I don't believe that there exists a single crate that solves all of the aforementioned issues, but I feel that, with a little work, vek is by far the closest towards covering these cases.

RFC

I've opened this issue to initiate discussion, but I realise that this is potentially a large enough change that it would require an RFC in the future.

[alice-i-cecile]

Thanks for posting this; I think it's worth discussing! Initial thoughts:

• Very few element-wise operations (no map, fold, reduce, etc.)

Agreed, this would be nice to have. We could add these to glam.

No generic vectors (VecN and VecN<VecM> crop up a lot in a number of algorithms and not being able to use them without abandoning the vector types entirely is quite the sharp edge)

By far the most serious limitation (but comes with an ergonomic and potentially compile-time cost). I would very much like this for managing coordinate systems, swapping between fixed point / f64 coordinates (see #1680), possibly maintaining distinct NetworkedTransform components...

No utility vector types like Rgb/Rgba

I think this is mostly an anti-feature: we should be using a proper color crate for this, see #1797.

No bounding box types like Aabr/Aabb
No line segment types like LineSegmentN
No curve types (quadratic and cubic bezier curves are very often relevant in the gamedev world and having a common > interop in Bevy for dependencies to use when talking about things like camera/entity paths is important)

For bounding boxes, line segments and so on see: bevyengine/rfcs#12

I'm not sure I love the idea of outsourcing our geometric primitive types (there's a lot to profile and get right), but I could be convinced.

No SIMD support (at least, support for SIMD appears to only incidentally exist, hidden behind the spirv feature flag)

This is important, and could be improved upon.

No RotorN (rotors are often more ergonomic/easier to reason about than quaternions, and generalise to N-dimensional space)

This is also useful, and could be added.

@bitshifter is quite active; I suspect we could contribute upstream to get most of these features: generic vectors (and some dereferencing pain) are the main arguments to consider migrating IMO.

The other small consideration is that if we migrated to nalgebra, we'd play nicer with rapier, the dominant physics crate.

[cart]

Left some assorted thoughts that relate to these points in @bitshifter's thread below. As a quick point of clarity, glam already has simd support and is quite competitive in performance.

[parasyte]

No SIMD support (at least, support for SIMD appears to only incidentally exist, hidden behind the spirv feature flag)

While glam is not my first choice for linear algebra, it does support SIMD for targets with target_feature = "sse2" and target_feature = "simd128": https://github.com/bitshifter/glam-rs/blob/029a036ee26329370ce45d722b7a342e2f0225b7/src/core/mod.rs

SIMD support is also described in the docs: https://docs.rs/glam/latest/glam/#simd

No RotorN (rotors are often more ergonomic/easier to reason about than quaternions, and generalise to N-dimensional space)

This is worth putting at the top of your list of grievances. Obligatory reference: Let's remove Quaternions from every 3D Engine

[bitshifter]

Hi, I'm the author of glam. I feel I should address some of these points on missing features:

* No SIMD support (at least, support for SIMD appears to only incidentally exist, hidden behind the `spirv` feature flag)

As already pointed out above by @parasyte this is not the case. glam uses SIMD differently to alternatives listed here but it most certainly uses SIMD, the most similar crate to glam in this regard is pathfinder_geometry. glam uses handwritten sse2 on x86/x86_64 and simd128 on wasm32 which are all available in stable Rust. Types that have been SIMD optimized include Vec4, Quat, Mat4, Mat3A, Vec3A, Mat2, Affine3A and Affine2. Other types did not benefit from SIMD in my benchmarking.

My understanding of vek is it uses repr(simd) which allows raw access to LLVM internals, however this is only available in nightly and it's my understanding that there is no path to stabilization for this feature (see https://rust-lang.github.io/rfcs/2325-stable-simd.html#stabilizing-simd-implementation-details).

ultraviolet and nalgebra provide wide version of their types which can use sse2, avx2 and so on, which can operate on multiple vectors at a time. This is the best way to utilize SIMD but requires structuring code differently to take advantage of it which is not always straight forward. This approach is described in more detail here https://www.rustsim.org/blog/2020/03/23/simd-aosoa-in-nalgebra/#what-is-aosoa-with-explicit-simd.

This is a different approach to glam which focuses on scalar math. ultraviolet and nalgebra do not have SIMD optimized scalar types as far as I am aware.

I also maintain mathbench which attempts to benchmark various Rust math crates and compares both scalar and wide variants. If you are interested recent bench results can be found in the here. glam tends to perform best out of the scalar options.

* Very few element-wise operations (no `map`, `fold`, `reduce`, etc.)

These could of course be added. No one has asked for them so far. I do not think that per element operations would perform well for SIMD types compared to more explicit methods but I can see how they could be convenient where an explicit method does not exist.

* No generic vectors (`VecN<bool>` and `VecN<VecM<T>>` crop up a lot in a number of algorithms and not being able to use them without abandoning the vector types entirely is quite the sharp edge)

Generic types is definitely not a goal of glam and would not work with the way glam uses SIMD. While it might be possible to add some generic type to glam I wouldn't see them ever replacing glam's existing SIMD optimized types so I am not sure it would be a worthwhile exercise.

* No utility vector types like `Rgb`/`Rgba`
* No bounding box types like `Aabr`/`Aabb`
* No line segment types like `LineSegmentN`
* No curve types (quadratic and cubic bezier curves are very often relevant in the gamedev world and having a common interop in Bevy for dependencies to use when talking about things like camera/entity paths is important)

glam is a fairly minimal library. Some of these things might make some sense to add longer to glam or a sub crate of glam. Some of these types can be found in other crates like Embark's macaw crate. As @alice-i-cecile pointed out Bevy is also looking at adding their own types where they need them. Potentially common features from macaw or other crates could migrate into glam if it made sense to do so. From my point of view it would be good if these were matured in other crates and migrated to glam if it was desirable and the implementation was general purpose enough.

* No `RotorN` (rotors are often more ergonomic/easier to reason about than quaternions, and generalise to N-dimensional space)

Probably not something I will add in the near term. Quaternions are still very commonly used. API wise rotors look quite similar to quaternions to me except there are additional concepts to learn about like bivectors. I appreciate the elegance of geometric algebra but I think I will wait and see if there is wider adoption in the industry before moving on that.

[cart]

I agree with the points made here. Some additional assorted thoughts:

• I don't see generic vectors as a desirable baseline vector type because they disallow some of the internal size-specific simd vector ops that crates like glam do for us. I also don't want to see Vec3<f32> everywhere. I much prefer the simplicity and terseness of Vec3, DVec3, IVec3, etc, alongside the comfort that they will be precompiled in the glam crate and shared across all consuming crates. We've discussed adding our own generic vector type (or contributing one to glam) to cover scenarios not covered by "core vector types", but I'm very happy with glam's approach generally.
• I agree that missing convenience functions like map don't justify an overhaul of our math types. We can always add them if we need them.
• I've read/watched Rotor vs Quats material in the past and while I agree that rotors are less magical internally (and more general), in actual real-world usage their apis have been identical in my experience. Show me a compelling real-world gamedev use case that benefits from Rotors over Quats and ill take the switch seriously. Until then Quats have name recognition that Rotors do not, the public apis are effectively the same, glam already has great Quat support, and 99.9999% of users will never try to "fully grok" the Quat implementation. Those that do can go down the Rotor vs Quat rabbit hole and enjoy the math.
• I'm glad that glam doesn't try to do everything. The higher level types like colors / bounding boxes / curves deserve opinionated and consistent apis that play well with the rest of the engine. I like that we own our own Color type and have control over the UX.

[Dampfwalze]

I also don't want to see Vec3<f32> everywhere

While I don't think, it is a suitable replacement for glam, I like the way, how glm-rs does this. It uses Vector2<T>, Vector3<T>, etc. as the generic basetype and defines aliases for Vec3, DVec3, IVec3 etc.

they disallow some of the internal size-specific simd vector ops

I think this boils down to the ability to write specializations for specific generic type parameters. This is hard to do, when not impossible currently in Rust, but might be possible in the future using rust-lang/rust#31844

alongside the comfort that they will be precompiled in the glam crate and shared across all consuming crates

In theory, this could be done for generic types too, when it is possible for the compiler to know in advance, which generic type parameters will most likely be used. For example, a concrete type alias can be used as a hint for the compiler. Though I doubt something like this is actually implemented, one could make a proposal for that!

I think it is important to investigate further on generic math primitives, since they are an important feature to have,

• to mitigate code duplication, by constructing meaningful trait bounds around all variants one might use,
• users are not limited to a set of predefined scalar types to use! They could implement their own, like BigInteger for example, without reimplementing everything! Isn't that the main goal of generics?
• etc.

[ua-kxie]

I'm here because I was missing some API from the euclid crate (specifically this one), considered maybe adding some and then realized that there were IRect, URect, and Rect with duplicated code. I accept the performance arguments, but I think aliases work well enough to hide something like Vec3<f32>.

I really liked the coordinates tag used in euclid. e.g.

pub type ProjectionMatrix = Transform3D<f32, WorldSpace, ScreenSpace>;

which allows the compiler to check for you that you're applying the right transforms (ever forget to take the inverse of a matrix?).

[Swoorup]

You can use glamour, which provides this type-safety atop glam.

[marstaik]

My largest complaint is that the choice for glam causes some actual development issues and pain points in the long term.

If I were to pick a math library, it would most definitely be nalgebra.

• It seems to be the most stable and up-to-date (opinion?)

• Really good for when game logic/math surpasses the easy-mode

  • This depends on the game/developer

• It's used by bevy_rapier

  • Note that bevy_rapier is limited to only f32 even though it supports f64 because of bevy being locked to f32

• It has tons of interop (ndarray, glam, etc)

• It has a glam/easy mode: https://docs.rs/nalgebra-glm/latest/nalgebra_glm/

• Bevy doesn't support f64 world math currently

I also don't want to see Vec3 everywhere
@cart I actually would hope to see Vec3 in the math / Transform, so we can control f32 or f64 at configuration.

It would be ideal if Transforms -> Global Transform -> MVP Matrix was done in f64 and truncated to f32 before being sent to the GPU to keep world precision at the maximum for certain games that require it.

The rendering engine and certain types (such as Mesh) could of course remain in f32, but there is no reason to force the world to be f32.

There is zero performance loss from going to f64 for desktop machines in this day and age, but keeping f32 for mobile devices would be good.

Also, there may be incentive to support double-precision rendering at some point, but that seems like it would be far, far off, and probably out of scope.

The higher level types like colors / bounding boxes / curves deserve opinionated and consistent apis that play well with the rest of the engine.

I think this is a bit orthogonal, and moving to nalgebra also wouldn't affect bevy's own types either.

[Dampfwalze]

Also, there may be incentive to support double-precision rendering at some point, but that seems like it would be far, far off, and probably out of scope.

For most Applikations it would be enough to do the transformation into view space with f64 precision and truncating to f32 for the rest of the pipeline. In view space the camera is at the origin. This is where the "floating" in floating point shines.

[lambdadeltakay]

I would also love to see nalgebra and I just end up using it as much as possible within my own bevy project anyway because of glam's strangeness/lack of features

[lambdadeltakay]

I'm gonna examine the effort required for porting

[lambdadeltakay]

Honestly does not look very hard just exceedingly tedious. The main thing is that for bevy_math we probably would want to have a cargo feature that chooses a default float type.