REVIEW: Fullscreen system refactor

[JeffM2501]

Currently there is a big problem/confusion with the fullscreen API in raylib. The current API is not functional in an useable way and leads to frustrations. Much of what the current fullscreen API is rooted in older systems that were designed to work with CRT displays. This functionality is outdated on current displays and causes much more harm than any real benefit.

I feel that we should redo this API so that it is simple and easy to understand for current users. This may break some small functionality that I don’t feel is really ever used and that also has other (better) ways to implement.

This post is intended to start the discussion about how we can clean up this API to make it not confusing and easy to use like the rest of the raylib API. The goal of this post is to have an agreed upon design before any code or PRs are submited.

I would like to start by defining our terms and agreeing on what the behavior for each thing is. After that I would like to define a series of use cases for fullscreen modes, and then finally propose an API that would implement this. After that is all agreed upon, we can focus on getting the code to work with the design.

Terms

Fullscreen

A window that has no decoration and takes up the full pixel resolution of the desired display. The window runs at the display's current resolution. By default this should be the display’s native pixel resolution. If the system has multiple displays, clicking outside the display will not loose focus on the window. Alt+tab out of the application will minimize the window and return to the rest of the OS windows. Refocusing the application will restore the full screen window.

Borderless Window

A windows that has no decoration and takes up the full pixel resolution of the desired display. . The window runs at the display's current resolution. By default this should be the display’s native pixel resolution. This window differs from a fullscreen window in that it is not mutually exclusive with other displays. Other displays will continue to display content, and clicking on windows in them will change focus to the other application. The borderless window will not minimize when it loses focus. The window will cover any taskbar elements in the OS.

Maximized

A window that is decorated and expanded to fit the full usable area of its monitor. This window will not cover the taskbar elements in the OS and will behave like a normal window in all other respects

Topmost

An additional property that can be applied to a window that forces it to be on top of all other OS windows.

Change Resolution

The act of changing the physical display resolution of a monitor. This used to be a common thing to do in order to increase performance by reducing the number of pixels to render. This was acceptable because CRT monitors could adapt to wide ranges of resolutions. WIth the advent of fixed pixel displays (flat panel/lcd/oled/etc..) this is no longer a good idea. While systems can change the resolution of the data that is sent to the display, this requires the display hardware to upscale the signal to fit the display's physical pixels, and has serious quality implications. For this reason resolution changes are not common anymore, and other methods of reducing render size are available.

Use Cases

These are some use cases that people commonly have

I want a fullscreen game

The user wants to toggle to a fullscreen mode where the game is the only thing shown, filling the display. This is very traditional for many games. They want to toggle back and forth between this mode and a windowed mode, keeping the last windowed size when restored back to a windowed mode.

I want a fullscreen game, but I want to check discord

The user wants to toggle to a fullscreen borderless window mode where the game fills the display, but the user can still see and interact with applications on other displays. This is very common for modern games. They want to toggle back and forth between this mode and a windowed mode, keeping the last windowed size when restored back to a windowed mode.

I want to reduce my render resolution for speed

My game runs on a potato and I need to render less for speed.

API

This is proposed changes to existing APIs as well as new APIs.

ToggleFullscreen

This function would be changed to no change resolutions as it does now.
If the current window is not fullscreen it would simply expand the window size to fit the current display and toggle the fullscreen mode. The previous windowed size/position would be saved into raylib state data.
If the current window is full screen it would be resized to the previously saved size and the fullscreen mode in the platform canceled. This will be a breaking change in that the function will not change resolutions. This is minimized by the fact that this current behavior is NOT desired by most people and nearly everyone resizes the window to the display size before calling this in existing code, thus the behavior for those games will stay the same. If a user wishes to truly change resolution for performance, they would call SetMonitorResolution(see below), or user a render texture at a lower resolution. The main cause of confusion with this function right now is that it changes resolution and that is not an expected behavior, so it should be removed.

ToggleBorderlessWindow

Currently this function does not cover the taskbar. It needs to be changed to do so on all platforms. This function should have the same save/restore of window size/position that fullscreen does.

MaximizeWindow

Grows the window to fit the display, showing the taskbar.

MinimizeWindow

Iconify the window

SetMonitorResolution(int monitor, int width, int height) [NEW API]

