SDL window size, state, and position functions have been considered immediate, with their effects assuming to have taken effect upon successful return of the function. However, several windowing systems handle these requests asynchronously, resulting in the functions blocking until the changes have taken effect, potentially for long periods of time. Additionally, some windowing systems treat these as requests, and can potentially deny or fulfill the request in a manner differently than the application expects, such as not allowing a window to be positioned or sized beyond desktop borders, prohibiting fullscreen, and so on.
With these changes, applications can make requests of the window manager that do not block, with the understanding that an associated event will be sent if the request is fulfilled. Currently, size, position, maximize, minimize, and fullscreen calls are handled as asynchronous requests, with events being returned if the request is honored. If the application requires that the change take effect immediately, it can call the new SDL_SyncWindow function, which will attempt to block until the request is fulfilled, or some arbitrary timeout period elapses, the duration of which depends not only on the windowing system, but on the operation requested as well (e.g. a 100ms timeout is fine for most X11 events, but maximizing a window can take considerably longer for some reason). There is also a new hint 'SDL_VIDEO_SYNC_ALL_WINDOW_OPS' that will mimic the old behavior by synchronizing after every window operation with, again, the understanding that using this may result in the associated calls blocking for a relatively long period.
The deferred model also results in the window size and position getters not reporting false coordinates anymore, as they only forward what the window manager reports vs allowing applications to set arbitrary values, and fullscreen enter/leave events that were initiated via the window manager update the window state appropriately, where they didn't before.
Care was taken to ensure that order of operations is maintained, and that requests are not ignored or dropped. This does require some implicit internal synchronization in the various backends if many requests are made in a short period, as some state and behavior depends on other bits of state that need to be known at that particular point in time, but this isn't something that typical applications will hit, unless they are sending a lot of window state in a short time as the tests do.
The automated tests developed to test the previous behavior also resulted in previously undefined behavior being defined and normalized across platforms, particularly when it comes to the sizing and positioning of windows when they are in a fixed-size state, such as maximized or fullscreen. Size and position requests made when the window is not in a movable or resizable state will be deferred until it can be applied, so no requests are lost. These changes fix another long-standing issue with renderers recreating maximized windows, where the original non-maximized size was lost, resulting in the window being restored to the wrong size. All automated video tests pass across all platforms.
Overall, the "make a request/get an event" model better reflects how most windowing systems work, and some backends avoid spending significant time blocking while waiting for operations to complete.
This can be used to work around issues where the Apple GCController driver doesn't work for some controllers but there's no way to know which GCController maps to which IOKit device.
This patch adds an API for querying pressure-
sensitive pens, cf. SDL_pen.h:
- Enumerate all pens
- Get pen capabilities, names, GUIDs
- Distinguishes pens and erasers
- Distinguish attached and detached pens
- Pressure and tilt support
- Rotation, distance, throttle wheel support
(throttle wheel untested)
- Pen type and meta-information reporting
(partially tested)
Pen event reporting:
- Three new event structures: PenTip, PenMotion, and
PenButton
- Report location with sub-pixel precision
- Include axis and button status, is-eraser flag
Internal pen tracker, intended to be independent
of platform APIs, cf. SDL_pen_c.h:
- Track known pens
- Handle pen hotplugging
Automatic test:
- testautomation_pen.c
Other features:
- XInput2 implementation, incl. hotplugging
- Wayland implementation, incl. hotplugging
- Backward compatibility: pen events default to
emulating pens with mouse ID SDL_PEN_MOUSEID
- Can be toggled via SDL_HINT_PEN_NOT_MOUSE
- Test/demo program (testpen)
- Wacom pen feature identification by pen ID
Acknowledgements:
- Ping Cheng (Wacom) provided extensive feedback
on Wacom pen features and detection so that
hopefully untested Wacom devices have a
realistic chance of working out of the box.
This gives applications and binding systems a clearer view of what the hardware is so they can make intelligent decisions about how to present things to the user.
Gamepad mappings continue to use abxy for the face buttons for simplicity and compatibility with earlier versions of SDL, however the "SDL_GAMECONTROLLER_USE_BUTTON_LABELS" hint no longer has any effect.
Fixes https://github.com/libsdl-org/SDL/issues/6117
This lets apps optionally have a handful of callbacks for their entry points instead of a single main function. If used, the actual main/SDL_main/whatever entry point will be implemented in the single-header library SDL_main.h and the app will implement four separate functions:
First:
int SDL_AppInit(int argc, char **argv);
This will be called once before anything else. argc/argv work like they always do. If this returns 0, the app runs. If it returns < 0, the app calls SDL_AppQuit and terminates with an exit code that reports an error to the platform. If it returns > 0, the app calls SDL_AppQuit and terminates with an exit code that reports success to the platform. This function should not go into an infinite mainloop; it should do any one-time startup it requires and then return.
Then:
int SDL_AppIterate(void);
This is called over and over, possibly at the refresh rate of the display or some other metric that the platform dictates. This is where the heart of your app runs. It should return as quickly as reasonably possible, but it's not a "run one memcpy and that's all the time you have" sort of thing. The app should do any game updates, and render a frame of video. If it returns < 0, SDL will call SDL_AppQuit and terminate the process with an exit code that reports an error to the platform. If it returns > 0, the app calls SDL_AppQuit and terminates with an exit code that reports success to the platform. If it returns 0, then SDL_AppIterate will be called again at some regular frequency. The platform may choose to run this more or less (perhaps less in the background, etc), or it might just call this function in a loop as fast as possible. You do not check the event queue in this function (SDL_AppEvent exists for that).
Next:
int SDL_AppEvent(const SDL_Event *event);
This will be called once for each event pushed into the SDL queue. This may be called from any thread, and possibly in parallel to SDL_AppIterate. The fields in event do not need to be free'd (as you would normally need to do for SDL_EVENT_DROP_FILE, etc), and your app should not call SDL_PollEvent, SDL_PumpEvent, etc, as SDL will manage this for you. Return values are the same as from SDL_AppIterate(), so you can terminate in response to SDL_EVENT_QUIT, etc.
Finally:
void SDL_AppQuit(void);
This is called once before terminating the app--assuming the app isn't being forcibly killed or crashed--as a last chance to clean up. After this returns, SDL will call SDL_Quit so the app doesn't have to (but it's safe for the app to call it, too). Process termination proceeds as if the app returned normally from main(), so atexit handles will run, if your platform supports that.
The app does not implement SDL_main if using this. To turn this on, define SDL_MAIN_USE_CALLBACKS before including SDL_main.h. Defines like SDL_MAIN_HANDLED and SDL_MAIN_NOIMPL are also respected for callbacks, if the app wants to do some sort of magic main implementation thing.
In theory, on most platforms these can be implemented in the app itself, but this saves some #ifdefs in the app and lets everyone struggle less against some platforms, and might be more efficient in the long run, too.
On some platforms, it's possible this is the only reasonable way to go, but we haven't actually hit one that 100% requires it yet (but we will, if we want to write a RetroArch backend, for example).
Using the callback entry points works on every platform, because on platforms that don't require them, we can fake them with a simple loop in an internal implementation of the usual SDL_main.
The primary way we expect people to write SDL apps is with SDL_main, and this is not intended to replace it. If the app chooses to use this, it just removes some platform-specific details they might have to otherwise manage, and maybe removes a barrier to entry on some future platform.
Fixes#6785.
Reference PR #8247.
On some system like MacBook Pro Intel with AMD card, asking for the default device will always return the AMD GPU.
This is not an issue for 99% of the case when the renderer context is here to provide the maximum performance level like for game.
However, for video application using GPU for 1 quad and 1 texture, using the discrete GPU for that lead to an important power consumption (4 to 8W), heat increase, and fan noise.
With this patch, I successfully amend ffplay to only use the integrated GPU (i.e. the Intel one), instead of the discrete GPU (i.e. the AMD one).
Add aspect-correct output of scaled video modes and a hint to control this behavior (aspect, stretch, or none).
The Wayland spec states that fullscreen surfaces that do not cover the entire output shall be centered with the borders masked by the compositor, so no additional work is required aside from calculating the proper window dimensions.
The default is still 'stretch' mode, as some window managers as of this time (KDE and older versions of GNOME still found in LTS distros) don't behave according to the spec and present an unmasked window that is not centered, so it's not yet safe to change the default.
Consolidate the X11_WMCLASS and WAYLAND_WMCLASS envvars into one SDL_HINT_APP_ID hint. This hint serves the same purpose on both windowing systems to allow desktop compositors to identify and group windows together, as well as associate applications with their desktop settings and icons.
The common code for retrieving the value is now consolidated under core/unix/SDL_appid.c as it's common to *nix platforms, and the value is now retrieved at window creation time instead of being cached by the video driver at startup so that changes to the hint after video initialization and before window creation will be seen, as well as to accommodate cases where applications want to use different values for different windows.
By default SDL will only enumerate controllers, to reduce risk of hanging or crashing on devices with bad drivers and avoiding macOS keyboard capture permission prompts.
Change 8067023 by mikela:
Add SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED to SDL_RaiseWindow
- When set to false, this allows SDL_RaiseWindow to bring a chosen window to the top of the stack but not force input focus to it
Change 8067041 by mikela:
Rename SDL_HINT_WINDOW_NO_ACTIVATION_WHEN_SHOWN to SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN
We have gotten feedback that abstracting the coordinate system based on the display scale is unexpected and it is difficult to adapt existing applications to the proposed API.
The new approach is to provide the coordinate systems that people expect, but provide additional information that will help applications properly handle high DPI situations.
The concepts needed for high DPI support are documented in README-highdpi.md. An example of automatically adapting the content to display scale changes can be found in SDL_test_common.c, where auto_scale_content is checked.
Also, the SDL_WINDOW_ALLOW_HIGHDPI window flag has been replaced by the SDL_HINT_VIDEO_ENABLE_HIGH_PIXEL_DENSITY hint.
Fixes https://github.com/libsdl-org/SDL/issues/7709
- SDL_AudioCVT is gone, even internally.
- libsamplerate is gone (I suspect our resampler is finally Good Enough).
- Cleanups and improvements to audio conversion interfaces.
- SDL_AudioStream can change its input/output format/rate/channels on the fly!
This fixes rounding errors with coordinate scaling and gives more flexibility in the presentation, as well as making it easy to maintain device independent resolution as windows move between different pixel density displays.
By default when a renderer is created, it will match the window size so window coordinates and render coordinates are 1-1.
Mouse and touch events are no longer filtered to change their coordinates, instead you can call SDL_ConvertEventToRenderCoordinates() to explicitly map event coordinates into the rendering viewport.
SDL_RenderWindowToLogical() and SDL_RenderLogicalToWindow() have been renamed SDL_RenderCoordinatesFromWindow() and SDL_RenderCoordinatesToWindow() and take floating point coordinates in both directions.
The viewport, clipping state, and scale for render targets are now persistent and will remain set whenever they are active.
* SDL 3.0 is going to be high DPI aware and officially separates screen coordinates from client pixel area
The public APIs to disable high DPI support have been removed
Work in progress on https://github.com/libsdl-org/SDL/issues/7134
I ran this script in the include directory:
```sh
sed -i '' -e 's,#include "\(SDL.*\)",#include <SDL3/\1>,' *.h
```
I ran this script in the src directory:
```sh
for i in ../include/SDL3/SDL*.h
do hdr=$(basename $i)
if [ x"$(echo $hdr | egrep 'SDL_main|SDL_name|SDL_test|SDL_syswm|SDL_opengl|SDL_egl|SDL_vulkan')" != x ]; then
find . -type f -exec sed -i '' -e 's,#include "\('$hdr'\)",#include <SDL3/\1>,' {} \;
else
find . -type f -exec sed -i '' -e '/#include "'$hdr'"/d' {} \;
fi
done
```
Fixes https://github.com/libsdl-org/SDL/issues/6575
Max Maisel
Sam Lantinga
Frank Praznik
Ryan C. Gordon
Christoph Reichenbach
Jeremy Demeule
luzpaz
Sylvain
Alibek Omarov
Nikita Krapivin
Anonymous Maarten
Rudolf-Walter Kiss-Szakacs
Sasha Szpakowski