SDL/WhatsNew.txt


This is a list of major changes in SDL's version history.

---------------------------------------------------------------------------
3.2.0:
---------------------------------------------------------------------------

General:
* SDL headers should now be included as `#include <SDL3/SDL.h>`
* M_PI is no longer defined in SDL_stdinc.h, now the symbols SDL_PI_D (double) and SDL_PI_F (float) are available
* SDL_GetWindowWMInfo() returns a standard int result code instead of SDL_bool, and takes SDL_SYSWM_CURRENT_VERSION as a new third parameter
* The preprocessor symbol __MACOSX__ has been renamed __MACOS__
* The preprocessor symbol __IPHONEOS__ has been renamed __IOS__
* The following macros have been renamed:
    * RW_SEEK_CUR -> SDL_RW_SEEK_CUR
    * RW_SEEK_END -> SDL_RW_SEEK_END
    * RW_SEEK_SET -> SDL_RW_SEEK_SET
* SDL_FreeWAV has been removed and calls can be replaced with SDL_free
* The following functions have been renamed:
* Removed the following functions from the API, see docs/README-migration.md for details:
    * SDL_AudioInit()
    * SDL_AudioQuit()
    * SDL_CalculateGammaRamp()
    * SDL_CreateRGBSurface()
    * SDL_CreateRGBSurfaceFrom()
    * SDL_CreateRGBSurfaceWithFormat()
    * SDL_CreateRGBSurfaceWithFormatFrom()
    * SDL_GameControllerGetSensorDataWithTimestamp()
    * SDL_GetRevisionNumber()
    * SDL_GetWindowBrightness()
    * SDL_GetWindowGammaRamp()
    * SDL_RWFromFP()
    * SDL_SensorGetDataWithTimestamp()
    * SDL_SetWindowBrightness()
    * SDL_SetWindowGammaRamp()
* Removed the following hints from the API, see docs/README-migration.md for details:
    * SDL_HINT_IDLE_TIMER_DISABLED
    * SDL_HINT_VIDEO_X11_FORCE_EGL
    * SDL_HINT_VIDEO_X11_XINERAMA
    * SDL_HINT_VIDEO_X11_XVIDMODE
* Renamed hints 'SDL_HINT_VIDEODRIVER' and 'SDL_HINT_AUDIODRIVER' to 'SDL_HINT_VIDEO_DRIVER' and 'SDL_HINT_AUDIO_DRIVER'
* Renamed environment variables 'SDL_VIDEODRIVER' and 'SDL_AUDIODRIVER' to 'SDL_VIDEO_DRIVER' and 'SDL_AUDIO_DRIVER'
* SDL_stdinc.h no longer includes stdio.h, stdlib.h, etc., it only provides the SDL C runtime functionality
* Added SDL_CreateSurface() and SDL_CreateSurfaceFrom() which replace the SDL_CreateRGBSurface*(), and can also be used to create YUV surfaces
* Removed unused 'flags' parameter from SDL_ConvertSurface and SDL_ConvertSurfaceFormat
* Removed 'SDL_GL_CONTEXT_EGL' from OpenGL configuration attributes
* SDL_GetTicks() now returns a 64-bit value and the tick values should be directly compared instead of using the SDL_TICKS_PASSED macro
* Added SDL_GetTicksNS() to return the number of nanoseconds since the SDL library initialized
* Added SDL_DelayNS() to specify a delay in nanoseconds, to the highest precision the system will support
* The timestamp member of the SDL_Event structure is now in nanoseconds, filled in with the time the event was generated, or the time it was queued if that's not available
* The `SDL_DISPLAYEVENT_*` and `SDL_WINDOWEVENT_*` events have been moved to top level events
* Intrinsic headers are no longer included in the public SDL headers
* The following enums have been renamed:
    * KMOD_ALT => SDL_KMOD_ALT
    * KMOD_CAPS => SDL_KMOD_CAPS
    * KMOD_CTRL => SDL_KMOD_CTRL
    * KMOD_GUI => SDL_KMOD_GUI
    * KMOD_LALT => SDL_KMOD_LALT
    * KMOD_LCTRL => SDL_KMOD_LCTRL
    * KMOD_LGUI => SDL_KMOD_LGUI
    * KMOD_LSHIFT => SDL_KMOD_LSHIFT
    * KMOD_MODE => SDL_KMOD_MODE
    * KMOD_NONE => SDL_KMOD_NONE
    * KMOD_NUM => SDL_KMOD_NUM
    * KMOD_RALT => SDL_KMOD_RALT
    * KMOD_RCTRL => SDL_KMOD_RCTRL
    * KMOD_RESERVED => SDL_KMOD_RESERVED
    * KMOD_RGUI => SDL_KMOD_RGUI
    * KMOD_RSHIFT => SDL_KMOD_RSHIFT
    * KMOD_SCROLL => SDL_KMOD_SCROLL
    * KMOD_SHIFT => SDL_KMOD_SHIFT
