Add support for letterboxing

[alice-i-cecile]

What problem does this solve or what need does it fill?

Cutting off segments of the game screen using black bars (a letterbox) is a common technique for both cinematic cutscenes and for supporting unusual aspect ratios, particularly for pixel art.

What solution would you like?

Expose a simple setting that sets the letterboxing mode, probably to Window or cameras.

What alternative(s) have you considered?

Add an example demonstrating how to set this up manually, probably using render targets.

Additional context

Discussed on Discord in the context of pixel art games. Prompted by the closure of #14153.

[alice-i-cecile]

Cart's demo: https://gist.github.com/cart/87c0215aa650170f09164fcffc252139

[cart]

Disclaimers: the demo is two years old now, so it would need porting. I think there is room for a simpler upstream solution. I think we could probably also come up with a Camera-level letterboxing API that doesn't rely on Bevy UI.

[Sapein]

I do hope you don't mind me chiming in on this. That being said, I've been giving some thought to this over the past few days, and while I definitely don't have the knowledge to implement this, I do have some ideas at the very least that could be helpful.

I think letterboxing should be done on the camera, and not necessarily on the window -- if it's possible. I think it would fit better with the APIs that the Camera has, and it would be (in my opinion) a bit more intuitive to look to the Camera for the settings for this rather than the Window. As an example, when it comes to setting the background color of areas that have nothing rendered to them, you set the color on the Camera (The clear-color should also probably be used for the letterboxing, which could be useful for artistic purposes).

Additionally, at least for certain classes of games those games would likely want to letterbox at specific resolutions, or at resolutions where the output would be scaled by a non-integer amount. This would be useful for things like 2D Games which use Pixel Art, like I tend to do. My assets and game is designed at 360p (16:9) so that it can be scaled to most other 16:9 displays (720p, 1080p, etc). if it is played on a resolution outside of 16:9 then I need to letterbox or just not support those resolutions whole-cloth. I'm already having to set scaling mode on the Camera as well to get behavior that I want, and in these circumstances it would be more intuitive to have it be on the Camera, than on the window.

If letterboxing is done on the Window specifically, then it would feel a bit weird to setup, at least for me, as if you wanted to enable/disable it then you'd have to go to the Window to do so, which for things like Cutscenes would likely be a bit weird.

I also searched the Bevy discord for letterboxing, and I noticed that most people are looking at the Camera to see if there's a letterbox implementation, with some expecting Scaling modes to letterbox automatically (specifically for Camera2D at least).

[cart]

I fully agree that this should be a camera setting and not a window setting.

[Jaso333]

Hello. I actually created something to do this today, but I named it "bevy_fixed_viewport", as it directly impacts the camera's viewport:

https://github.com/Jaso333/bevy_fixed_viewport

It would be nice to get this integrated into the engine.

The example shows how it works, and allows you to use the arrow keys to dynamically change the aspect ratio on the fly.

[benfrankel]

@Jaso333 it would be nice to give that a permissive license so it can be used by others, assuming that's your intent (even if it's a tiny library).

[Sapein]

I've been playing around with this and I think I got something that's pretty decent FWIW, I'm currently working on improving documentation and just getting things together but: https://github.com/Sapein/bevy_simple_screen_boxing

The API is, in my opinion, rather decent and I've tried to support for boxing a Camera with any RenderTarget. There are probably some things I've missed, or just didn't consider but it does seem to work.

The way this works is you just add a CameraBox component to a Camera, and configure it and then it just 'works'.