Changes the specified monitor resolution to the nearest supported resolution that is specified. Should be combined with ToggleFullscreen but that would be up to the user.

Use Case Solutions using API

These are how this new API would handle the various use cases above.

I want a fullscreen game

Call ToggleFullscreen(), that’s it. Simple API just works as expected.

I want a fullscreen game, but I want to check discord

Call ToggleBorderlessWIndow(), that’s it. Simple API just works as expected.

I want to reduce my render resolution for speed

Load a render texture at the resolution you want to draw at, draw that texture to your screen. This is how modern games handle this case, as it allows the GPU to do the scaling, not the monitor’s display hardware.

[JeffM2501]

To note, I am aware that there are several PRs that have been submitted in the past with changes to these APIs. I feel that they have not been accepted simply because we have not agreed upon the expected operation of these functions, and got hung up on breaking behavior.
I want this discussion to hash all that out before we start looking at code so that we can have a clear direction to move it and no confusion about expectations.

[veins1]

Agree with every point. I would also add monitor refresh rate to SetMonitorResolution and some way to get all supported monitor modes.

[JeffM2501]

Yeah I'd start with this, and then get into modes and refresh later. I really don't think changing the display resolution is going to be something any significant portion of the raylb user base is going to do, so I would prefer to keep that out as a separate discussion, and not mix it up with this part. Resolution change will most likely only be done in VERY rare cases.

The goal of raylib is to have a simple API, so we should start with the most simple API and move from there.

[juan-medina]

One thing that it maybe consider is what some other engine are doing and is just dropping exclusive full-screen to be only borderless.

For example, ebiten an OpenGL golang engine, that as well runs in all desktops, mobile & web, only have borderless when switching to full-screen:

https://pkg.go.dev/github.com/hajimehoshi/ebiten/v2#SetFullscreen

Bgfx does not support exclusive full-screen is only borderless:

bkaradzic/bgfx#695

Beby a rust game engine consider exclusive full-screen as legacy:

https://docs.rs/bevy/latest/bevy/window/enum.WindowMode.html#variant.BorderlessFullscreen

And the reason why is mainly because modern graphics API are just well optimize in Windowed.

https://devblogs.microsoft.com/directx/demystifying-full-screen-optimizations/

For that reason, some games such World of Warcraft they don't have any more and exclusive mode.

And to be 100 honest, gamers nowadays is not that they want to check discord while playing, is just they have Spotify or YouTube in another window, or some twitch stream or so on, in fact the amount of people that have more than one screen right now is increasing large.

But we, programmers, believe that exclusive full-screen is the way to go because performance, when really is not like that any more, and all arguments in the top topic in the discussion show how modern games play the games in the same reolution and refresh rate that they desktop.

[JeffM2501]

I agree with this in concept, but raylib is not an engine. I think it's trivial to support exclusive fullscreen and thus we should keep that API. That leaves it up to the end user. I agree that most people probably won't do it, but I would not specifically remove it as a feature for 6.0. This is simply minimize how much of the API gets broken. If we find that nobody is using the new fullscreen API, we then evaluate it's removal as a separate task.

[cos1110]

One important aspect is that when Fullscreen mode is on, then the OS keys should be disabled.

As for example if you press Win+E (or Ctrl+Shift+Esc) there should not be any background action happening. When you press Ctrl+Alt+Delete then is good idea to interrupt the TOPMOST state so the task manager pops up.

There should be a dozen of use cases in other OS's as well about how this new fullscreen mode should behave as expected based from the classic fullscreen mode.

[designerfuzzi]

OS keys .. disabled.

would depending how you distribute a macAPP be good reason to trigger either bad User experience or a simple Appstore ban. OS keys are meant to control an OS, regardless if an APP developer ignores them or does simply not make use of them. Forcing to escape a fullscreen scenario via poping up Task Manager aka Finder is also a good reason to get banned.

It is rather so that raylib and in particular its underlaying glfw3 does not entirely implement window related NSNotifications, just some of them, which in turn leads to miss out some scenario states in which a developer would act to make the experience smooth, in and out of fullscreen.

I was developing on a solution to fix the resizing flickering of raylib hosted windows on mac and had to implement all that missing stuff in glfw to come closer. And with some more tweaks in rcore and rcore_desktop i figured out, it is possible.. (no flicker)

