Add information about hit side to Ray3d::intersect_plane

[Mati18505]

Objective

Currently, Ray3d::intersect_plane always returns intersections on both faces of the plane, including backface hits.
This behavior:

• isn’t documented clearly,
• cannot be changed by the user without duplicating the method.

Fixes #20152

Solution

• Introduced HitSide enum to allow the user to retrieve information about intersected plane side.
• Changed return type of Ray3d::intersect_plane from Option<f32> to Option<(f32, HitSide)>.

Testing

Added unit tests.

---

Showcase

if let Some((distance, hit_side)) = ray.intersect_plane(Vec3::Z, InfinitePlane3d::new(Vec3::Z)) {
  match hit_side {
    HitSide::Front => (),
    HitSide::Back => (),
  }
}

[github-actions]

Welcome, new contributor!

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

[github-actions]

It looks like your PR is a breaking change, but you didn't provide a migration guide.

Please review the instructions for writing migration guides, then expand or revise the content in the migration guides directory to reflect your changes.

[alice-i-cecile]

To me the big question here is if we solidify the fact that a plane has a "front" (the current approach), or if we should be creating a new Halfspace type. I am currently undecided, but we should debate it a bit.

[IQuick143]

Personally I'm not a huge fan of putting everything everything into one universal method. Though the code diff is actually nicer than what I expected. (ex: All the backface-relevant data is already computed anyway and the method is already full of branches.) So I'm not against merging this.

Given that the user has to supply an argument (whose documentation explains the details), so they won't be surprised by what the method does.

[atlv24]

How about making the function params stay the same but changing the output to Option<(f32, HitSide)> where enum HitSide { Front, Back } or something like that, then have users match on it or deconstruct-discard it?

[IQuick143]

That would work by me too yeah.

[alice-i-cecile]

I like changing the return type!

[Mati18505]

Thanks for all the suggestions! I agree that using the return type instead of parameter makes everything cleaner.

I've updated Ray3d::intersect_plane to return Option<(f32, HitSide)>, where HitSide is an enum with Front and Back variants.

I'm wondering if Ray2d should also have HitSide for consistency.