Rename Direction2d/Direction3d to Dir2/Dir3 and add Dir3A

[Jondolf]

Objective

Currently, Bevy has the Direction2d and Direction3d types, which are used for Ray2d and Ray3d, several primitive shapes, some gizmo and transform APIs, and more.

Direction3d stores a Vec3. However, the SIMD version Vec3A can be meaningfully faster for many tasks like ray casting, so we want types like Ray2d and Ray3d to use it. We could just change Direction3d to use a Vec3A, but the unaligned version is also valuable for determinism and APIs that use Vec3. As a result, we need both Vec3 and Vec3A versions of Direction3d.

The name Direction3dA doesn't feel very natural, and SimdDirection3d is a bit long. Thus, I propose renaming the direction types to shortened versions that follow Glam's naming conventions: Dir2, Dir3, and Dir3A. This was also proposed in the original primitive PR, but back then we were slightly in favor of the longer, more explicit names.

I would argue that Dir2 and Dir3 are also a bit nicer to write than Direction2d and Direction3d, and in some cases they can produce nicer formatting. The name length also matches Vec2 and Vec3, and the API is intended to be very similar (but with normalization guarantees). In my opinion, the direction types are to be treated like core math types, and it makes sense to match Glam's naming convention.

Some examples of what it'd look like in code:

// Before
let ray_cast = RayCast2d::new(Vec2::ZERO, Direction2d::X, 5.0);

// After
let ray_cast = RayCast2d::new(Vec2::ZERO, Dir2::X, 5.0);

// Before (an example using Bevy XPBD)
let hit = spatial_query.cast_ray(
    Vec3::ZERO,
    Direction3d::X,
    f32::MAX,
    true,
    SpatialQueryFilter::default(),
);

// After
let hit = spatial_query.cast_ray(
    Vec3::ZERO,
    Dir3::X,
    f32::MAX,
    true,
    SpatialQueryFilter::default(),
);

// Before
self.circle(
    Vec3::new(0.0, -2.0, 0.0),
    Direction3d::Y,
    5.0,
    Color::TURQUOISE,
);

// After (formatting is collapsed in this case)
self.circle(Vec3::new(0.0, -2.0, 0.0), Dir3::Y, 5.0, Color::TURQUOISE);

The diff of this PR has more examples.

Personally, I find Dir2 and Dir3 to look better aesthetically in addition to being more consistent with Glam's naming conventions. They are often next to Vec2 or Vec3, and having the type names be the same length looks nice.

Solution

Rename Direction2d to Dir2 and Direction3d to Dir3, and add Dir3A.

There's now quite a bit of direction code (including tests and the InvalidDirectionError), and we will add more implementations and helpers in the future. The direction types also feel a bit out-of-place in the primitives module in my opinion.

I have discussed this with others on the Discord, and have decided to move the direction types out of primitives into a dedicated direction module. This is something we were intending to do much earlier, but never did.

---

Changelog

• Renamed Direction2d to Dir2 and Direction3d to Dir3
• Added Dir3A
• Moved direction types out of primitives and into a new direction module

Migration Guide

The Direction2d and Direction3d types have been renamed to Dir2 and Dir3.

[alice-i-cecile]

Can you add deprecated type aliases for the old names to ease migration?

[Jondolf]

I already did, they're in the primitive modules where the old Direction2d and Direction3d used to be.

[JMS55]

I don't like the shortened names personally.

[alice-i-cecile]

Can we split out the rename from the code org + new aligned types? I'd like to avoid getting derailed by bikeshedding.

[Jondolf]

What should the new aligned type be called though? That was one of the motivating factors behind the rename. Direction3dA feels a bit weird, SimdDirection3d isn't ideal imo, and I'm not sure what other viable options there would be

[alice-i-cecile]

Let's do Direction3dA for now: it's at least consistent.

[alice-i-cecile]

Closing in favor of #12018: we can do the rename in another PR after :)