Fixed crash if initialization of EGL failed but was tried again later. The internal function SDL_EGL_LoadLibrary() did not delete and remove a mostly uninitialized data structure if loading the library first failed. A later try to use EGL then skipped initialization and assumed it was previously successful because the data structure now already existed. This led to at least one crash in the internal function SDL_EGL_ChooseConfig() because a NULL pointer was dereferenced to make a call to eglBindAPI(). 2015-06-21 09:33:46 -06:00
			`This is a list of major changes in SDL's version history.`

Re-added the CRC to the joystick guid This is now used as a crc field in the mapping rather than directly in mapping guids, for better mapping compatibility between versions of SDL. Added SDL_GetJoystickGUIDInfo() to get device information encoded in a joystick GUID, so that mapping programs can clear the CRC from the GUID when generating mappings. sort_controllers.py has been updated to extract the CRC from mappings created by older mapping programs and convert it into the new crc field. It will also take the CRC into account when checking for duplicate mappings. Also regenerated the GUIDs for the PS2/PSP/Vita controller mappings, fixing https://github.com/libsdl-org/SDL/issues/6151 2022-08-27 19:55:55 -06:00			`---------------------------------------------------------------------------`
Updated SDL_syswm.h for SDL 3.0 * The header is no longer dependent on SDL build configuration * The structures are versioned separately from the rest of SDL * SDL_GetWindowWMInfo() now returns a standard result code and is passed the version expected by the application * Updated WhatsNew.txt and docs/README-migration.md with the first API changes in SDL 3.0 2022-11-23 14:33:48 -07:00			`3.2.0:`
Re-added the CRC to the joystick guid This is now used as a crc field in the mapping rather than directly in mapping guids, for better mapping compatibility between versions of SDL. Added SDL_GetJoystickGUIDInfo() to get device information encoded in a joystick GUID, so that mapping programs can clear the CRC from the GUID when generating mappings. sort_controllers.py has been updated to extract the CRC from mappings created by older mapping programs and convert it into the new crc field. It will also take the CRC into account when checking for duplicate mappings. Also regenerated the GUIDs for the PS2/PSP/Vita controller mappings, fixing https://github.com/libsdl-org/SDL/issues/6151 2022-08-27 19:55:55 -06:00			`---------------------------------------------------------------------------`

			`General:`
Switch header convention from `#include "SDL.h"` to `#include <SDL3/SDLh>` 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 2022-11-26 21:43:38 -07:00			* SDL headers should now be included as `#include <SDL3/SDL.h>`
renamed SDL PI constants to SDL_PI_D and SDL_PI_F. 2022-11-25 12:35:24 -07:00			`* M_PI is no longer defined in SDL_stdinc.h, now the symbols SDL_PI_D (double) and SDL_PI_F (float) are available`
Updated SDL_syswm.h for SDL 3.0 * The header is no longer dependent on SDL build configuration * The structures are versioned separately from the rest of SDL * SDL_GetWindowWMInfo() now returns a standard result code and is passed the version expected by the application * Updated WhatsNew.txt and docs/README-migration.md with the first API changes in SDL 3.0 2022-11-23 14:33:48 -07:00			`* SDL_GetWindowWMInfo() returns a standard int result code instead of SDL_bool, and takes SDL_SYSWM_CURRENT_VERSION as a new third parameter`
Use Apple's nomenclature for macOS and iOS Fixes https://github.com/libsdl-org/SDL/issues/6621 2022-11-25 17:00:06 -07:00			`* The preprocessor symbol __MACOSX__ has been renamed __MACOS__`
			`* The preprocessor symbol __IPHONEOS__ has been renamed __IOS__`
