This now mentions the main callbacks as a possible option, and removes the
part about prebuilt libraries. The latter can return when Emscripten packages
SDL3.
Fixes#11080.
Wayland can expose displays in any arbitrary order, and doesn't have the native concept of a primary display. However, there are games that presume that the first listed display is the primary, which can lead to problems if that output isn't necessarily the ideal one, as they may use that display to build a resolution list or as the default fullscreen output. This sorts displays by position, then attempts to find the primary display, first by querying the explicit ordering hint, then the GNOME DBus property, then tries to determine the 'best' display according to the criteria that is generally ideal for games and media playback.
The makes the list of displays deterministic, as long as the desktop configuration remains static, with a reasonably appropriate one prioritized as primary, even if there is no explicit way to retrieve the primary display. In the case where a user has a particularly esoteric physical display configuration, the new hint enables explicitly overriding the sorting and selection logic, allowing the entire display order to be customized, if necessary.
especially SDL_VIDEODRIVER is commonly used to use the native Wayland
backend, so I think it's a good idea to keep supporting the old name
instead of forcing users to find out that they now have to add an
underscore..
Not sure how popular SDL_AUDIODRIVER is, but with all the audio backends
that exist on Linux alone I'm sure some people use it to work around
sound issues.
Note: Doing this in the SDL_hints implementation instead of the
call-sites of SDL_GetHint(SDL_HINT_VIDEO_DRIVER) etc ensures that
1. Hint priorities work (env var overriding hint set by application with normal
priority, but not when application used SDL_HINT_OVERRIDE)
2. SDL_ResetHint() (called by user code) respects the fallback
environment variable
Mark the event as removed as there is no true direct mapping in SDL3, and inform clients that they should handle the explicit SDL_EVENT_WINDOW_RESIZED and SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED events instead.
We require stdbool.h in the build environment, so we might as well use the plain bool type.
If your environment doesn't have stdbool.h, this simple replacement will suffice:
typedef signed char bool;
This was the only API that broke the "GetNumThings" convention
used elsewhere, so renaming it helps with consistency.
Adding "logical cores" to the name also makes it a bit
more immediately obvious what the count actually represents.
Also marked the existing functions as unsafe, as they can cause crashes if used in multi-threaded applications.
As a bonus, since the new functions are hashtable based, hint environment lookups are much faster.
wikiheaders needs the documentation in the first row of the line, at least
currently, so I've only indented things I could get away with, but it might
be a little easier to follow the preprocessor logic now.
