Prepare API for multimonitor support

[L0laapk3]

Multimonitor support

This is my proposal for a plan to support multiple monitors in the future. To keep a good overview about what changes, I propose to split it up in several PRs:

1. A PR Monitor implementation, breaking API changes (this PR).
2. PRs populating each of the platforms MonitorImpls.
3. A PR adding a RenderWindow constructor overload with a Monitor parameter.
4. PRs adding new functionality into Monitor such as listing all available monitors and getting information about monitors.

Comments about the general plan as lined out above are welcome, as well as comments on 1. this PR. However, please try to keep specific comments about PRs 2-4 out of this page if they have no impact on this specific PR. These comments could possibly be directed at #2136.

This PR

The goal of this PR is to only make the necessary breaking changes to the API for multimonitor support, while keeping all functional behavior identical.

Description

• A new Monitor API class has been created.
• VideoModes functions have been moved to Monitor as they are all monitor dependent.
• VideoModeImpls have been moved to MonitorImpl, and this class has been made non-static.
• MonitorImplTargets have been populated with placeholders with identical behavior as before the PR to limit the scope. See PR 2 in the plan above.

Tasks

• Tested on Linux
• Tested on Windows
• Tested on macOS
• Tested on iOS
• Tested on Android

How to test this PR?

#include <SFML/Graphics.hpp>

int main()
{
    sf::RenderWindow window(sf::VideoMode(sf::Monitor::getPrimaryMonitor().getDesktopMode(), "Minimal, complete and verifiable example");
    window.setFramerateLimit(60);

    while (window.isOpen())
    {
        while (const auto event = window.pollEvent())
        {
            if (event.is<sf::Event::Closed>())
                window.close();
        }

        window.clear();
        window.display();
    }
}

[ChrisThrasher]

a plan to support multiple monitors in the future

Do we have any confidence that the team has the expertise and resources to actually implement these features? My concern is that we're building a road to nowhere by creating an API without a plan to ever implement new features with it.

[vittorioromeo]

a plan to support multiple monitors in the future

Do we have any confidence that the team has the expertise and resources to actually implement these features? My concern is that we're building a road to nowhere by creating an API without a plan to ever implement new features with it.

Without commenting on the "expertise and resources" part, I'd like to say that it's pretty embarassing to not support multiple monitors in a graphics library in 2024, no matter how "simple" it is.

[vittorioromeo]

Some minor improvements to our original code

[vittorioromeo]

@L0laapk3: can you help me understand the relationship between VideoMode and Monitor a bit more?

Does VideoMode become just a simple struct to represent width, height, and bpp?

If I create a RenderWindow with a specific Monitor and VideoMode, how do I ensure that the video mode is supported by that monitor? What would happen if it isn't?

[eXpl0it3r]

Some minor improvements to our original code

Before we jump too much into reviewing code that was mostly meant as a jump off point for API discussions, lets focus on that first.

[L0laapk3]

@vittorioromeo

Does VideoMode become just a simple struct to represent width, height, and bpp?

The way I changed it now, yes.

@L0laapk3: can you help me understand the relationship between VideoMode and Monitor a bit more?

Each monitor has a list of supported fullscreen VideoModes. In fullscreen mode it must be an exact match with one of the supported modes to work afaik. In windowed/borderless mode it doesn't matter (more on this below)

If I create a RenderWindow with a specific Monitor and VideoMode, how do I ensure that the video mode is supported by that monitor? What would happen if it isn't?

Nothing is strictly stopping you from entering custom numbers and creating your own VideoMode object, but if you're using fullscreen, the RenderWindow constructor will validate it first..

As a sidenote, in my opinion the RenderWindow constructor VideoMode parameter is being abused a little as it is doubling up as the window size in windowed mode. For that reason, maybe the constructor should also accept Rect when not in fullscreen mode, or some other solution could be thought up. anyways Im not planning to change that part in this PR.

[coveralls]

Pull Request Test Coverage Report for Build 9033044943

Details

• 48 of 68 (70.59%) changed or added relevant lines in 15 files are covered.
• 4 unchanged lines in 4 files lost coverage.
• Overall coverage increased (+0.02%) to 51.913%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/SFML/Window/Unix/GlxContext.cpp	1	2	50.0%
src/SFML/Window/Unix/WindowImplX11.cpp	0	1	0.0%
src/SFML/Window/Window.cpp	0	1	0.0%
src/SFML/Window/macOS/InputImpl.mm	0	1	0.0%
src/SFML/Window/macOS/SFContext.mm	1	2	50.0%
src/SFML/Window/macOS/SFWindowController.mm	0	2	0.0%
src/SFML/Window/WindowBase.cpp	0	3	0.0%
src/SFML/Window/DRM/DRMContext.cpp	0	5	0.0%
src/SFML/Window/DRM/MonitorImplDRM.cpp	0	5	0.0%

Files with Coverage Reduction	New Missed Lines	%
include/SFML/Window/WindowBase.hpp	1	0.0%
include/SFML/Window/Window.hpp	1	0.0%
src/SFML/Window/WindowBase.cpp	1	75.84%
src/SFML/Window/Unix/WindowImplX11.cpp	1	43.17%

Totals
Change from base Build 9020114451:	0.02%
Covered Lines:	10495
Relevant Lines:	19026

---

💛 - Coveralls

[L0laapk3]

Looks ready for review to me

[ChrisThrasher]

Do you expect any of these MonitorImpl classes to have data members in the future? Currently none of them contain any data which means we could simplify this significantly by converting all these classes into a collection of free functions within a namespace.

[L0laapk3]

Do you expect any of these MonitorImpl classes to have data members in the future?

@ChrisThrasher yes, they will definitely have data members once they are populated. That is why I went through all the trouble of non-static impl classes :D

For reference, I have an unix implementation prepared here: https://github.com/L0laapk3/SFML/pull/1/files
But that is blocked until this PR is more mature, I do not want to spend a lot of effort into something that I may still be asked to change.

[L0laapk3]

whoops, that last commit & message was meant to go into my games' repository, not its sfml subrepository. reverted.

[JonnyPtn]

I'm not sure Monitor is the best name here as it's a bit specific, something like VideoDevice seems better to me, and fits names we use elsewhere

[L0laapk3]

I'm not sure Monitor is the best name here as it's a bit specific, something like VideoDevice seems better to me, and fits names we use elsewhere

Im open to name suggestions and not super attached to any names.
Specifically for the VideoDevice suggestion, I did google it quickly and looked at the first 8 results, they all referred to camera devices, most of the results were about APIs. So I don't think thats a great idea.

[L0laapk3]

See also https://github.com/SFML/SFML/wiki/SD:-Multi-Monitor-Support