Used rename_api.py to add previously renamed symbols to SDL_oldnames.h 2022-12-23 16:08:30 -07:00			`* The following macros have been renamed:`
			`* RW_SEEK_CUR -> SDL_RW_SEEK_CUR`
			`* RW_SEEK_END -> SDL_RW_SEEK_END`
			`* RW_SEEK_SET -> SDL_RW_SEEK_SET`
Documentation cleanup 2022-12-27 06:28:18 -07:00			`* SDL_FreeWAV has been removed and calls can be replaced with SDL_free`
Added placeholder in the patch notes for renamed functions 2022-12-22 17:07:47 -07:00			`* The following functions have been renamed:`
Added a note to direct people to README-migration.md 2022-11-27 11:07:44 -07:00			`* Removed the following functions from the API, see docs/README-migration.md for details:`
Documentation cleanup 2022-12-27 06:28:18 -07:00			`* SDL_AudioInit()`
			`* SDL_AudioQuit()`
Clarified the migration path for SDL_CreateSurface() 2022-12-01 09:26:32 -07:00			`* SDL_CalculateGammaRamp()`
Removed SDL_SensorGetDataWithTimestamp() and SDL_GameControllerGetSensorDataWithTimestamp() 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. 2022-12-04 10:21:14 -07:00			`* SDL_CreateRGBSurface()`
			`* SDL_CreateRGBSurfaceFrom()`
			`* SDL_CreateRGBSurfaceWithFormat()`
			`* SDL_CreateRGBSurfaceWithFormatFrom()`
			`* SDL_GameControllerGetSensorDataWithTimestamp()`
Clarified the migration path for SDL_CreateSurface() 2022-12-01 09:26:32 -07:00			`* SDL_GetRevisionNumber()`
			`* SDL_GetWindowBrightness()`
			`* SDL_GetWindowGammaRamp()`
			`* SDL_RWFromFP()`
Removed SDL_SensorGetDataWithTimestamp() and SDL_GameControllerGetSensorDataWithTimestamp() 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. 2022-12-04 10:21:14 -07:00			`* SDL_SensorGetDataWithTimestamp()`
Clarified the migration path for SDL_CreateSurface() 2022-12-01 09:26:32 -07:00			`* SDL_SetWindowBrightness()`
			`* SDL_SetWindowGammaRamp()`
Added a note to direct people to README-migration.md 2022-11-27 11:07:44 -07:00			`* Removed the following hints from the API, see docs/README-migration.md for details:`
Clarified the migration path for SDL_CreateSurface() 2022-12-01 09:26:32 -07:00			`* SDL_HINT_IDLE_TIMER_DISABLED`
			`* SDL_HINT_VIDEO_X11_FORCE_EGL`
			`* SDL_HINT_VIDEO_X11_XINERAMA`
			`* SDL_HINT_VIDEO_X11_XVIDMODE`
Renamed AUDIODRIVER and VIDEODRIVER hint/env to AUDIO_DRIVER and VIDEO_DRIVER 2022-12-08 02:40:01 -07:00			`* Renamed hints 'SDL_HINT_VIDEODRIVER' and 'SDL_HINT_AUDIODRIVER' to 'SDL_HINT_VIDEO_DRIVER' and 'SDL_HINT_AUDIO_DRIVER'`
			`* Renamed environment variables 'SDL_VIDEODRIVER' and 'SDL_AUDIODRIVER' to 'SDL_VIDEO_DRIVER' and 'SDL_AUDIO_DRIVER'`
