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.
Now it returns an array and optional count, to match other SDL3 APIs.
SDL_GetTouchName() was replaced with a function that takes an instance ID
instead of an index, too.
This uses the same `SDL_VerbNoun` format as the rest of SDL3, and also
adds stronger effort to invalidate cached state in the backend, so cooperation
improves with apps that are using lowlevel rendering APIs directly.
Fixes#367.
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
Almost nothing checks these return values, and there's no reason a valid
lock should fail to operate. The cases where a lock isn't valid (it's a
bogus pointer, it was previously destroyed, a thread is unlocking a lock it
doesn't own, etc) are undefined behavior and always were, and should be
treated as an application bug.
Reference Issue #8096.
The following objects now have properties that can be user modified:
* SDL_AudioStream
* SDL_Gamepad
* SDL_Joystick
* SDL_RWops
* SDL_Renderer
* SDL_Sensor
* SDL_Surface
* SDL_Texture
* SDL_Window
Wayland doesn't support programmatically setting the app icon, so note this restriction and specify that a desktop entry file that points to the desired icon image is required.
This is meant to offer a simplified API for people that are either migrating
directly from SDL2 with minimal effort or just want to make noise without
any of the fancy new API features.
Users of this API can just deal with a single SDL_AudioStream as their only
object/handle into the audio subsystem.
They are still allowed to open multiple devices (or open the same device
multiple times), but cannot change stream bindings on logical devices opened
through this function.
Destroying the single audio stream will also close the logical device behind
the scenes.
The sequence order of the four paddles is not obvious, with SDL and Xbox
controllers swapping the order of P2 and P3 relative to each other.
If we group them into left and right, then it becomes more obvious.
Signed-off-by: Simon McVittie <smcv@collabora.com>
The current status is stored in the SDL_rwops 'status' field to be able to determine whether a 0 return value is caused by end of file, an error, or a non-blocking source not being ready.
The functions to read sized datatypes now return SDL_bool so you can detect read errors.
Fixes https://github.com/libsdl-org/SDL/issues/6729
This rips up the entire SDL audio subsystem! While we still feed the audio device from a separate thread, the audio callback into the app is now gone a totally optional alternative.
Now the app will bind an SDL_AudioStream to a given device and feed data to it. As many streams as one likes can be bound to a device; SDL will mix them all into a single buffer and feed the device from there.
So not only does this function as a basic mixer, it also means that multiple device opens are handled seamlessly (so if you want to open the device for your game, but you also link to a library that provides VoIP and it wants to open the device separately, you don't have to worry about stepping on each other, or that the OS will fail to allow multiple opens of the same device, etc).
Merged from pull request #7704.
Fixes#7379.
Reference Issue #6889.
Reference Issue #6632.
Render targets are a core feature of SDL 3.0, so this flag has been removed.
The OpenGL ES renderer still doesn't support them, but we'll deal with that later.
Fixes https://github.com/libsdl-org/SDL/issues/8059
Also renamed most cases of SDL_GAMEPAD_TYPE_UNKNOWN to SDL_GAMEPAD_TYPE_STANDARD, and SDL_GetGamepadType() will return SDL_GAMEPAD_TYPE_UNKNOWN only if the gamepad is invalid.
Removing SDL_GAMEPAD_TYPE_VIRTUAL allows a virtual controller to emulate another gamepad type. The other controller types can be treated as generic controllers by applications without special glyph or functionality treatment.
Also renamed SDL_GetDisplayOrientation() SDL_GetDisplayCurrentOrientation()
The natural orientation of the primary display is the frame of reference for accelerometer and gyro sensor readings.
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.
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
It turns out that screen coordinates were confusing people, thinking that meant pixels, when instead they are virtual coordinates; device independent units defined as pixels scaled by the display scale. We'll use the term "points" for this going forward, to reduce confusion.
- 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!
It turns out there's a race condition on X11 where the window could be placed by the window manager while being placed by the application, so we need to have the initial position available at window creation.
This function wasn't consistently correct across platforms and devices.
If you want the UI scale factor, you can use display_scale in the structure returned by SDL_GetDesktopDisplayMode(). If you need an approximate DPI, you can multiply this value times 160 on iPhone and Android, and 96 on other platforms.
This makes it clear what the new versions are, and in the case of SDL_RenderDrawPoint() and SDL_RenderDrawLine(), the coccinelle script actually does the (float) casts for you.
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.
Rather than iterating over display modes using an index, there is a new function SDL_GetFullscreenDisplayModes() to get the list of available fullscreen modes on a display.
{
SDL_DisplayID display = SDL_GetPrimaryDisplay();
int num_modes = 0;
SDL_DisplayMode **modes = SDL_GetFullscreenDisplayModes(display, &num_modes);
if (modes) {
for (i = 0; i < num_modes; ++i) {
SDL_DisplayMode *mode = modes[i];
SDL_Log("Display %" SDL_PRIu32 " mode %d: %dx%d@%gHz, %d%% scale\n",
display, i, mode->pixel_w, mode->pixel_h, mode->refresh_rate, (int)(mode->display_scale * 100.0f));
}
SDL_free(modes);
}
}
SDL_GetDesktopDisplayMode() and SDL_GetCurrentDisplayMode() return pointers to display modes rather than filling in application memory.
Windows now have an explicit fullscreen mode that is set, using SDL_SetWindowFullscreenMode(). The fullscreen mode for a window can be queried with SDL_GetWindowFullscreenMode(), which returns a pointer to the mode, or NULL if the window will be fullscreen desktop. SDL_SetWindowFullscreen() just takes a boolean value, setting the correct fullscreen state based on the selected mode.
SDL_DisplayMode now includes the pixel size, the screen size and the relationship between the two. For example, a 4K display at 200% scale could have a pixel size of 3840x2160, a screen size of 1920x1080, and a display scale of 2.0.
This fixes the clang warning "Cast between pointer-to-function and pointer-to-object is an extension"
You can define SDL_FUNCTION_POINTER_IS_VOID_POINTER in your project to restore the previous behavior.
Fixes https://github.com/libsdl-org/SDL/issues/2866
You can enable and disable subsystems with SDL_ENABLE_SYSWM_*/SDL_DISABLE_SYSWM_* and you can disable the type forward declarations with SDL_DISABLE_SYSWM_*_TYPES
This simplifies the API and removes a level of API translation between the int variants of the functions and the float implementation
Fixes https://github.com/libsdl-org/SDL/issues/6656
Also cleaned up logic for whether we need to poll for events:
- We need to periodically poll for joysticks to handle hotplug.
- We need to frequently poll for joysticks and sensors when they're open so their state can be updated
Feedback from @icculus:
"IsTablet" uses "is" as a form of "to be" ...like, the actual question is of its nature.
The rest is just a superfluous word in the question and it flows as better English with if (RectEmpty) than if (IsRectEmpty)
Fixes https://github.com/libsdl-org/SDL/issues/6932
`SDL_QUERY`, `SDL_IGNORE`, `SDL_ENABLE`, and `SDL_DISABLE` have been removed.
SDL_EventState() has been replaced with SDL_SetEventEnabled()
SDL_GetEventState() has been replaced with SDL_EventEnabled()
SDL_GameControllerEventState has been replaced with SDL_SetGamepadEventsEnabled() and SDL_GamepadEventsEnabled()
SDL_JoystickEventState has been replaced with SDL_SetJoystickEventsEnabled() and SDL_JoystickEventsEnabled()
SDL_ShowCursor() has been split into three functions: SDL_ShowCursor(), SDL_HideCursor(), and SDL_CursorVisible()
Fixes https://github.com/libsdl-org/SDL/issues/6929
Instead of indexing into an internal list of devices which requires locking, we return a list of device IDs which can then be queried individually.
Reference: https://github.com/libsdl-org/SDL/issues/6889
and update README-visualc.md and README-gdk.md accordingly
Also moved src/main/windows/version.rc to src/core/windows/
and adjusted VS solutions, CMakeLists.txt and versioning scripts
in build-scripts/ accordingly.
This will eventually allow us to remove all of src/main/
# Conflicts:
# VisualC/tests/testgesture/testgesture.vcxproj
As the implementation requires C++, the user will have to include
SDL_main.h in a C++ source file (that needs to be compiled with /ZW).
It's ok to keep the standard main() implementation in plain C and use
an otherwise empty C++ source file for the SDL_main implementation part,
if both source files #include <SDL3/SDL_main.h>
Including SDL_main.h in a C source file will print a message at
compilation (when building for WinRT or possibly other not yet implemented
platforms that require C++ for main), to remind the user of also
including it in a .cpp source file. This message/warning can be disabled
with #define SDL_MAIN_NOIMPL before including SDL_main.h in the C file.
When including it in a .cpp file, there will be a compiler error with
helpful message if it's not compiled with /ZW
For this I renamend _SDL_MAIN_NOIMPL to SDL_MAIN_NOIMPL, because now it's
not for internal use only anymore, but also useful for users (that want
their main() function in a different file than the SDL_main implementation)
Add a project for the testdraw2.c test to the WinRT solution to at least
get some minimal testing on WinRT.
I won't add all tests because it's a lot of manual clicking per test,
but this should be better than nothing :)
Also adjusted iOS demo's includes to <SDL3/..> and explicit SDL_main.h
untested, I don't have Xcode (or a Mac, for that matter)
The xcode projects (for both Xcode-iOS/ and Xcode/) will probably
have to be adjusted for the SDL_main changes to work, but now at least
the iOS demo source should work as is :)
* N3DS: Make Sem waits cooperative friendly.
The 3DS has a cooperative threading model. Sleeping after TryWait and
WaitTimeout avoid starving other threads. It inccurs a runtime penalty,
but it's better than having to hard reset your console to recover from
a deadlock.
If you care about timestamps you'll also want to catch all of the sensor events instead of just polling the current state. For example, Nintendo Switch controllers generate 3 sensor events with distinct values for each polling interval.
* Remove depth field from SDL_CreateRGBSurfaceWithFormat and SDL_CreateRGBSurfaceWithFormatFrom
* Removed unused 'flags' parameter from SDL_CreateRGBSurface and SDL_CreateRGBSurfaceWithFormat
* Removed unused 'flags' parameter from SDL_ConvertSurface and SDL_ConvertSurfaceFormat
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
