Add a Dir4 to resolve #17983 #19223

stevehello166 · 2025-05-15T23:28:39Z

Objective

Fixes #17983

Solution

Implemented a basic Dir4 struct with methods similar to Dir3 and Dir2.

Testing

Did you test these changes? If so, how?
Added unit tests that follow the same pattern of the other Dir structs.
Are there any parts that need more testing?
Since the other Dir structs use rotations to test renormalization and I have been following them as a pattern for the Dir4 struct I haven't implemented a test to cover renormalization of Dir4's.
How can other people (reviewers) test your changes? Is there anything specific they need to know?
Use Dir4 in the wild.
If relevant, what platforms did you test these changes on, and are there any important ones you can't test?
N/A (Tested on Linux/X11 but it shouldn't be a problem)

github-actions · 2025-05-15T23:28:53Z

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

Person-93 · 2025-05-16T04:21:38Z

crates/bevy_math/src/direction.rs

+        Self(value)
+    }
+
+    /// Create a direction from a finite, nonzero [`Vec3`], normalizing it and


Suggested change

/// Create a direction from a finite, nonzero [`Vec3`], normalizing it and

/// Create a direction from a finite, nonzero [`Vec4`], normalizing it and

IQuick143 · 2025-05-16T07:51:22Z

crates/bevy_math/src/direction.rs

+            .ok_or(InvalidDirectionError::from_length(length))
+    }
+
+    /// Create a direction from its `w`, `x`, `y`, and `z` components.


The order seems a bit peculiar.
Despite not being alphabetic, the typical ordering is xyzw (also AXES are ordered that way).
Also Vec4::W is (0,0,0,1).

yeah this needs to to be uniformly xyzw order, this is just the sort of thing that'd trap me for hours because I didn't notice the difference.

I fixed it.

crates/bevy_math/src/direction.rs

IQuick143 · 2025-05-16T07:54:39Z

crates/bevy_math/src/direction.rs

@@ -1090,4 +1279,26 @@ mod tests {
        );
        assert!(dir_b.is_normalized(), "Renormalisation did not work.");
    }