Remove SDL_config.h from the public headers The SDL headers are no longer dependent on the build configuration. Fixes https://github.com/libsdl-org/SDL/issues/6643 and https://github.com/libsdl-org/SDL/issues/6641 2022-11-26 02:41:46 -07:00			`* SDL_stdinc.h no longer includes stdio.h, stdlib.h, etc., it only provides the SDL C runtime functionality`
Enable creation of yuv SDL_Surfaces (#6735) 2022-12-02 13:53:48 -07:00			`* Added SDL_CreateSurface() and SDL_CreateSurfaceFrom() which replace the SDL_CreateRGBSurface*(), and can also be used to create YUV surfaces`
Remove depth field from SDL_CreateRGBSurfaceWithFormat and SDL_Create… (#6685) * 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 2022-11-29 10:40:09 -07:00			`* Removed unused 'flags' parameter from SDL_ConvertSurface and SDL_ConvertSurfaceFormat`
Remove SDL_GL_CONTEXT_EGL #6657 (#6683) 2022-12-01 15:53:37 -07:00			`* Removed 'SDL_GL_CONTEXT_EGL' from OpenGL configuration attributes`
Convert ticks to 64-bit, added nanosecond precision to the API Fixes https://github.com/libsdl-org/SDL/issues/5512 Fixes https://github.com/libsdl-org/SDL/issues/6731 2022-12-02 02:17:17 -07:00			`* SDL_GetTicks() now returns a 64-bit value and the tick values should be directly compared instead of using the SDL_TICKS_PASSED macro`
			`* Added SDL_GetTicksNS() to return the number of nanoseconds since the SDL library initialized`
			`* Added SDL_DelayNS() to specify a delay in nanoseconds, to the highest precision the system will support`
Pass the OS event timestamp for keyboard, mouse, and touch events where possible Currently implemented for Windows and Apple platforms 2022-12-02 10:03:13 -07:00			`* The timestamp member of the SDL_Event structure is now in nanoseconds, filled in with the time the event was generated, or the time it was queued if that's not available`
Made SDL_WINDOWEVENT_* and SDL_DISPLAYEVENT_* first class event types Fixes https://github.com/libsdl-org/SDL/issues/6772 2022-12-22 08:20:48 -07:00			* The `SDL_DISPLAYEVENT_` and `SDL_WINDOWEVENT_` events have been moved to top level events
Move intrinsic includes into a private header 2022-11-26 10:12:42 -07:00			`* Intrinsic headers are no longer included in the public SDL headers`
Prepend key modifier enum values with 'SDL_' 2022-12-23 18:52:46 -07:00			`* The following enums have been renamed:`
			`* KMOD_ALT => SDL_KMOD_ALT`
			`* KMOD_CAPS => SDL_KMOD_CAPS`
			`* KMOD_CTRL => SDL_KMOD_CTRL`
			`* KMOD_GUI => SDL_KMOD_GUI`
			`* KMOD_LALT => SDL_KMOD_LALT`
			`* KMOD_LCTRL => SDL_KMOD_LCTRL`
			`* KMOD_LGUI => SDL_KMOD_LGUI`
			`* KMOD_LSHIFT => SDL_KMOD_LSHIFT`
			`* KMOD_MODE => SDL_KMOD_MODE`
			`* KMOD_NONE => SDL_KMOD_NONE`
			`* KMOD_NUM => SDL_KMOD_NUM`
			`* KMOD_RALT => SDL_KMOD_RALT`
			`* KMOD_RCTRL => SDL_KMOD_RCTRL`
			`* KMOD_RESERVED => SDL_KMOD_RESERVED`
			`* KMOD_RGUI => SDL_KMOD_RGUI`
			`* KMOD_RSHIFT => SDL_KMOD_RSHIFT`
			`* KMOD_SCROLL => SDL_KMOD_SCROLL`
			`* KMOD_SHIFT => SDL_KMOD_SHIFT`