Allow retrieving list of common resolutions

[RedMser]

Describe the project you are working on

Any game with an options menu.

Describe the problem or limitation you are having in your project

An options menu usually contains a resolution selector. Knowing which resolutions to display in this list is a very difficult task and it changes based on what the device can show.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Add two APIs for listing screen resolutions:

1. Query the GPU for natively supported screen resolutions, e.g. what your monitor can output natively. These resolutions are also the only ones that should be used when Godot is running in exclusive fullscreen on e.g. Windows.
2. Based on a given base resolution, calculate a list of recommended windowed resolutions while keeping the given aspect ratio. This can be used for resolution selection in windowed mode, by basically down-scaling the given resolution until it reaches a minimum value like 640x360.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

APIs could look like this (pseudo-code):

// Get supported native resolutions of given screen, used for exclusive fullscreen resolution selection.
// Introduce a new constant `SCREEN_ANY = -2` which can be used to get a combined list of all screens' supported resolutions.
// Dictionary contains "width", "height" and "refresh_rate".
Array<Dictionary> DisplayServer::screen_get_supported_resolutions(int screen = SCREEN_OF_MAIN_WINDOW) const;
// Get recommended resolutions given a base resolution, used for windowed mode resolution selection.
// The default -1 vector will use `screen_get_size(SCREEN_OF_MAIN_WINDOW)` as value of base_resolution.
Array<Vector2i> DisplayServer::get_windowed_resolutions(Vector2i base_resolution = Vector2i(-1, -1)) const;

Regarding screen_get_supported_resolutions: Windows API has EnumDisplaySettings for querying the GPU on native resolutions. Need to investigate how other OSes can support this.

Regarding get_windowed_resolutions: This is basic math which can be done for all platforms.

If this enhancement will not be used often, can it be worked around with a few lines of script?

The first API requires a native OS call, which is not simple. The second API has less logic, but is still not trivial due to possible edge cases (like a minimum resolution).

Is there a reason why this should be core and not an add-on in the asset library?

This is an essential feature for games that provide a standard options menu.

[zinnschlag]

Can you provide a use case for this feature? I don't see any. Sounds redundant to me.

If you are going full screen in Godot you get your native screen resolution anyway. No need to specify it explicitly.

If you are not running in full screen (AKA windowed mode) why would you limit yourself to only a specific list of resolutions? While we are at it why would you want to keep the aspect ratio of your screen? Both are annoying at best and at times a serious usability issue.

These resolution selector options in the options/settings menu are actually kinda dumb. IMO they need to go away. These made sense with previous generations of monitors that you would often run in a variety of resolutions (even when full screen). But when the selector is used only in windowed mode it is pointless.

In my current project I have a fullscreen option and two numeric input fields for width and height that enforce minimum size but allow free resizing otherwise. And the user can simply resize the window manually (by dragging its edges) to change the resolution. I expect that to be the method user will use most of the time.

[RedMser]

@zinnschlag

If you are going full screen in Godot you get your native screen resolution anyway. No need to specify it explicitly.

Only for borderless fullscreen mode. With exclusive fullscreen (Windows only - DisplayServer.WINDOW_MODE_EXCLUSIVE_FULLSCREEN), the screen's actual resolution can be changed by the game and the scaling is done by the monitor.

If you are not running in full screen (AKA windowed mode) why would you limit yourself to only a specific list of resolutions? While we are at it why would you want to keep the aspect ratio of your screen? Both are annoying at best and at times a serious usability issue.

It can be useful if they want an exact resolution with a precise aspect ratio (e.g. for recording gameplay footage at non-native resolution) without requiring the player to edit a config file or input numbers in the settings screen.

Preset choices are especially important if your game is designed around a specific aspect ratio like 16:9, if you decide to add black bars for other aspect ratios (not saying this is "the way to do it", just a design decision each developer can take). Also, these would just be presets to select, but you can still allow resizing the window independently from that.

These resolution selector options in the options/settings menu are actually kinda dumb. IMO they need to go away. These made sense with previous generations of monitors that you would often run in a variety of resolutions (even when full screen). But when the selector is used only in windowed mode it is pointless.

Many computers can't run more graphically demanding games at native resolution smoothly, so users would be forced to play in window mode if they could not choose a resolution for exclusive fullscreen. There is no other choice but to query the OS for resolutions and force one of the selected values upon the user.

I suppose that makes the native resolution API less useful for platforms outside of Windows, though it could still be used for configuring variable render scaling perhaps?

In my current project I have a fullscreen option and two numeric input fields for width and height that enforce minimum size but allow free resizing otherwise. And the user can simply resize the window manually (by dragging its edges) to change the resolution. I expect that to be the method user will use most of the time.

Numeric input fields are not very accessible to users that are not familiar with computers ("What number do I enter here? What was the default?". A dropdown with commonly used items is far more convenient to configure. Precise input should probably stay to manually editing the config file. There's a good reason why basically no modern game does it any other way.

[zinnschlag]

Only for borderless fullscreen mode. With exclusive fullscreen (Windows only - DisplayServer.WINDOW_MODE_EXCLUSIVE_FULLSCREEN), the screen's actual resolution can be changed by the game and the scaling is done by the monitor.

I admit, I don't know a thing about that. Its been a while since a last touched a Windows system. But if it is Windows only, it probably needs a windows only solution. No idea how that would work in the context of Godot.

It can be useful if they want an exact resolution with a precise aspect ratio (e.g. for recording gameplay footage at non-native resolution) without requiring the player to edit a config file or input numbers in the settings screen.

Actually it is the other way around. Preset-options mean that you have to edit a config file if you want a specific resolution (that not happens to be in the list). Happened to me more than once. Very annoying.

As for recording game footage (let's say for YouTube or Twitch) you typically want one of the standard resolutions (720p and so on). The aspect ratio of these does not necessarily match the aspect ratio of your screen. Also, that is kinda a niche use case. Someone who is interested in streaming will likely have to do some setup work anyway and manually entering the desired resolution should barely be significant compared to that.

Preset choices are especially important if your game is designed around a specific aspect ratio like 16:9,

For games that require a specific aspect ratio (probably mostly 2D) you would want to use resolutions based on the hard-coded aspect ratio the game is based on. Not the aspect ratio of your screen.

Numeric input fields are not very accessible to users that are not familiar with computers ("What number do I enter here? What was the default?".

That's why the window can be resized manually.

Precise input should probably stay to manually editing the config file.

I aggressively disagree with this statement. I guess it is tolerable if you can manually resize the window. But having to dig into the config file to set the window size is a pain in the arse.

[Calinou]

In the era of resolution scaling percentages, getting a list of "video modes" isn't really relevant anymore. Modern games typically render their viewport at desktop resolution, with a slider to scale down the 3D rendering resolution to make it less demanding if needed. (This is built-in in 4.0.alpha, but you'll need a second Viewport to do it in 3.x.)

Also, we have a demo project showcasing multiple resolution support in Godot: https://github.com/godotengine/godot-demo-projects/tree/master/gui/multiple_resolutions

[Zireael07]

That slider thingy ought to be better documented... I went with FSR when I see there's a simpler solution??

[Calinou]

I went with FSR when I see there's a simpler solution??

Bilinear scaling is the default in 4.0, so it is actually the simpler solution 🙂

[Calinou]

Closing, as this is made obsolete by resolution scaling support or using SubViewports with a different resolution from the window.

To abide by modern expectations, Godot never changes fullscreen resolution even in exclusive fullscreen mode, so you don't need to get a list of screen resolutions supported by the hardware.