+
+    #[test]
+    fn dir4_creation() {


I would propose the following tests:

assert_eq!(Dir4::from_xyzw(1.0, 0.0, 0.0, 0.0), Ok(Dir4::X)); assert_eq!(Dir4::from_xyzw(0.0, 1.0, 0.0, 0.0), Ok(Dir4::Y)); assert_eq!(Dir4::from_xyzw(0.0, 0.0, 1.0, 0.0), Ok(Dir4::Z)); assert_eq!(Dir4::from_xyzw(0.0, 0.0, 0.0, 1.0), Ok(Dir4::W)); assert_eq!(Dir4::from_xyzw(-1.0, 0.0, 0.0, 0.0), Ok(Dir4::NEG_X)); assert_eq!(Dir4::from_xyzw(0.0, -1.0, 0.0, 0.0), Ok(Dir4::NEG_Y)); assert_eq!(Dir4::from_xyzw(0.0, 0.0, -1.0, 0.0), Ok(Dir4::NEG_Z)); assert_eq!(Dir4::from_xyzw(0.0, 0.0, 0.0, -1.0), Ok(Dir4::NEG_W));

Those tests shouldn't be necessary since they should always give that same output unless something goes catastrophically wrong.

crates/bevy_math/src/direction.rs

jnhyatt · 2025-05-16T14:16:34Z

Should impl StableInterpolate in common_traits.rs. If you're in VS code you can click the "n implementations" lens above the other Dir types to see all the traits they impl. Not sure how to do that without rust analyzer.

stevehello166 · 2025-05-16T15:07:14Z

Should impl StableInterpolate in common_traits.rs. If you're in VS code you can click the "n implementations" lens above the other Dir types to see all the traits they impl. Not sure how to do that without rust analyzer.

Implementing StableInterpolate for Dir4 would require implementing a slerp method which doesn't exist for Dir4 since I haven't found a way to implement it for 4 dimensions.

jnhyatt · 2025-05-16T15:26:31Z

Should impl StableInterpolate in common_traits.rs. If you're in VS code you can click the "n implementations" lens above the other Dir types to see all the traits they impl. Not sure how to do that without rust analyzer.

Implementing StableInterpolate for Dir4 would require implementing a slerp method which doesn't exist for Dir4 since I haven't found a way to implement it for 4 dimensions.

Ahhhhhhhh my bad!

stevehello166 · 2025-05-16T15:37:46Z

Should impl StableInterpolate in common_traits.rs. If you're in VS code you can click the "n implementations" lens above the other Dir types to see all the traits they impl. Not sure how to do that without rust analyzer.

Implementing StableInterpolate for Dir4 would require implementing a slerp method which doesn't exist for Dir4 since I haven't found a way to implement it for 4 dimensions.

Ahhhhhhhh my bad!

No problem. I didn't even know that this existed until you mentioned it.

ickshonpe · 2025-05-16T21:29:45Z

Should impl StableInterpolate in common_traits.rs. If you're in VS code you can click the "n implementations" lens above the other Dir types to see all the traits they impl. Not sure how to do that without rust analyzer.

Implementing StableInterpolate for Dir4 would require implementing a slerp method which doesn't exist for Dir4 since I haven't found a way to implement it for 4 dimensions.

We can use the formula from here:
https://en.wikipedia.org/wiki/Slerp

It might need to fall back to a lerp or something for very close values.

ickshonpe

Looks good.
Slerp support isn't essential, fine with leaving it for a follow up if you want.

stevehello166 · 2025-05-16T21:54:59Z

Looks good. Slerp support isn't essential, fine with leaving it for a follow up if you want.

It will have to be a follow up since glam is missing an angle_between function for Vec4 which would be essential if we use the geometric slerp mentioned in the Wikipedia article. I guess I'm going to work on putting that into glam next since I have nothing better to do with my time lol.

ickshonpe · 2025-05-16T22:19:00Z

Looks good. Slerp support isn't essential, fine with leaving it for a follow up if you want.

It will have to be a follow up since glam is missing an angle_between function for Vec4 which would be essential if we use the geometric slerp mentioned in the Wikipedia article. I guess I'm going to work on putting that into glam next since I have nothing better to do with my time lol.

The vectors are already normalized so the angle is just acos(dir_a.dot(dir_b)) I think.

stevehello166 · 2025-05-17T00:02:06Z

Looks good. Slerp support isn't essential, fine with leaving it for a follow up if you want.

It will have to be a follow up since glam is missing an angle_between function for Vec4 which would be essential if we use the geometric slerp mentioned in the Wikipedia article. I guess I'm going to work on putting that into glam next since I have nothing better to do with my time lol.

The vectors are already normalized so the angle is just acos(dir_a.dot(dir_b)) I think.

Oh. Well now I feel like an idiot. Thanks for pointing that out. I'll get a commit for that prepared right away. :)

IQuick143 · 2025-05-17T07:37:36Z

crates/bevy_math/src/direction.rs

+    #[inline]
+    pub fn slerp(self, rhs: Self, s: f32) -> Self {
+        // This uses a geometric slerp as opposed to the Quaternion slerp Dir3 uses
+        let angle = acos(self.dot(*rhs));


This can produce NaNs due to f32 imprecision (and/or imperfect normalisation) if both directions point the same way, or opposite ways.

Fixed. Perhaps not the best solution, but it is a solution.

IQuick143 · 2025-05-17T07:42:03Z

crates/bevy_math/src/direction.rs

+        let p0 = (sin((1.0 - s) * angle) / sin(angle)) * self;
+        let p1 = (sin(s * angle) / sin(angle)) * rhs;


These two lines will divide by zero (or numbers very close) for directions which are pointing the same way, or opposite ways. (Their angle is either 0 or pi)

I straight up just don't know how to fix this. I haven't been using rust for that long and I thought that this would've been much more simple than it ended up being. Perhaps I'll just cut the function and make it a problem for later.

I decided to use ickshonpe's approach after reading through the comments looking for a solution and just added a branching path to use lerp instead of slerp when the sine of the angle is 0.
Edit:
Perhaps I should also wait until I'm not in a bad mood to post comments like the previous one lol.

IQuick143 · 2025-05-17T07:43:25Z

crates/bevy_math/src/direction.rs

@@ -1323,4 +1363,34 @@ mod tests {
        );
        assert!(dir_b.is_normalized(), "Renormalisation did not work.");
    }
+
+    #[test]
+    fn dir4_slerp() {


These tests all slerp only between perpendicular directions.

I added two that test along parallel axes. More may be needed in the future. However it is also a problem shared among the other slerp functions, so more work may need to be done there.

IQuick143

The slerp function is rather unstable in its current state.

IQuick143 · 2025-05-18T14:33:42Z

crates/bevy_math/src/direction.rs

+                // Perhaps it should be improved, but I'm reaching my limit
+                result = self.map(|f| if f != 0.0 { 8.940697e-8 } else { 0.0 });
+            }
+            return Dir4(result);


This returns denormalised Dir4's most of the time.

IQuick143 · 2025-05-18T14:38:40Z

crates/bevy_math/src/direction.rs

+        // When the values are too small to use slerp it falls back on a regular lerp.
+        let angle = acos(self.dot(*rhs));
+        if angle.is_nan() {
+            return self;


This is an okay solution, although I prefer the method used in glam where they just clamp the input to acos to <-1.0, 1.0> to avoid this completely as this could potentially create sporadic jumps rarely.

IQuick143 · 2025-05-18T14:52:17Z

crates/bevy_math/src/direction.rs

+        if angle.is_nan() {
+            return self;
+        }
+        if angle == 0.0 || angle == PI {


Exact float comparison doesn't help much here. While it avoids the case sin(0.0) == 0.0, it doesn't avoid all of the nearby values where the value is very small and the result of the division is a fairly absurdly large number.

IQuick143 · 2025-05-18T14:54:48Z

crates/bevy_math/src/direction.rs

+
+        assert_relative_eq!(
+            Dir4::X.slerp(Dir4::NEG_X, 0.5),
+            Dir4(Vec4::new(8.940697e-8, 0.0, 0.0, 0.0)),


This is not a valid Dir4.

IQuick143

I would suggest just dropping the slerp, it's very complicated to get right and I think focusing on it would just bog down the rest of the PR from getting merged which would be a shame as the PR is quite good.

stevehello166 · 2025-05-18T23:51:20Z

I would suggest just dropping the slerp, it's very complicated to get right and I think focusing on it would just bog down the rest of the PR from getting merged which would be a shame as the PR is quite good.

Alright. I'll revert the slerp and make it not my problem

stevehello166 added 3 commits May 15, 2025 14:34

Added the dir4 struct and associated methods

f1d60f6

Added test for the creation of Dir4

b91eaa1

Cargo clippy

fed1216

Run cargo fmt

af4a070

Person-93 reviewed May 16, 2025

View reviewed changes

IQuick143 added A-Math Fundamental domain-agnostic mathematical operations S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels May 16, 2025

IQuick143 reviewed May 16, 2025

View reviewed changes

crates/bevy_math/src/direction.rs Outdated Show resolved Hide resolved

IQuick143 reviewed May 16, 2025

View reviewed changes

IQuick143 added the D-Straightforward Simple bug fixes and API improvements, docs, test and examples label May 16, 2025

ickshonpe reviewed May 16, 2025

View reviewed changes

crates/bevy_math/src/direction.rs Show resolved Hide resolved

stevehello166 added 2 commits May 16, 2025 08:45

Fixed documentation and naming errors

f26203a

Added test to cover Dir4 renormalization

4332ef1

stevehello166 requested review from Person-93, ickshonpe and IQuick143 May 16, 2025 16:47

IQuick143 approved these changes May 16, 2025

View reviewed changes

ickshonpe approved these changes May 16, 2025

View reviewed changes

stevehello166 added 2 commits May 16, 2025 18:05

Added slerp support for Dir4

da01c1a

Fix broken test for Dir4 to not rely on std

c3584d0

IQuick143 reviewed May 17, 2025

View reviewed changes

IQuick143 suggested changes May 17, 2025

View reviewed changes

Vrixyz added S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels May 17, 2025

stevehello166 added 2 commits May 17, 2025 20:47

Stabilized slerp for Dir4 and added tests

577aaa1

Fixed a broken test for Dir4

06b47f2

IQuick143 reviewed May 18, 2025

View reviewed changes

IQuick143 suggested changes May 18, 2025

View reviewed changes

stevehello166 added 2 commits May 18, 2025 18:05

Rollback slerp for Dir4

6bef645

Rustfmt for Dir4

1d70d90

IQuick143 approved these changes May 19, 2025

View reviewed changes

IQuick143 added S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it and removed S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels May 19, 2025

	/// Create a direction from a finite, nonzero [`Vec3`], normalizing it and
	/// Create a direction from a finite, nonzero [`Vec4`], normalizing it and

		let p0 = (sin((1.0 - s) * angle) / sin(angle)) * self;
		let p1 = (sin(s * angle) / sin(angle)) * rhs;

Uh oh!

Add a Dir4 to resolve #17983 #19223

Are you sure you want to change the base?

Add a Dir4 to resolve #17983 #19223

Uh oh!

Conversation

stevehello166 commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Testing

Uh oh!

github-actions bot commented May 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jnhyatt commented May 16, 2025

Uh oh!

stevehello166 commented May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jnhyatt commented May 16, 2025

Uh oh!

stevehello166 commented May 16, 2025

Uh oh!

ickshonpe commented May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ickshonpe left a comment

Choose a reason for hiding this comment

Uh oh!

stevehello166 commented May 16, 2025

Uh oh!

ickshonpe commented May 16, 2025

Uh oh!

stevehello166 commented May 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevehello166 May 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

IQuick143 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

IQuick143 left a comment

Choose a reason for hiding this comment

Uh oh!

stevehello166 commented May 18, 2025

stevehello166 commented May 15, 2025 •

edited

Loading

stevehello166 commented May 16, 2025 •

edited

Loading

ickshonpe commented May 16, 2025 •

edited

Loading

stevehello166 May 18, 2025 •

edited

Loading