Split OrthographicProjection::default into 2d & 3d (Adopted)

[Azorlogh]

Adopted PR from dmlary, all credit to them! #9915

Original description:

Objective

The default value for near in OrthographicProjection should be different for 2d & 3d.

For 2d using near = -1000 allows bevy users to build up scenes using background z = 0, and foreground elements z > 0 similar to css. However in 3d near = -1000 results in objects behind the camera being rendered. Using near = 0 works for 3d, but forces 2d users to assign z <= 0 for rendered elements, putting the background at some arbitrary negative value.

There is no common value for near that doesn't result in a footgun or usability issue for either 2d or 3d, so they should have separate values.

There was discussion about other options in the discord 0, but splitting default() into default_2d() and default_3d() seemed like the lowest cost approach.

Related/past work #9138, #9214, #9310, #9537 (thanks to @Selene-Amanita for the list)

Solution

This commit splits OrthographicProjection::default into default_2d and default_3d.

Migration Guide

• In initialization of OrthographicProjection, change ..default() to ..OrthographicProjection::default_2d() or ..OrthographicProjection::default_3d()

Example:

--- a/examples/3d/orthographic.rs
+++ b/examples/3d/orthographic.rs
@@ -20,7 +20,7 @@ fn setup(
         projection: OrthographicProjection {
             scale: 3.0,
             scaling_mode: ScalingMode::FixedVertical(2.0),
-            ..default()
+            ..OrthographicProjection::default_3d()
         }
         .into(),
         transform: Transform::from_xyz(5.0, 5.0, 5.0).looking_at(Vec3::ZERO, Vec3::Y),

[janhohenheim]

Makes sense to me :) I would like to not add API without documentation, otherwise this looks good.

[Azorlogh]

@janhohenheim Thanks for the review! I removed the outdated comment & added docs to default_2d & default_3d. Let me know if they're clear enough

[janhohenheim]

Looks good now, thanks! Left some minor documentation suggestions, but nothing blocking :)

[IQuick143]

Would it make sense for Default to default to default_3d (like FromWorld does)?

[Azorlogh]

Would it make sense for Default to default to default_3d (like FromWorld does)?

It would defeat the point, since beginners would keep writing

OrthographicProjection {
    scaling_mode: ScalongMode::FixedVertical(2.0),
    ..default()
}

on their 2d cameras, ending up with a black screen.
With this PR they're forced to make the choice