[Merged by Bors] - Add the possibility to create custom 2d orthographic cameras

[nsarlin]

Objective

• The OrthographicCameraBundle constructor for 2d cameras uses a hardcoded value for Z position and scale of the camera. It could be useful to be able to customize these values.

Solution

• Add a new constructor custom_2d that takes far (Z position) and scale as parameters. The default constructor new_2d uses this constructor with far = 1000.0 and scale = 1.0.

[MrGVSV]

Might want to add some documentation indicating that the camera will be placed at a z-position of far - 0.1 looking toward the world origin (like in the documentation for new_2d()).

[jakobhellermann]

Since you can already express this with

let bundle = OrthographicCameraBundle {
  orthographic_projection: OrphographicProjection {
    far: 1000.0,
    scale: 1.0,
    depth_calculation: DepthCalculation::ZDifference,
    ..Default::default()
  },
 ..OrthographicCameraBundle::new_2d(),
};

I wonder whether having a custom contructor is worth it. Usually in bevy the recommended way to configure bundles is by overriding some fields and extending ..Default::default() or ..OrthographicCameraBundle::new_2d(), like there is no PbrBundle::new(mesh, material).

When you have a custom contructor you need to decide between having a very long new_with_far_scale_depth_calculation_scaling_mode(_: f32, _: f32, _. DepthCalculation, _: ScalingMode) or having a constructor for the common case, but then when someone wants to change the scaling mode they need to use the other pattern anyways.

[nsarlin]

Since you can already express this with

let bundle = OrthographicCameraBundle {
  orthographic_projection: OrphographicProjection {
    far: 1000.0,
    scale: 1.0,
    depth_calculation: DepthCalculation::ZDifference,
    ..Default::default()
  },
 ..OrthographicCameraBundle::new_2d(),
};

I don't think this would work in that case because other components of the bundle would still be set with far = 1000.0. This argument is used in different places so I think it can be valuable to have a way to set it just once.

[jakobhellermann]

Oh right, the value is used both in the Camera and OrthographicProjection. In that case I totally see the value.

I don't like the name custom_2d though because it gives no intuition about what the values mean. Maybe with_far_scale would be an option, although it sounds like it sets the "far scale". with_far_plane_and_scale?

[alice-i-cecile]

The other option for clarity here is that we could use custom CameraPlane::Far(f32) and CameraScale(f32) types for these.

A longer name is probably better, but I thought it was worth bringing up

[MrGVSV]

Oh right, the value is used both in the Camera and OrthographicProjection. In that case I totally see the value.

I don't like the name custom_2d though because it gives no intuition about what the values mean. Maybe with_far_scale would be an option, although it sounds like it sets the "far scale". with_far_plane_and_scale?

Alternatively, we could just have it set the far plane since that's the tricky one. Users could then just mutate the scale after construction via camera.orthographic_projection.scale if they need to.

[nsarlin]

Alternatively, we could just have it set the far plane since that's the tricky one. Users could then just mutate the scale after construction via camera.orthographic_projection.scale if they need to.

That's a good point. Maybe with the name 2d_with_far new_2d_with_far to make it clear that it's a 2d camera ?

[mockersf]

I'm not completely a fan of the fn new_2d_with_far(far: f32) -> Self method...
What would you think of having instead a fn with_far(mut self, far: f32) -> Self that would apply the given far to an existing OrthographicCameraBundle? So you would do OrthographicCameraBundle::new_2d().with_far(5000.0).
Not suggesting the change, it has drawbacks too like needing to duplicate some code.

[superdump]

I'm not completely a fan of the fn new_2d_with_far(far: f32) -> Self method... What would you think of having instead a fn with_far(mut self, far: f32) -> Self that would apply the given far to an existing OrthographicCameraBundle? So you would do OrthographicCameraBundle::new_2d().with_far(5000.0). Not suggesting the change, it has drawbacks too like needing to duplicate some code.

I prefer the current approach. Otherwise I feel like for API consistency we should have ::new().as_2d().with_far(5000.0) but then for construction efficiency I'd probably want it to be a builder not building at every step.

[alice-i-cecile]

but then for construction efficiency I'd probably want it to be a builder not building at every step.

This is probably a silly concern here; 99% of games will have exactly one camera built ever ;)

[alice-i-cecile]

bors r+

[bors]

Pull request successfully merged into main.

Build succeeded:

• build-android
• build (nightly, ubuntu-latest)
• build (stable, macos-latest)
• build (stable, ubuntu-latest)
• build (stable, windows-latest)
• build-wasm (nightly, ubuntu-latest)
• build-wasm (stable, ubuntu-latest)
• check-benches
• check-doc
• check-markdown-links
• check-missing-examples-in-docs
• check-unused-dependencies
• ci
• markdownlint
• miri
• run-examples