Bildschirmvideo.aufnehmen.2025-01-07.um.02.17.26.mov

in this particular case even the window header is rendered by raylib, which means my app uses an undecorated window mode.

here some snipped out of my code that explains the relation ship of raylib and the coloured window control buttons of a macApp (red/yellow/yellow)

switch (xaxis) {
    case red: ForceWindowToClose(); break; //non-raylib func to address win-close-misses of raylib.
    case yellow: IsWindowMinimized() ? RestoreWindow() : MinimizeWindow(); break;
    case green: IsWindowMaximized() ? RestoreWindow() : MaximizeWindow(); break; 
}

Surprise: no FullScreen function used at all.
That is Fullscreen has multiple meanings in macOS. Once the IsWindowMaximized()==true the Finder (mainmenu) header could be hidden and the windowsize increased. Which usually is found as result of "CMD+green_btn". Another app could also provide Fullscreen as classic fullscreen, meaning the entire screen resolution gets refitted to match the content, in example for a lower resolution video.

maybe obvious i am working on a new UI model making use of raylib even for the window controls.

[cos1110]

Just for the sake of having a clear picture I tested those:

Fullscreen is interrupted by WinKey
• Duckstation emulator: ✅
• ePCSX2 emulator: ✅
• Unreal5 game ("HalfSword"): ✅
• Unreal4 game ("TombRaider DOX"): ✅
• Unity3D demo ("Unity Chan"): ✅
• Godot game ("HotShots"): ✅
• C# Game ("Celeste64"): ✅

Looks like you can't help it, you need to use a controller to play the game or to be careful not to press WinKey accidentally. I wonder though if there are other potential open source projects (engines / frameworks) that use such a workaround. 🤔

[Reticulatas]

Chiming in that the current complexity leads to difficulty with common operations and a lot of needless code.

I think ideally Raylib would support an API like:

SetWindowMode(int mode)

where mode is defined as:

enum WindowMode { WINDOW_MODE_WINDOWED, WINDOW_MODE_FULLSCREEN_EXCLUSIVE, WINDOW_MODE_FULLSCREEN_BORDERLESS, ... };

A mode would be defined as a collection of window state flags that match conventional expected behavior for the mode. Video game window behaviors are widely established at this point and if customization is needed then SetWindowState is still available.

• WINDOWED MODE - Raylib's default. Not resizable, fixed screen resolution, windowed.
• FULLSCREEN EXCLUSIVE - Legacy support for fullscreen exclusive, hardware fullscreen
• FULLSCREEN BORDERLESS - Same as current borderless, but not topmost as it is currently which leads to unconventional window behavior

Having Set instead of Toggle (as it is now) would lend itself better to common game operations, like toggling a checkbox to go into Fullscreen in a settings menu, etc.

[cos1110]

Yeap, this looks like a much more clear plan, so the user can explicitly set the behavior they need.
FULLSCREEN_BORDERLESS: for streamers and developers having multiple desktop utilities at the same time
FULLSCREEN_EXCLUSIVE: for gamers that want high-end uninterrupted behavior

As mentioned above as well in this list of games+engines tested:
#4507 (reply in thread)

As for example in the Unreal4 game there would be those options to choose on the display settings:
Windowed, Windowed Fullscreen, Fullscreen
[ Interestingly enough, that the 'FullScreen' mode processes the WinKey event as normal and actually interrupts the application. ]

[lowiemelatonin]

It's pretty lame that this has been totally ignored and unnoticed, this bothers me a lot because this issue kept me from making the 80s like visual novel that I wanted

[JeffM2501]

this is not ignored or unnoticed, ray and I discuss it on occasion and I plan on submitting a PR before the next release.
Nothing in the current API should prevent you from shipping a game, you can toggle fullscreen like we described, you just have to do some tricks first (resize the window to the monitor first), The core issue is confusion in the API, not a lack of functionality.

[lowiemelatonin]

I see!

[nahuakang]

Just a friendly reminder that you're not entitled to other people's time. The open source maintainers and contributors can work on a feature/refactoring if they have the time and energy. Whether it's "lame" or not or "bothers" you or not is not their problem. It's your problem. You can solve it, too.