The flags parameter has been removed from SDL_CreateRenderer() and SDL_RENDERER_PRESENTVSYNC has been replaced with SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_NUMBER during window creation and SDL_PROP_RENDERER_VSYNC_NUMBER after renderer creation.
SDL_SetRenderVSync() now takes additional values besides 0 and 1.
The maximum texture size has been removed from SDL_RendererInfo, replaced with SDL_PROP_RENDERER_MAX_TEXTURE_SIZE_NUMBER.
The shorthand version of this function didn't allow specifying a controller name, which seems pretty important. It seems like anyone actually implementing a virtual joystick is going to want to use some of the extended functionality.
This allows applications to re-query the values if the system locale is changed during runtime, and better matches the other locale functions. A note is included in the documentation mentioning that this can be slow, as it has to call into OS functions.
Also allows for the removal of the init/quit time functions, as they are no longer needed.
This will provide a quick and easy way of clearing the error when a function succeeds, if we want to do that in a more widespread way.
For now we guarantee that SDL_Init() will never have an error set when it returns successfully.
Fixes https://github.com/libsdl-org/SDL/issues/8421
The "jump magic" codepath was never written, and would have involved a lot
of low-level and platform/processor/compiler specific work.
A better solution is for compilers to treat the function call in the jump
table functions as a tail call, which would effectively produce the same
result in a portable way.
Clang already has a way to do this that we could add later. But this wouldn't
need a separate "jump magic" section.
This was hardcoded to disabled, since building it in bloated the binary
massively for little gain (one could probably accomplish this same thing
with ltrace or something).
If we need it, we'll pull it out of revision control.
Adds functions to query the system's realtime clock, convert time intervals to/from a calendar date and time in either UTC or the local time, and perform time related calculations.
An SDL_Time type (a time interval represented in nanoseconds), and SDL_DateTime struct (broken down calendar date and time) were added to facilitate this functionality.
Querying the system time results in a value expressed in nanoseconds since the Unix epoch (Jan 1, 1970) in UTC +0000. Conversions to and from the various platform epochs and units are performed when required.
Any direct handling of timezones and DST were intentionally avoided. The offset from UTC is provided when converting from UTC to a local time by calculating the difference between the original UTC and the resulting local time, but no other timezone or DST information is used.
The preferred date formatting and 12/24 hour time for the system locale can be retrieved via global preferences.
Helper functions for obtaining the day of week or day or year for calendar date, and getting the number of days in a month in a given year are provided for convenience. These are simple, but useful for performing various time related calculations.
An automated test for time conversion is included, as is a simple standalone test to display the current system date and time onscreen along with a calendar, the rendering of which demonstrates the use of the utility functions (press up/down to increment or decrement the current month, and keys 1-5 to change the date and time formats).
- SDL_RWops is now an opaque struct.
- SDL_AllocRW is gone. If an app is creating a custom RWops, they pass the
function pointers to SDL_CreateRW(), which are stored internally.
- SDL_RWclose is gone, there is only SDL_DestroyRW(), which calls the
implementation's `->close` method before freeing other things.
- There is only one path to create and use RWops now, so we don't have to
worry about whether `->close` will call SDL_DestroyRW, or if this will
risk any Properties not being released, etc.
- SDL_RWFrom* still works as expected, for getting a RWops without having
to supply your own implementation. Objects from these functions are also
destroyed with SDL_DestroyRW.
- Lots of other cleanup and SDL3ization of the library code.
- Always use internal qsort and bsearch implementation.
- add "_r" reentrant versions.
The reasons for always using the internal versions is that the C runtime
versions' callbacks are not mark STDCALL, so we would have add bridge
functions for them anyhow, The C runtime qsort_r/qsort_s have different
orders of arguments on different platforms, and most importantly: qsort()
isn't a stable sort, and isn't guaranteed to give the same ordering for
two objects marked as equal by the callback...as such, Visual Studio and
glibc can give different sort results for the same data set...in this
sense, having one piece of code shared on all platforms makes sense here,
for reliabillity.
bsearch does not have a standard _r version at all, and suffers from the
same SDLCALL concern. Since the code is simple and we would have to work
around the C runtime, it's easier to just go with the built-in function
and remove all the CMake C runtime tests.
Fixes#9159.
This better reflects how HDR content is actually used, e.g. most content is in the SDR range, with specular highlights and bright details beyond the SDR range, in the HDR headroom.
This more closely matches how HDR is handled on Apple platforms, as EDR.
This also greatly simplifies application code which no longer has to think about color scaling. SDR content is rendered at the appropriate brightness automatically, and HDR content is scaled to the correct range for the display HDR headroom.
- Simplified public API, simplified backend interface.
- Camera device hotplug events.
- Thread code is split up so it backends that provide own threads can use it.
- Added "dummy" backend.
Note that CoreMedia (Apple) and Android backends need to be updated, as does
the testcamera app (testcameraminimal works).
Eventually we can re-add a fast path for that data down to the individual renderers. Setting color scale would still require converting to float, and most hardware accelerated renderers prefer to consume colors as float, so this requires some thought and performance testing.
Fixes https://github.com/libsdl-org/SDL/issues/9009
The renderer will always use the sRGB colorspace for drawing, and will default to the sRGB output colorspace. If you want blending in linear space and HDR support, you can select the scRGB output colorspace, which is supported by the direct3d11 and direct3d12
Modern C runtimes have well optimized memset and memcpy, so use those instead of dispatching into SDL's versions. In addition, some compilers can analyze memset and memcpy calls and directly turn them into optimized assembly.
Added support for getting the real controller info, as well as the function SDL_GetGamepadSteamHandle() to get the Steam Input API handle, from the virtual gamepads provided by Steam.
Also added an event SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED which is triggered when a controller's API handle changes, e.g. the controllers were reassigned slots in the Steam UI.
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 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
SDL_PollEvent(), SDL_WaitEvent(), and SDL_WaitEventTimeout() all return SDL_bool.
SDL_AddEventWatch() returns an int result code.
Also improved timeout accuracy in SDL_WaitEventTimeout()
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.
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
Also switched the D3D11 and D3D12 renderers to use real NV12 textures for NV12 data.
The combination of these two changes allows us to implement 0-copy video decode and playback for D3D11 in testffmpeg without any access to the renderer internals.
You can see it in action in testaudio by mousing over a logical device; it
will show a visualizer for the current PCM (whatever is currently being
recorded on a capture device, or whatever is being mixed for output on
playback devices).
Fixes#8122.
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 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
Add SDL_ShowWindowSystemMenu() to display the system-level menu for windows. Typically, this is done by right-clicking on the system provided window decorations, however, if an application is rendering its own client-side decorations, there is currently no way to display it. This menu is provided by the system and can provide privileged desktop functionality such as moving or pinning a window to a specific workspace or display, setting the always-on-top property, or taking screenshots. In many cases, there are no APIs which allow applications to perform these actions manually.
Implemented for Wayland via functionality provided by the xdg_toplevel protocol, Win32 via the undocumented message 0x313 (typically called WM_POPUPSYSTEMMENU), and X11 via the "_GTK_SHOW_WINDOW_MENU" atom (supported in GNOME and KDE).
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.
Now you open an audio device and attach streams, as planned, but each
open generates a new logical device. Each logical device has its own
streams that are managed as a group, but all streams on all logical
devices are mixed into a single buffer for a single OS-level open of
the physical device.
This allows multiple opens of a device that won't interfere with each
other and also clean up just what the opener assigned to their logical
device, so all their streams will go away on close but other opens will
continue to mix as they were.
More or less, this makes things work as expected at the app level, but
also gives them the power to group audio streams, and (once added) pause
them all at once, etc.
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.
The destination rectangle passed to SDL_BlitSurface() and SDL_BlitSurfaceScaled() is non-const and filled in with the final destination rectangle after clipping, and now documented as such.
Fixes https://github.com/libsdl-org/SDL/issues/7911
Also renamed SDL_GetDisplayOrientation() SDL_GetDisplayCurrentOrientation()
The natural orientation of the primary display is the frame of reference for accelerometer and gyro sensor readings.
Sam Lantinga
Frank Praznik
Miku AuahDark
Brick
Ryan C. Gordon
Petar Popovic
Susko3
Cameron Gutman
Ethan Lee
Semphris
Sylvain
Anonymous Maarten
Ozkan Sezer
Christoph Reichenbach
ilyas-taouaou
Anonymous Maarten
meyraud705
luzpaz