Green-Sky/tomato
1
0
Fork 1
Code Issues Pull Requests 1 Actions Packages Projects Releases 1 Wiki Activity

Squashed 'external/sdl/SDL/' changes from 399bc709b7..0d7df16812

Browse Source 
0d7df16812 Timers are a required platform feature
518b070aa9 Fixed drop event coordinate conversion
3ca8cee874 Sync SDL3 wiki -> header
8bf74280e0 docs: Note SDL_UpdateWindowSurfaceRects can update beyond specified areas.
9408299bad Set the number of audio devices to 0 if audio hasn't been initialized
be0ba78c56 Convert the coordinates in drop events as well (thanks @Dragon-Baroque!)
e6c8872fdc Fixed bug #7614: Segmentation Fault in SDL_BlitSurface
ce0e0675de Fixed bug #8301 - Software renderer draws long lines incorrectly / SDL_RENDERLINEMETHOD_GEOMETRY
6e48d4532c Added raw input device handle for WM_INPUT mouse button handling
cf5e0637b5 Touchpads already have their right/left buttons swapped in raw input
fb2d7ed83e Restore window minimum and maximum size if it is recreated
915afae514 Remove force using one thread
64a3e2d17d Remove ps2_driver from workflow
464a41411e Sync SDL3 wiki -> header
4f3d4bd110 wayland: Add the ability to import and wrap external surfaces
99f6bcf504 Sync SDL3 wiki -> header
3a4ac15a27 Make Xbox GDK code public (and fix some GDK code rot) (#8844)
649556befa win32: Let windows manage the floating state unless explicitly overridden
d4a9748740 win32: Fix test failures
101f903bb1 testgeometry: allow to use arrows to move the triangle
4033a0a83b Prevent ASAN warning: like SDL_triangle.c:305:30: runtime error: left shift of negative value -672 (even if the value was correctly computed)
f0b9c7f0f0 Let Windows track floating window state
98be55894e Moved window state change handling from WM_WINDOWPOSCHANGING to WM_WINDOWPOSCHANGED
7efeb36131 Pass the frame DPI to WIN_AdjustWindowRectForHWND()
e4ee1cade7 Revert "SDL_windowsevents.c: fixed -Werror=unused-variable"
f8cce4ead4 SDL_windowsevents.c: fixed -Werror=unused-variable
277fded7ba Refactor AdjustWindowRectEx() into WIN_AdjustWindowRectForHWND()
312160935d Removed deprecated use of __IPHONEOS__ (thanks @Dragon-Baroque!)
483155bbf9 Fixed borderless window client area calculation
cf0d1d7234 Fixed ASAN warning, runtime error: left shift of 160 by 24 places cannot be represented in type 'int'
0c6b070761 Capture debug macros off by default
b5bc64aa55 Fixed pause key on Windows (thanks Mikhail!)
d766f68cb3 Fix compile error with XInputOnGameInput.h
ec2159d492 tests: Clean up the window creation properties in the Wayland custom surface example
9a77813df0 WinMain is specified by the Win32 API as having extern "C" linkage
6407e0cc37 Added attribution for GIP protocol handling (thanks @medusalix!)
3a219caf3d wayland: Restore accidentally removed line of code
ccae9c1ef6 Only initialize audio drivers that have been requested
590d0bec6f Revert "Make sure new windows have mouse and keyboard focus if there's no windowing system"
5948ea997f Make sure new windows have mouse and keyboard focus if there's no windowing system
05d18aab1c Sync SDL3 wiki -> header
4b6df89238 wayland: Add a property to allow creation of a wl_egl_window object even if OpenGL is not enabled
f7dd0f9491 wayland: Allow the creation of roleless window surfaces for custom application use
4417250d0d wayland: Remove the registry from the window properties
392796e49c wayland: Eliminate redundant protocol checks
82f2c4d581 render: Renamed SDL_GetTextureRenderer to SDL_GetRendererFromTexture.
95066ce2a0 Sync SDL3 wiki -> header
df438a3170 opengl: OpenGL renderers need to support texture target in properties.
8e7c0b34d7 test: If SDL_CreateRenderer() fails, say why
022ff075b9 test: When listing test-cases, say which ones are disabled
44adab7dfd Sync SDL3 wiki -> header
059fb560ba gamepad: Clarify range and direction of axes
4942027117 Sync SDL3 wiki -> header
e056f52f7d include: Remove string literals from properties documentation.
e8c595af5c Sync SDL3 wiki -> header
adef35b9ec include: Attempt to make new properties documentation wiki bridge friendly.
4ffec098b7 Sync SDL3 wiki -> header
9bc7cfc755 render: Added SDL_GetTextureRenderer().
7eae08cfc4 Removed SDL_GL_BindTexture() and SDL_GL_UnbindTexture()
4d5bffc323 Sync SDL3 wiki -> header
1a13dae219 Added constant definitions for SDL properties
3deefa6b43 Updated documentation for SDL_HINT_SHUTDOWN_DBUS_ON_QUIT
2348e8b6a2 Add hint to make SDL handle dbus_shutdown()
d3daba791a Don't try to send the PS third-party feature request to the Logitech G815 keyboard
014a63b4b5 Renamed ShowTextInput/HideTextInput to ShowScreenKeyboard/HideScreenKeyboard on Android
3a9a52fe6c updateKeyboard should use the SDL window's screen instead of the view window's screen, which may be nil.
e100992c17 Added mapping for the RX Gamepad, e.g. Pandora Box 7
139a0931a3 Fix memory barriers on ARMv5
21c80ac843 Added a practical example of confirm/cancel gamepad button handling
787a15f760 Fix Mac child windows that are created hidden showing if their parent window is shown
d6b1fc9576 Add SDL_MAC_REGISTER_ACTIVATION_HANDLERS hint to allow disabling the normal application startup/activation/deactivation handlers
7c5e694022 Ignore a new warning in Visual Studio 2022
73d02184d7 docs: Add Wayland to the SysWM migration example
c03c01e9b2 Make sure we get mouse events as soon as possible
5cbdeab799 Rename SDL_mslibc_x64.asm -> SDL_mslibc_x64.masm
ed62d6e7de cocoa: Set the titled flag on fullscreen space windows
b4b5dbd92f testcontroller.c: fixed warnings.
31851a50d2 Fixed dropping raw input because of mixing GetRawInputBuffer() and WM_INPUT handling
987744aae8 Fix Duplicated includes
2b369a14ab Fixed allocation and alignment of raw input buffers
bec1b8f849 Add basic rumble support to Steam Deck
8fe4a45edf Use GetRawInputBuffer() instead processing raw input one at a time
87b8f09657 Fixed warning: no previous prototype for function 'SDL_PrivateGetGamepadButtonFromString' [-Wmissing-prototypes]
c2951655ff Fixed warning: missing field 'window' initializer [-Wmissing-field-initializers]
5b3ee51c6c Updated copyright for 2024
a7b79c483c Remove unused 'window' variable from -[Cocoa_WindowListener windowWillExitFullScreen]
dd2d809407 AndroidShowToast: make OneShotTask members private final
44c2f344d6 Fixed build
2faae8457d The C standard defines a boolean expression as a signed integer value.
e3d50619f8 Fixed fatal error: SDL_pen.h: No such file or directory
dfe1a37bab Fixed error: 'static' is not at beginning of declaration [-Werror=old-style-declaration]
423b1fafcd Fixed warning C4047: 'function': '__x_ABI_CWindows_CGaming_CInput_CIRawGameController **' differs in levels of indirection from '__x_ABI_CWindows_CGaming_CInput_CIRawGameController *'
7681695875 Revert "Fixed signed/unsigned warnings with Visual Studio when comparing SDL_bool with boolean expressions"
8f94102b04 tests: Use unsigned format specifiers for printing flags
5d0c893723 wayland: Remove bitfield specifiers from boolean values
530b41d531 Fixed warnings in SDL_pen.c
9906d6d3bc Fixed warning C4244: '=': conversion from 'SDL_bool' to 'Uint8', possible loss of data
ebd7f9adbd Fixed warning C4245: 'initializing': conversion from 'int' to 'Uint32', signed/unsigned mismatch in SDL_video.c
dc1c27885e Fixed warning C4389: '!=': signed/unsigned mismatch in SDL_blit.c
e813c72b3c Fixed warning C4245: 'return': conversion from 'int' to 'SDL_JoystickID', signed/unsigned mismatch
dce626f469 Fixed warning C4244: 'function': conversion from 'int' to 'Uint16', possible loss of data
7f376277e5 Fixed warning C4244: 'initializing': conversion from 'SDL_bool' to 'Uint8', possible loss of data
61db102da9 Fixed signed/unsigned warnings with Visual Studio when comparing SDL_bool with boolean expressions
d71454da17 Store the surface properties in the reserved pointer of a surface
b6a92c113f wayland: Don't apply old libdecor window dimensions
39e24e52c8 Fixed example of creating a window with properties
dc450ba908 Added an example of creating a window with position
ce4fe32ce3 Added documentation for getting the X11 display from an SDL window
327d31a5d9 Added documentation for getting the NSWindow from an SDL window
3976bbef2a Added documentation for getting the X11 window from an SDL window
ffb8515c21 Use the Valve code name for the Steam Deck controller
43c40d30a2 Added comment for the BDA Pro Ex controller
61704b5862 Removed an assertion it's possible to hit
c24b33d8d9 Fixed building with older Windows SDK
70ba3f2830 Report the D-Pad for HIDAPI gamepads as a hat
ce329d60e4 Added support for alpha blending using palette alpha
9c3e831e33 uikit: Send fullscreen enter/leave events
5df3eac925 Sync SDL3 wiki -> header
0dfdf1f3f2 Fixed crash if joystick functions are passed a NULL joystick
4ce935b910 Fix static build with libdecor 0.2.0
5d6d149862 Allow passing in `extrainfo` value to `GetMouseMessageSource()`
e0df963ef0 Fix wrong bit count in comment
c2a55cd2c5 Add missing `(void)` in functions params
a3c8f2f6cb Consolidate mouse-touch event checking logic
d747daf03d Use correct touch check flag
a961066d0b Add basic touch/finger support to `testpen.c`
a3b5eb07b2 Removed extern "C" linkage from main() declaration
50e309bb17 Include SDL_events.h in SDL_main.h
cae657140c Add Access Controller
74418e1aa8 Made the cursor list check a compile time assert instead of a runtime one
d6fb0d91d8 Added testpen to the Visual Studio solution
bbdd41f287 Fix windows touch using wrong axis for normalisation
a28ac29aa0 Add missing cursor types
6daf2e943f Try SDL_UDEV_deviceclass to detect joysticks even if in a container
1bf78ed544 We get a resize event when the view enters fullscreen mode on iOS
e3b5999bb4 Use the application requested size to determine automatic orientation on iOS
278e3f9184 Whoops, fixed setting fullscreen flag
69e60e0f1b Fixed setting fullscreen mode on iOS
0e5ea3cc4b Fixed infinite recursion when adding an accelerometer as joystick on iOS
c3d84c3342 Record the initial input report mode and only restore simple mode if that's what we started with
10a8b750a0 Use common generic syscond for platforms with no cond implementation
4914e5bb78 PS2 use WaitSemaEx for waiting for semaphore with timeout
bb0e0ae080 Added a runtime check for BLUETOOTH_CONNECT in addition to BLUETOOTH (thanks @perepujal!)
312f98c2a1 Make sure the string is terminated, fixed invalid read in SDL_PrivateParseGamepadConfigString()
199f7cc3b1 x11: Ignore border extents when the border hint is unset
07e9603398 Sync SDL3 wiki -> header
ffd82fb7c4 Add scaleMode to SDL_SoftStretch(), remove SDL_SoftStretchLinear().
5dba04b29b Remove SDL_{Set,Get}SurfaceScale(). Add Scale parameter to SDL_BlitSurfaceScaled() and SDL_BlitSurfaceScaledUnchecked() (see #8732)
e66896406d cocoa: Set appropriate flags on fullscreen spaces windows
57fcb9044c video: Remove more assumptions about window state in the video layer
cb90653695 win32: use USER_DEFAULT_SCREEN_DPI instead of explicit 96 value
a2e05480d6 Use crc16 return value when calculating GUID
2ad50e9675 Make the SDL3 surface ABI compatible with SDL2
f72d6a7fd9 Use more verbose names for properties, to match upcoming public property names
1f1ee6f77c Use the original manufacturer and product strings for the joystick CRC
4bb5e1f0f9 Added migration notes for migrating Steam Input support from SDL2 to SDL3
56f111dffc Fix compilation / same as sdl2-compat
72c366bf3d Fixed whitespace
3152b98e87 win32: minor fixup in WIN_UpdateKeymap()
2c4360ce8f Sync SDL3 wiki -> header
c981a597dc Added Steam Input API support for game controllers
a8f4f40d08 Sync more Steam Controller header definitions for the Steam Deck
e6e54b22c8 Ignore all surface comparison output files in the testautomation directory
9d13be743b Make sure we're rendering whenever the activity might be visible, even if we don't have focus.
69ec0322d3 win32: Make leaving fullscreen when the window already isn't fullscreen a no-op
8f79e0b7f8 win32: Fix high-DPI debug logging
a4496f7dcf Update doc: SDL_SoftStretch() and SDL_SoftStretchLinear() #8667
43309d38ed joystick: Extract 0x02a9 and 0x0291 PIDs into separate defines.
84a0d5f623 Added SDL_SetSurfaceScaleMode() and SDL_GetSurfaceScaleMode() to control scale mode using SDL_BlitSurfaceScaled()
4d5949dcf6 Added a controller name for the Steam virtual gamepad
695846f2ed Pass through the name of the controller for the XInput mapping
1745289b1b x11: Don't move the window when restoring and ensure that resize and position events are sent when entering or leaving fullscreen
08a7ca4d53 XInput: Use XInputGetCapabilitiesEx instead of fragile GuessXInputDevice
7f75178908 Verify that the %p format specifier works for 64-bit pointers
72b7acfe8a Don't create a TLS error buffer if we're just clearing the error
240e7747c8 Fix #8702: Add SDL_hidapi_steamdeck.c to Xcode target
b937c54b66 win32: Set all size and position variables for external windows
8c285828e5 Fixed return value for SDL_UDEV_AddCallback()
cbf9012c74 Fixed build
5547007915 Added test for inverted cursor
0ab13f2498 joystick: fixup for Wireless Xbox 360 Controller VID/PID detection in WGI backend.
627d134b9e Add support for monochrome cursors with inverted pixels under Windows.
21879faf48 wayland: Handle mouse focus when receiving touch events
58a5f5cbe8 Allow sendCommand() to be overridden by derived classes
e6d8ef1a5b Revert "Back out Steam virtual gamepad changes"
b0e7b7db6f Don't unload graphics libraries until after the window has been destroyed.
69288038ed Refactor away some additional integer types.
f3048e3cd2 Add new file to vcxproj files.
5a21febecb Add new steam deck HIDAPI controller to controller database.
67d44c1017 Disable lizard mode while steam deck HID device is opened.
6dd6827343 Translate steam deck HID reports to SDL events.
94f621e030 Implement steam deck HIDAPI initialization.
c1a7d0f96e Add steam deck detection and HIDAPI driver scaffold.
0baee3e676 Reversed test to be easier to read, more efficient, and match other code
bddbd1e317 cocoa: Check the resizable flag along with zoomed status when resizing
835c733f4d video: Only sync when programmatically entering/exiting fullscreen
c790572674 Use existing XUSB driver software PID 0x02a1 instead of PID 0x02fe
581d1cab25 You should call present when using a software renderer as well.
5173b0c2cc Make built-in joystick device lists extendable by using hints
34eb24ebc4 Back out Steam virtual gamepad changes
7529d25b2b Use the Steam virtual gamepad slot as the gamepad player index
445f08a0fb Print the gamepad player index when opening a gamepad
17723381da Sort Steam virtual gamepads by Steam controller slot
f3d8a2def5 audio: Fixed resource leak in unlikely failure case during device add.
63ae84e140 x11: Improve sync algorithm
7e5511d3cd x11: Move unrelated variables out of XFixes #ifdef
3c5e9e6112 We can wait up to 500ms in onNativeSurfaceDestroyed(), so wait at least that long in onDestroy()
53cda988f4 Clear any errors from a previous run
a197efe3a7 pen: fix leak caused by pen subsystem
fbb0914b78 wayland+x11: free system cursors when quiting video
7484d02a2e testshape: use SDL_test to create multiple windows
20250aecc5 Sync SDL3 wiki -> header
4fd778119b video: Implement asynchronous windowing
ace385a134 Revert "Fixed warning C33010: Unchecked lower bound for enum scancode used as index."
e482f00a17 SDL_string.c (SDL_vsscanf): fix gcc build
f00ecf5f19 Fixed building with older Windows SDK
7ca43995a1 Fixed warning C4028: formal parameter 1 different from declaration
aab7432f5f Fixed analyze warnings for SDL_dynapi_procs.h
c484140f56 Fixed warning C33010: Unchecked lower bound for enum scancode used as index.
02a116217d Fixed Arithmetic overflow: Using operator '-' on a 4 byte value and then casting the result to a 8 byte value. Cast the value to the wider type before calling operator '-' to avoid overflow (io.2).
91da942b33 Fixed warning C28251: Inconsistent annotation for 'SDL_RWvprintf_REAL': this instance has no annotations.
b8840801cc Fixed analyze warnings in SDL_xinputhaptic.c
8e0d728c67 Fixed warning C26451: Arithmetic overflow: Using operator '-' on a 4 byte value and then casting the result to a 8 byte value. Cast the value to the wider type before calling operator '-' to avoid overflow (io.2).
6a736d7766 Fixed warning C6340: Mismatch on sign: 'unsigned char' passed as _Param_(2) when some signed type is required in call to 'SDL_SetError_REAL'.
1fcc75ba81 Fixed warning C6340: Mismatch on sign: 'unsigned char' passed as _Param_(4) when some signed type is required in call to 'SDL_snprintf_REAL'.
7f2e16db8b Fixed warning C6340: Mismatch on sign: 'const unsigned short' passed as _Param_(2) when some signed type is required in call to 'SDL_SetError_REAL'.
163de8e697 Fixed warning C6001: Using uninitialized memory 'rdi'.
e29393e407 Fixed warning C6001: Using uninitialized memory 'devName'.
0f34ca2e71 Fixed analyze warnings in SDL_xinputjoystick.c
2b5c7db645 Fixed analyze warnings in SDL_render_d3d12.c
a28769759b Fixed warning C26052: Potentially unconstrained access using expression '(signed char *)info'
6ee34380f4 Fixed warning C6011: Dereferencing NULL pointer 'viewport'.
230581f4a8 Fixed warning C26451: Arithmetic overflow: Using operator '+' on a 4 byte value and then casting the result to a 8 byte value. Cast the value to the wider type before calling operator '+' to avoid overflow (io.2).
3775d9be4b Fixed warning C28251: Inconsistent annotation for 'SDL_LogMessageV_REAL': this instance has no annotations.
b512182222 Fixed warning C6340: Mismatch on sign: 'unsigned int' passed as _Param_(2) when some signed type is required in call to 'SDL_SetError_REAL'.
8a82f7e837 Fixed warning C33005: VARIANT '&valueX' was provided as an _In_ or _InOut_ parameter but was not initialized
fda039e6f8 Fixed analyzer warnings for SDL_string.c
22f44aefe7 Fixed warning C6340: Mismatch on sign: 'int' passed as _Param_(3) when some unsigned type is required in call to 'SDL_sscanf_REAL'.
eab2d97d07 Fixed warning C26451: Arithmetic overflow: Using operator '*' on a 4 byte value and then casting the result to a 8 byte value. Cast the value to the wider type before calling operator '*' to avoid overflow (io.2).
41bfcad5d7 Fixed warning C6340: Mismatch on sign: 'unsigned short' passed as _Param_(2) when some signed type is required in call to 'SDL_SetError_REAL'.
54dc73aa88 Fixed warning C6386: Buffer overrun while writing to 'palette_saved_alpha':  the writable size is 'sizeof(Uint8)*((palette_saved_alpha_ncolors))' bytes, but '2' bytes might be written.
0dad56354c Fixed warning C6326: Potential comparison of a constant with another constant.
c9b243fb56 Fixed warning C6263: Using _alloca in a loop: this can quickly overflow stack.
4ccc53edfe Fixed warning C6011: Dereferencing NULL pointer 'display'.
3db4695ac7 warning C6340: Mismatch on sign: 'unsigned int' passed as _Param_(3) when some signed type is required in call to 'SDL_LogDebug_REAL'.
c7d81d936a Fixed warning C6031: Return value ignored: 'GetKeyboardState'.
69b9d44bdc Fixed warning C26451: Arithmetic overflow: Using operator '-' on a 4 byte value and then casting the result to a 8 byte value. Cast the value to the wider type before calling operator '-' to avoid overflow (io.2).
a9b87ee201 Fixed warning C28159: Consider using 'GetTickCount64' instead of 'GetTickCount'. Reason: GetTickCount overflows roughly every 49 days.  Code that does not take that into account can loop indefinitely.  GetTickCount64 operates on 64 bit values and does not have that problem
21f273ecc7 Fixed warning C6255: _alloca indicates failure by raising a stack overflow exception. Consider using _malloca instead.
0c4cb3d153 Fixed warning C26451: Arithmetic overflow: Using operator '<<' on a 4 byte value and then casting the result to a 8 byte value. Cast the value to the wider type before calling operator '<<' to avoid overflow (io.2).
06f8f9a891 Fixed warning C6326: Potential comparison of a constant with another constant.
3e54061fa8 Fixed warning C6011: Dereferencing NULL pointer 'SDL_disabled_events[hi]'.
226f8fde09 Fixed warning C28182: Dereferencing NULL pointer. 'streams[j]' contains the same NULL value as 'stream' did.
fe6b3ab0b0 Fixed warning C6031: Return value ignored: 'CLSIDFromString'.
f3b0149756 Fixed warning C26451: Arithmetic overflow: Using operator '*' on a 4 byte value and then casting the result to a 8 byte value. Cast the value to the wider type before calling operator '*' to avoid overflow (io.2).
6cfce101fb Don't call the property cleanup function if setting the property fails
14380ec48a Fixed signed/unsigned comparison warning
ac0751a652 Added SDL_strnstr()
7c71e72193 SDL_render: Call InvalidateCachedState to initialise some of driverdata values (eg '*_dirty' to 1). At the earliest place, immediatly after driverdata is set. (Doing it in SDL_render.c, after creation, would be too late, because there're renderers that already use/change those values in the CreateRender() function).
058213366b Make sure we use alpha of 0 when clearing a transparent window with no content
ecd56bb8f0 Removed SDL_GetErrorMsg(), trivially implemented in application code
66e532fa61 Handle out of memory errors without any allocation
579681a372 fixed SDL_SCANCODE_LEFT array position in scancodes_windows.h
675423f096 Sync SDL3 wiki -> header
744a29b88f WGI: Cleanup code a bit (#8647)
e4582e6edc Sync SDL3 wiki -> header
df0fd55891 wikiheaders.pl: README files are no longer in Windows endline format.
1072b6e86e docs: fixed typo
f184dea16c uikit: Patched to compile.
447b508a77 error: SDL's allocators now call SDL_OutOfMemory on error.
70b65d4170 cocoa: Resync modifier keypressed on NSEventTypeFlagsChanged event.
d1b831e232 include: Clarified documentation for two functions.
daa38dc793 touch: Replace GetNumTouchDevices/GetTouchDevice with a single function.
dd47da8a5c gamepad: Replace GetNumMappings/GetMappingByIndex with a single function.
dfee3f9e92 render: Replaced SDL_RenderFlush with SDL_FlushRenderer.
eef5c53668 docs: Moved CREDITS and INSTALL to markdown format.
f32575dfab docs: Convert everything to Unix-style endlines.
c5daf8adb1 testcontroller: Don't query the mapping list until after they are available.
df05d5eff4 Fix scroll wheel handling in testmouse
63d4bd4e57 SDL_SendKeyboardText: remove workaround from 1e12d7c, fix use of iscntrl
fea6e7afb1 cmake: copy sources to binary directory in separate target
9faa7977bd UWP: Add support for supplementary Unicode characters input
7b628ea4d5 Win32: Simplify Unicode text input code
411c70abb1 Fix the target membership of SDL_pen.h (thanks kanjitalk755!)
3e6513c773 document the purpose of SDL_SetTextInputRect
1e12d7cfb6 Make sure we don't pass UTF-8 to SDL_iscntrl()
9a206adbee UWP: Use Windows.UI.Core.CoreDispatcher.AcceleratorKeyActivated event for keyboard
309ea2d5f9 UWP: Simplify Win32 scan code to SDL scan code mapping
acc5bb89f8 [Win32] Better keyboard button mapping to SDL scan codes
6b28065e9e Reformat Win32 scan code table
7e86b6aef2 Win32: Fix keymap for keyboard layouts that can print UTF-16 surrogates and ligatures
08c6ac1b16 test: SDLTest_PrintEvent now reports key event mod state.
571e9796b9 Fixed the GameCube HIDAPI controller mapping
dd984dcd9f Removed HIDAPI controller mappings
3817f5126e cocoa: Use `-[NSApplicationDelegate applicationSupportsSecureRestorableState]`.
c5b0ff77d7 test: testwm2 now displays keyboard mod state.
5772e00c3f cmake: disable oss by default on OpenBSD, not FreeBSD
ceac93ade2 Set framebuffer_srgb_capable to the actual value obtained (#8634)
ed3fad1880 cmake: disable oss by default on Linux, NetBSD and FreeBSD
6bb40f1d8d SDL_VideoCapture: allow add/remove device at runtime on linux
f0e47f8ee0 Added support for the NACON Revolution 5 Pro controller
2f806c89b5 initial import of hidapi netbsd uhid native backend from mainstream
1b284cd415 X11 pen detection: fix misclassification due to improper init
c4ca64deaf ci: do 'brew update' & don't run dependent checks on installed things
d486de6349 cmake: fixed iconv detection test program
42a8139fd6 render: Clip bresenham lines against a real viewport thing.
4a40a272bd render: Patched to compile.
983f178b7d render: Clip lines before Bresenham algorithm generates points.
db7f6425d0 rect: Avoid numeric overflow on massive lines in SDL_IntersectRectAndLine.
e548044a82 ci: add NetBSD to test matrix
dd5b8db3a6 SDL_hidapi requires libusb >= 1.0.16
6ba90f7775 render: Batching is always enabled now!
b24d6bd59a opengl: Creating a texture trashes the cached `texturing` state, fix it.
dcf04559db render: GL-based renderers should treat adaptive vsync as vsync being enabled.
74a2542564 x11: Deal with difference in GLX_EXT_swap_control_tear behavior.
08fac5b1b2 SDL_PenModifyForWacomID: return zero as axis_flags upon failure.
aaba01aee4 hidapi: syncing with mainstream:
5730eb67f0 add HAVE_GCC_DIAGNOSTIC_PRAGMA to SDL_internal.h, use it
42c8366fdc revise iconv detection:
a45b371de0 cmake: create and install SDL3::Jar target for Android
53544cabaa psp: fix copy/paste error from SDL2 in PSP_VideoQuit().
6cde96f9a0 psp: Hook up event subsystem init/quit.
e9659f5738 Removed some function declarations that don't actually exist.
3264e64738 SDL_RunApp: Make sure argc/argv are stable if the caller didn't define them.
eca79e38db Removed test shape images
81fc7ded78 Removed the window shape API for SDL 3.0
45938bbfa5 Corrected comment
059e550e98 Fix 3DS Analog Values (#8581)
dbf14df80f Fix joysticks returning invalid device IDs
d2db3f3993 ci: cache android ndk archive
d6291d4d42 alloca: use alloca from <stdlib.h> on NetBSD
f26a93211f SDL_bsdjoystick: fix -Wundef warning on FreeBSD
d1def7f033 cmake: add openbsd wscons sources to build, if supported
86d77bbcc5 kmsdrm: restrict KMSDRM_ReleaseVT/KMSDRM_AcquireVT to SDL_INPUT_LINUXEV
94ad1a4ae4 SDL_bsdjoystick.c: fix -Wundef warning.
e761770c24 No, this wasn't right
b7d7e54895 Fixed uninitialized variable
119e02f314 Always use 'm' for controllers provided by the MFI joystick driver
75df4cc5c2 Don't tickle PS4 Bluetooth controllers in simple mode
0d431015bf Extract BMP magic into separate define
0413f6fc49 Use SDL_iscntrl() call instead of manual code that is doing the same (#8593)
fd91178d7f Make size cursors be double arrows on Wayland
5e9b0820f3 Add cursors for X11/Wayland window resizing
91e122316c Use SDL_small_alloc() instead of SDL_stack_alloc() in CreateMaskBitmap()
b76f8de298 Hit testing tweaks for X11 and Wayland (#8582)
5b1c68c2f3 testshader: Don't make local variables with the same name as GL entry points.
30a2291d59 Fixed compatibility with sdl2-compat (thanks @sezero!)
49d58bc73a Cleanup WIN_CreateCursor() code a bit
4722269fb6 tests: Print window occluded log events
5db781cc3d Use the correct pixel formats for OpenGL ES on big endian
05e7dcf8f8 Support returning <8bpp surfaces in SDL_LoadBMP_RW
773ec1cfcb Extend blitting support for all <8bpp formats
753bbd199e Add SDL_PIXELFORMAT_INDEX2LSB and SDL_PIXELFORMAT_INDEX2MSB
fda69e5e79 Test both MSB and LSB indexed surfaces in testautomation
39870031d1 use format string attributes for functions accepting va_list params, too
666301f9f9 Fixed build with older macOS SDK
238987df3b Always use physicalInputProfile on OS versions that support it
e424dcca4b More fixing the build with older macOS SDKs
4ebb0c6dac Revert "Fixed build"
7abacc9f9f Fixed build
ac1f896f89 Fixed building with older macOS SDK
8043dad369 Fixed build warning
5c8c3931f2 Removed outdated information about SDL_GetWindowWMInfo()
e0d0d140b2 Fixed SDL_GetWindowWMInfo() code example
f61c0f3dc1 SDL_HINT_TV_REMOTE_AS_JOYSTICK should only affect Siri Remotes on Apple TV
51fc134cad Added support for the second generation Siri Remote on Apple TV
bfba9de43a Revert "Map Siri Remote touchpad to D-Pad for consistency with physicalInputProfile mapping"
f2c12fe5f3 Removed TODO.txt
d4448fe3d2 Update virtual joystick test now that we're just using abxy for mappings, for compatibility
f40f272107 Fixed build
34bdd321bf Improved navigation while setting up controller mapping
57e5c7f6ee We'll just use the legacy names for face buttons in the mappings
051ed397d1 Removed testautomation_syswm.c from the Xcode project
fb08c22abf Disable controller state debug messages
2999634f29 Map Siri Remote touchpad to D-Pad for consistency with physicalInputProfile mapping
2ff9255f29 Print the GUID for controllers that don't have a mapping
64939d3586 Switch the menu button on the Apple TV remote to the B button to match UI guidelines
0fe5713964 Improved GCController handling on Apple platforms
aaf54b09a1 Revert "Cleanup WIN_CreateCursor() code a bit"
e923a458ea audio: Protect against race conditions when closing a physical device.
8fa0746d4a audio: Fix postmix state when migrating to new default devices.
078995bbe0 x11: Set the skip taskbar and skip pager atoms on utility windows
a58af6d0d1 wasapi: Reference devices when proxying to management thread.
34392db9c3 Fixed IOS_SupportedHIDDevice() returning SDL_FALSE before initialization
708f18d49e Added SDL_HINT_JOYSTICK_IOKIT and SDL_HINT_JOYSTICK_MFI to control whether the IOKit and GCController drivers should be used for joystick support.
bd4966999b Replacing SDL_SCANCODE_AUDIOMUTE by SDL_SCANCODE_MUTE on Windows
15504da0b8 Fixed mouse wheel scrolling direction on iOS
f5600fd9f4 Fall back to using the physical profile for Apple controllers if they don't match a standard profile
924de4df48 Enable transparent windows when using the D3D11 renderer
1c64366b80 Added SDL_CreateRendererWithProperties() and SDL_CreateTextureWithProperties()
7203641597 Note that the SDL window properties are read-only
e0c45c6c98 Renamed SDL_WINDOW_FOREIGN to SDL_WINDOW_EXTERNAL
229b7b9d50 SDL_CreateWindowWithPosition() and SDL_CreateWindowFrom() have been replaced with SDL_CreateWindowWithProperties()
2c1fbe1967 Revert "Check to make sure the Windows joystick device has buttons and axes"
edd044e901 Fixed the ROG PUGIO II showing up as a game controller
861b1ebd12 properties: Use a mutex instead of an RWLock to guard the hash table
dd8ab67bd9 Sync wiki -> headers.
91460fc13d include: Fixed up documentation in SDL_pen.h
876c97454a Cleanup WIN_CreateCursor() code a bit
8766aa39d6 Sync wiki -> headers.
e5ffd6d8eb include: Removed `\link` and `\endlink` Doxygen tags.
1c4723ac66 SDL_CreateWindowFrom() now takes a set of properties that describe the native window and options.
6afae6681b Allow casting properties of different types
bd269b0f41 Added SDL_SetBooleanProperty() and SDL_GetBooleanProperty()
c47ac5b2df include: Fixed copy/paste error
0efb3d90e0 audio: removed a fixed FIXME comment.
69cae07cc1 cpuinfo: Fix detection of physical memory above 2GB on NetBSD
45fc828c95 move SDL_EVENT_WINDOW_PEN_ENTER and SDL_EVENT_WINDOW_PEN_LEAVE down
0907f345cb Added property types: pointer, string, number, float
7c80ac6df7 API for pressure-sensitive pens + XInput2/Wayland
d3e43668d0 Revert "Sync SDL3 wiki -> header"
43571769f1 Sync SDL3 wiki -> header
843873626c Handle window resizing on the render thread in D3D11 and D3D12
f66f61de01 Fixed missing "0" in the button list
04b6b2979f Re-add SDL_assert() with non boolean ptr syntax (#8530)
b374105975 Replaced SDL_GetTextureDXGIResource() with texture properties
09d1e9defb Only update the battery status for Bluetooth Switch Pro controllers
87794d03ad Added shortened name for "Nintendo Co., Ltd."
fbb6934905 Added support for the Dragonrise GameCube adapter with VID 0x1843
d98e1bdfe1 Use the standard gamepad type for Switch Pro controllers using the GameCube form factor
a5a47d3bee Fixed crash if there is no controller mapping
312faf9305 Updated documentation for the controller face buttons
2991b9f6ac SDL now represents gamepad buttons as positional elements with a separate label
8708ba7393 Don't leak if realloc fails
36b2d2e463 Fix memory leak in SDL_SendDrop()
dfb87e1099 Fix uninitialised variable 'properties'
e54c5e0204 Fix condition in SDLTest_TrackAllocations()
89408a9705 wasapi: ResetWasapiDevice no longer blocks on management thread.
aa7baf63aa Sync wiki -> headers.
74f3643bfa wayland: Add missing break to switch statement
2d6bae70b4 Older gcc does not support #pragma GCC diagnostic inside functions
d8600f717e  Pointer as bool (libsdl-org#7214)
23db971681 x11: Ignore deprecated declaration of XKeycodeToKeysym
61c39ce848 ci: re-enable Intel compilers on ci
4ac3f5c07e Updated Xcode project with the video capture API
59f93e20a7 Add SDL Video Capture, with back-end for linux/macos/ios/android
3ab98a3572 Removed debug print statements (thanks @stsp!)
f4b61fff30 Implemented VT switching for KMSDRM on Linux
391a3d23d0 cmake: the compile-time pdb does not have a suffix, if set
a6541166bc cmake: also install pdb files of static libraries
2e3f574f8f cmake: don't add the C runtime library to the .obj file (when using MSVC)
bea34c5380 Fixed a memory leak at window creation.
b5347c3364 Fixed emscripten and iOS builds
02f356439d Allow the application to draw while Windows is in a modal move/resize loop
1934417b4d Show the existing mapping when a controller is connected
407a3cb4e0 Fixed infinite recursion initializing properties
979214363f Added SDL_GetGlobalProperties()
151cdfa99f Added the "SDL.window.wayland.registry" property
6c91b28e71 Added the "SDL.renderer.d3d12.command_queue" property
4e8d1ec983 Fixed crash trying to create a metal view with the dummy driver
fd4a2cce9e SDL_syswm.h has been removed and replaced with window properties
aea6e6de6f Simplified SDL_SetProperty() and added SDL_SetPropertyWithCleanup()
a1941fad6c Replaced SDL_RenderGetD3D11Device(), SDL_RenderGetD3D12Device(), and SDL_RenderGetD3D9Device() with renderer properties.
0cd4b7d3e3 Added display properties
a02afbaea5 Clean up window properties when the window is destroyed
8668943746 Standardized property names for internal SDL properties
a4c6b38fef Fixed FreeBSD build
d9e6dcc650 Fixed FreeBSD build
7cc3e94eb2 Store the requested muted state
ce9e1bd324 Don't mute the console input if we can't read the keyboard
0a1b6b270f sdlchecks.cmake: Clarified the reason why shared X11 mode doesn't work
80b2bbad21 Removed useless branch test
15bc12165a Actually we need to enumerate the 8BitDo Xbox SKUs
8049af3355 Assume all 8BitDo Xbox controllers have a share button
ed1e0c1530 Make sure joysticks are locked when adding and removing them
415283ef38 Fixed checking for linux/input.h
fea2504a37 Prioritize the pipewire audio driver over ALSA
04e98d2236 Added missing calls to SDL_InvalidParamError("surface")
521bbcc15e Destroy the window surface if we've created it for the software renderer
28e623c504 Added a mapping for the Atari VCS controller connected over Bluetooth (thanks @WizzardSK!)
4106697774 Make sure we include the null terminator in XLookupStringAsUTF8()
b5057edf29 Remove unused SDL_TextureModulate enum
9458cbf75e Removed unused SDL_OSEvent
1a57f6bb29 wayland: Remove QtWayland extensions
5f920d6639 fix emscripten build after commit 07cb7c10
22016b4eae Enable the 5th player LED on the DualSense controller
66cf30c2de Removed misleading comment
dbcd390cdf Log drag and drop position updates in SDL test programs
07cb7c10a1 Fixed connecting and disconnecting real-joysticks closing virtual joysticks in Emscripten (thanks David!)
869257a5c1 SDL_migration.cocci: Added a thing for SDL_Vulkan_CreateSurface.
c6d9fb1ad7 hidapi: Avoid memcpy'ing to NULL.
4d1aecc225 vulkan: Patched to compile on iOS.
fccec65afe Sync SDL3 wiki -> header
2f92807087 vulkan: SDL_Vulkan_CreateSurface now accepts an app-provided allocator.
c53843a961 docs: Remove Doxygen `\brief` tags.
c132295ad7 SDL_FlushEventMemory is not a public procedure.
7ac281f800 Sync wiki -> headers.
f7d40b7594 Added 10-bit pixel formats in addition to SDL_PIXELFORMAT_ARGB2101010
3e4d7e48b0 Fixed memory leak in XInput code
bc3d9e99f3 Only save ibus_addr_file after we've successfully read an address from it.
04dfca958a Added a note to events indicating that memory is owned by SDL
20cd789bab Improved migration documentation for the event memory change.
459f17257c cmake: fix MSVC unrecognized option link warning
761390b62f cmake: detect linker id, and assume MSVC does not support version scripts
d2e005ee13 dynapi: remove duplicated SDL_LoadWAV entries
21ff699251 test: Fix popup test crash on exit
70c149c88f Automatically clean up memory associated with events
1a83bf2399 fix a possible memory leak in SDL_vasprintf()
59b37d0e5b cmake: fix Windows unrecognized option link warning
9302d7732d Fixed touch normalized coordinates
ff3c20a799 Sync SDL3 wiki -> header
17a0fe3a0c Sync SDL3 wiki -> header
14d2471a8f Sync SDL3 wiki -> header
2ad22eeeb5 Sync SDL3 wiki -> header
930438dfb7 Added note that the #ifdef is for !__IOS__
c56583fe45 Fix duplicate symbol on iOS/tvOS
2b62f25a6f Add SDL_sysmain_callbacks.c to the Xcode project
4ab31ca678 Fix dropping file event
5dce4bc716 Makes SDLInputConnection and DummyEdit public classes (thanks Cole!)
d3f2eb2aba Use XINPUT_STATE instead of XINPUT_STATE_EX (thanks Andrew!)
3a482ebae0 Add createSDLMainRunnable() to SDLActivity (thanks Cole!)
b9784feb24 Fixed potential uninitialized memory access (thanks Mathieu!)
75ea3a8d32 Dynamically allocate long text for SDL_EVENT_TEXT_INPUT events
2a1660ab51 Additional cleanup for SDL_RWprintf() (thanks @sezero!)
e5f2cea234 Sync wiki -> headers
ad842dd5ad Fixed a typo in SDL_log.h
f9d11807c0 Added SDL_RWprintf() and SDL_RWvprintf() to do formatted printing to an SDL_rwops stream
52c4e3eab3 events: Update self-referential pointers when copying event objects
91f0456391 Add the source application for drag and drop events (thanks Nathan!)
1a8bf31a69 include: Fixing whitespace on SDL_MixAudioFormat.
d07a264a9b Use the default UCS2/UCS4 conversion rather than non-portable INTERNAL encoding
780b6612a9 wayland: Wayland_Vulkan_GetInstanceExtensions didn't set the count variable.
46b940d571 Updated documentation to note that the event callback is called on the same thread as the main iteration callback
4481754359 Make sure we only dispatch events on the main thread when using application callbacks
274da8561c Updated the migration guide to note that you can check the return value of SDL_AddEventWatch()
ad9dcdbbce Clarify that you should use the other field when reading the event
a19029e3c1 docs: Updated README-main-functions.md based on feedback.
019468dc59 main: Check for SDL_AddEventWatch failure, now that it can report it.
7e445da569 Added SDL_CleanupEvent()
c4bf05fd9d Added subsystem refcount tests to testautomation
7f65ed6461 Handle subsystem dependencies recursively
a6b85c81cc Fixed build
3ab6670cb1 Sync SDL3 wiki -> header
f439ccfc1a Updated return values for SDL event functions
e0379c3b37 Grab events in large chunks in SDL_IterateMainCallbacks()
ad5264e54f Don't run SDL_IterateMainCallbacks() if the init call returns an exit code
dad1a84be4 Fixed building Vivante video driver
fe175d025f Fixed building Vivante video driver
0b460f34ba The HP HyperX controllers have a share button
f3261fedcc Code cleanup now that SDL_bool is equivalent to a C boolean expression
a76d8e39aa Changed SDL_bool from an enum to unsigned int
cf7e5bd0e8 Sync SDL3 wiki -> header
853c28e624 docs: Added first draft of README-main-functions.md
70d75b4a23 Sync wiki -> headers
ea02630143 More audio migration clarification
14980b25a8 Clarify documentation for audio callback migration
6cf84e2c5b cmake: fold HAVE_INPUT_EVENTS into HAVE_LINUX_INPUT_H
5e869d1b35 fix Cocoa_Vulkan_GetInstanceExtensions prototype for Mac
07a776f255 include: Fixed documentation for SDL_Vulkan_GetInstanceExtensions.
5b3a2c6df6 docs: Updated SDL_Vulkan_GetInstanceExtensions info in README-migration.md.
9224a0a2d8 Fix emscripten, android, uikit and windows
d0d8b28df1 Change SDL_Vulkan_GetInstanceExtensions
338974bb29 SDL_test_memory.c: fix build against older windows SDKs.
618d15bce6 Fixed typo
ad0af48883 Check to make sure the Windows joystick device has buttons and axes
ac6b32bb02 gendynapi.py: Discard SDLMAIN_DECLSPEC functions.
9c664b0062 main: Added _optional_ callback entry points.
9323417e9c Fixed gendyapi.py parsing of SDL_RELEASE_GENERIC
759cdf6159 audio: Fixed GetFirstAudioDeviceAdded().
0e614d9179 audio: Massive reworking on thread locking.
40fb76196c audio: Don't let simplified audio streams bind to new devices.
24e3328cca audio: Don't reset device ID counter on subsystem init/quit.
5d95cbde37 cmake: reset check state before testing -fobjc-arc
f18120c83c cmake: check -fobjc-arc compiler flag on Apple platforms
4aacc4b92e cmake: file(RELATIVE_PATH) needs 2 absolute paths
dcc8805c21 testaudio: Fixed compiler warning on Visual Studio.
9cb259e865 audio: Never SDL_PushEvent from anywhere but SDL_UpdateAudio().
875e45e70b wayland: Sanity check pointers and protocols before confining
0e87b71d08 wayland: Check the relative pointer handle before destroying
6127ac0871 Use SDL_DISABLE_ALLOCA instead of HAVE_ALLOCA in SDL_stdinc.h
552bee47cb Clear any previous errors if we successfully show a message box
343da852a6 Don't try to use the Wayland messagebox if we're not in Wayland
f63e9a8a3f wasapi: Handle disconnected devices that get reconnected.
5fa7b291d4 wasapi: Fixed memory leak if new audio devices fail to add.
468c386686 wasapi: Handle disconnect notifications from the management thread, too.
ce3be02b48 wasapi: If device is marked as a zombie, don't try to resuscitate it.
85923049a6 wasapi: Patched to compile.
9bec57309c wasapi: Proxy default device change handling to management thread.
c45b5121ce audio: Fixed potential race condition.
8b6da3c701 Fixed making the EGL context current when resuming on Android
2e9eb1073d Sync SDL3 wiki -> header
e6116d399a mutex: Removed SDL_MUTEX_MAXWAIT.
82f48be3ef Sync SDL3 wiki -> header
899eb0d042 thread: Locking mutexes and rwlocks are now void functions.
082ef41566 alsa: Fix crash from invalid handle pointer
a9aa15c792 CI: change FreeBSD CI runner to cross-platform-actions.
23ceae94c9 Fixed Xbox 360 Controller support using libusb on Linux
ace0c2c297 mutex: Fixed bug where generic SDL_TryLockMutex would incorrectly block.
f52b330ed8 Added support for the HP HyperX Clutch Gladiate controller
b61706373c n3ds: Check that audio thread name starts with "SDLAudioP"
6827b3331d n3ds systhread - use 80kb thread stack size as default, remove hard cap
e4cd1d4059 n3ds systhread - prefer to put audio thread on system core
1023d8ec84 SDL_n3dsaudio.c - don't risk leaving current_priority uninitialized
07171be596 SDL_n3dsaudio.h: use triple buffering
6efe957159 SDL_n3dsaudio.c: separate mixer locks from audio device locks
39a961ba41 Added support for "%[]" sscanf syntax
124a0050b6 Fixed warning: no previous prototype for function 'SDL_UpdateAudio'
b16165a33f rwlock: SDL_UnlockRWLock was incorrectly tagged with SDL_RELEASE_SHARED.
865dd04068 pulseaudio: Don't use a hash for device change detection.
b8cc51875a Fixed build
0413e21e54 Fixed audio device removed events for ALSA
5ba03d377a Revert "Fixed audio device removed events for ALSA"
a774694be0 pulseaudio: Simplified default device change detection code.
e57fef8f0b Fixed audio device removed events for ALSA
4280d4b359 Fixed warning C4210: nonstandard extension used: function given file scope
182cfc3265 pulseaudio: Rework how we manage default devices and hotplug.
b2ae1e835f pulseaudio: Change debug printf calls to use SDL_Log instead.
38afd48daf Added a single source of SDL object IDs
e07f6c0a17 SDL_IsJoystickProductWheel() returns SDL_TRUE for Asetek wheelbases (thanks @IOBYTE!)
c98a14fdeb Renamed display added/removed events for consistency with the rest of the API
c2a3112b6f Added "--substring" to the help for rename_symbols.py
a844d90942 Add missing error reporting in Android_JNI_FileOpen()
4ac38d13dd alsa: Don't touch free'd memory in hotplug thread.
43d41c9dcb audio: Another attempt to make device add/remove work vs event watchers.
9abc692156 audio: Another attempt to deal with device destruction from device thread.
33c9eeec7c Revert "audio: Device threads don't increment physical device refcounts."
e5a15f94e2 Revert "Check to make sure the Windows joystick device has buttons and axes"
70fd8e2ba2 Lock joysticks when adding gamepad mappings
76f81797b7 audio: Device threads don't increment physical device refcounts.
594fda4120 Sync SDL3 wiki -> header
0d7c5a2c56 Updated Android API documentation
0df888c584 Moved Android low latency audio behind a hint "SDL_ANDROID_LOW_LATENCY_AUDIO"
142366c837 Sync SDL3 wiki -> header
3a4c9d6990 Fixed build error when API logging is enabled
1f8f82b379 Removed redundant thread-safety information
a6edc75fe7 Sync SDL3 wiki -> header
3c8edeb79b Clarified SDL property thread-safety information
4fa821cb3e Sync SDL3 wiki -> header
1c70760c0b Added thread-safety information for the new SDL properties API
15533dce05 Cleaned up warnings from check_stdlib_usage.py
bf269571fc jack: Removed FIXME comment that has since been fixed.
797b70877d audio: Remove stub header SDL_audio_c.h.
9d7c57234a audio: Cleaned out most remaining `/* */` comments for `//` style.
0ff67dc21b video: Fix compiler warning about SDL_ReadSurfacePixel not being declared.
81c77396af opensles: Patched to compile.
442e84916a opensles: Fixed capitalization to match other SDL backends.
34914bfb49 alsa: Clean up device handles, now that hotplug thread cleanup is in place.
48d80efb51 Fixed warning C4701: potentially uninitialized local variable 'props' used
f7dc63bcc3 audio: another windows wasapi build fix.
dd98330076 audio: fix windows wasapi build.
7a52f7b3fd audio: Split Deinitialize into two stages.
e55e556f32 alsa: Fixed minor memory leak.
b45a0d9016 Updated the documentation for SDL_LoadWAV_RW()
435e7ce663 Check for device disconnection in HIDAPI_JoystickOpen()
b733adb503 audio: Fix device refcounting vs ProvidesOwnCallbackThread backends.
c6f08c2553 testaudio: Removed debugging code.
d5dac0ad27 testaudio: Deal with a texture being unexpectedly NULL when scaling.
b19e68c8ec testaudio: Properly display playback progress, regardless of data source.
8c39269279 audio: Fix audio stream format when binding to a capture device.
f26b838a3e jack: Check for sample rate and buffer size changes from the server.
063cb0df6b audio: Fixed comment typo. "deref" should be "unref"
354611a0c6 testaudio: Fixed some bugs Valgrind pointed out.
a17f3ba916 audio: Reworked audio device disconnect management.
6ddd96a4d0 Fix some wrong gamepad/controller event enums
8df68b4120 hashtable: Moved over to single-line comments.
1c6d996108 testaudio: if the SDL_Renderer is already gone, don't destroy SDL_Textures.
b22ffb9797 audio: Fix some logic errors in the new device hashtable code.
e526dc64bd Don't set unused variable
6664437748 hashtable: Don't rearrange bucket elements during SDL_FindInHashTable.
8ac5c84ad1 audio: device thread shouldn't touch `thread_alive` after object is free'd.
b17151eb16 testaudio: Don't crash if renderer is NULL (happens during shutdown).
7f408e57ee audio: Keep all available devices in a hashtable instead of linked lists.
0aba2c97db hashtable: SDL_IterateHashTable might as well provide both key and value.
95a9271dbf audio: Never lock a device while holding the device_list_lock.
9aeabb0b05 Fix macOS build error by #8269
382751c4b5 testffmpeg: print usage of options to change audio/video codec
f91bde64d5 testffmpeg: Only enable blending if we're using a texture format that supports it
516d6f9efc testffmpeg: added support for YUVA formats using swscale
ac71831350 Sync wiki -> headers
d18f910248 testffmpeg: added the ability to specify audio and video codecs
72034b9a07 wayland: Fix primary selection handling when the protocol isn't supported
e152129787 Fixes #8190. From #7249, reverted the hunks other than #7239.
b79db0a6ea Fixed potential wraparound issue with property IDs
c9ccf0670c Add unsupported functions to dynapi
25ce87979d Always provide an implementation for all SDL3 symbols
3a36433a3c cmake: test -Wl,--version-script with minimal version script
0efa196989 dynapi: implement SDL_DYNAPI_entry even when building SDL without dynapi support
bf64fecf19 testffmpeg: allow resizing of the video window
efa9a45048 Clarified that testffmpeg will resize the window to the video size
4368f70ff9 Added properties to various SDL objects
973c8b3273 Added SDL properties API
2bca4671a6 audio: Allow audio streams to be created when the subsystem isn't initialized.
1ae33f6751 cmake: optionally install pdb's
0d5cad91b1 We need audio converters initialized in SDL_InitAudio()
1c3a0ade74 audio: Whoops, this stream format change is only for capture devices.
10fab3a39e pulseaudio: Stop the threaded mainloop before destroying the context.
0b71898cb1 Make it clear that the string comparison isn't a boolean check
6c8ad975c7 Like mutexes, operations on NULL rwlocks are no-ops
c552cc6847 We don't require the audio system to be initialized for audio format conversion
9a5f7b17c6 Use SDL wrapped getenv function
044046bc50 audio: Fixed assertions when capture devices have wrong audio formats.
bb2f767f5d testaudio: Make program usable without a 3-button mouse.
321fc18417 README-migration.md: Added note about SDL_HasRDTSC removal.
82f54af617 x11: Properly check for XInput2 support before using it.
b654427537 Added support for the PowerA Nintendo Switch Nano Wired Controller
dc2a5f6ab2 Fixed error C2054: expected '(' to follow 'inline'
a7ae1de9a6 Fixed warning C4028: formal parameter different from declaration
3a47fb7208 The sensor and joystick instance ID generator isn't guarded by a lock.
aee4862958 ci: stop FreeBSD job after 30 minutes
99fa0d6cae Disable low latency audio by default when using AAudio on Android
ebfbd7327b testffmpeg: use SDL_test to parse arguments and track memory
ee53e4d319 cmake: check ffmpeg capability instead of version
2d62c65a75 Fixed build warning
bf72704bfd audio: Disable NEON sample conversion until test failures are fixed
0fe95cfba3 Sync wiki -> header
adcace6f95 Added a "--software" option to testffmpeg
86ada8a9f0 fix testffmpeg.c build.
303f4e965c testffmpeg works with ffmpeg 5.1.3 and newer
2bd478ae65 Added SDL_GetTextureDXGIResource() to get the DXGI resource associated with a render texture.
a842446f62 Added support for 0-copy decode and display using D3D11
d830cd140b Added support for 0-copy decode and display using Apple VideoToolbox
1bf913b29a Added support for 0-copy decode and display using VAAPI and EGL
ce8161e0cf Make sure we're building with ffmpeg 6.0 or newer
ed6381b68d Allow setting any number of sprites over the video
ebf5e08fa1 cmake: use *_STATIC_* variables when linking to a static ffmpeg
88f2fb9dcf Added an example of video decoding with ffmpeg
d88bf687a8 surface: Document the in-memory layout of the pixels
3698630bbc pixels: Document the naming convention
04edb38cdf shape: Use SDL[Test]_ReadSurfacePixel
f5745c3a67 surface: Add a private SDL_ReadSurfacePixel
0d68f45879 test: Extract SDLTest_ReadSurfacePixel
55a1458ed0 audio: Changes to one logical device must update all sibling logical devices.
8e03ea4383 hashtable: Use Create/Destroy naming, in the SDL3 style.
568902b64e hashtable: Added src/SDL_hashtable.[ch].
8745a9949b add-source-to-projects.pl: Fix adding files in the base src dir.
836927edf8 wayland: Try to skip the Wayland driver if not connecting to or in a Wayland session
2a9480c815 wayland: Add null check for zenity version string
f30392da5b Fix assertion in LINUX_JoystickSetSensorsEnabled()
4e59bf6cb9 SDLTest_CompareSurfaces: Output RGBA values of first differing pixel
b2ddfbbec3 SDLTest_CompareSurfaces: If surfaces differ, log their formats
b028fd9604 SDLTest_CompareSurfaces: Log better messages if NULL or different sizes
183606d3d4 testdrawchessboard: clean up renderer and window
4f0642bf47 triangle: don't read destination pixel when you're going to discard it anyways
4cd0c13823 blit_slow: don't read destination pixel when you're going to discard it anyways
49abb9c1fa aaudio: Fixed a comment.
0eb8651d5e Do not report gyro/accelerometer if we can't read axes info
ff57867516 audio: Fixed copy/paste error that was checking wrong variable.
d2d4914ac3 audio: WaitDevice/WaitCaptureDevice now returns a result.
a0820ed833 directsound: Cleaned up WaitDevice.
6c33a05bdb audio: Removed unused AllowsArbitraryDeviceNames variable.
f1fc198278 audio: Destroy the logical audio device before sending DEVICE_REMOVED event.
64ec208479 Fix log message spelling
9111c5e178 tests: Disable mouse warp test under Wayland
de5068f4e4 audio: Commented out a currently-incorrect assert.
3abb464f10 ci: disable Intel compilers
251f8fa272 Revert "Do a better job of finding default ALSA devices"
8857b0f13a Use the device audio format for the lowest latency
806e11ac00 Update sample processing bookkeeping when recovering the AAudio audio device
482c238953 aaudio: Deal with device recovery.
a8813b58a6 aaudio: Change an int to an SDL_bool.
8923305f34 We don't need to wait a full 10 ms, just delay a bit
6a152676bb Wait a bit when snd_pcm_avail() returns 0
b4372de186 alsa: Cleaned up remaining debug logging.
a063c943dc pulseaudio: Use pa_stream_begin_write to avoid an extra buffer copy.
0471a93706 alsa: Simplified PlayDevice and CaptureFromDevice.
776d9d0ee3 alsa: Convert `/* */` comments to `//` comments.
64fee85c69 alsa: More efficient audio thread iteration.
47cba08259 VisualC/pkg-support/cmake: remove subdir from public header include path
61e9a9dd56 pulseaudio: Just feed the device whenever it asks for any amount of data.
4f76f9b0a7 pulseaudio: Use correct buffer size of stream, wait less between fills.
d95d2d7051 SDLTest_CompareSurfaces: Decode pixels correctly on big-endian platforms
d65861f049 Do a better job of finding default ALSA devices
ba65ef5ce7 Recover from -EPIPE in snd_pcm_avail()
5be5000fa1 cmake: make HEADERS_DIR a required argument of SDL_generate_manpages
5c1a91a4e1 ci: make sure perl is installed + build docs with MSVC toolchain
6248472c0c test: Accept small numerical differences in more mathematical tests
a2c5dc6507 pulseaudio: Added typedef needed for compat with ancient Pulse installs.
f24551f6d1 pulseaudio: More workarounds for extremely old Pulse installs.
441a5b707b audio: Adjusted const/static fields on some variables.
280c2c1d7d pulseaudio: Revert "pulseaudio: Require PulseAudio 5.0 or later for SDL3."
4db2b968af audio: simple-copy path should check if device is paused.
505dc4c39c wasapi: Deal with device failures when we aren't holding the device lock.
ea5f59c234 Removed unused code
a6854098f7 Fixed stuttering on Android when using the AAudio driver
a5175e5ed0 audio: Fixed bug when setting up mixing formats.
9667aa18e6 wayland: Check that the data device supports the release method before calling it
4454dc400b wayland: Null all Wayland manager objects after freeing
e1789b320e video: Streamline a little deinit code.
2a1058713c Bump libdecor feature check to look for 0.2.0
f5886f11d0 cmake: let every test depends on pretest
f45761908a Move check for SDL_Delay upper bounds to testtimer
a84389f6bb libm: use union for infinity
474c8d0073 testautomation: don't do float equality tests
a6bc6b882c ci: always upload the artifacts
85e3099ba4 testautomation: only require accelated renderer with non-dummy video driver
26fd231151 ci: run tests on msvc workflow
0e955a9127 cmake: run testautomation with CTest
1375d2049d SDL_iconv_string() defaults to UTF-8
70a1bc6973 Check for NULL before dereferencing newly allocated memory
752f14e5a6 wayland: Convert some memcpy calls to copyp
9284a03053 wayland: Remove some unnecessary helper functions

git-subtree-dir: external/sdl/SDL
git-subtree-split: 0d7df16812c75c4a587d7d2673e3d1a5f2c2879b
This commit is contained in:
Green Sky
2024-01-17 16:26:06 +01:00
parent 644725478f
commit 852f2a6343
1244 changed files with 49212 additions and 27224 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
include/SDL3/SDL.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -58,16 +58,17 @@
#include <SDL3/SDL_misc.h>
#include <SDL3/SDL_mouse.h>
#include <SDL3/SDL_mutex.h>
#include <SDL3/SDL_pen.h>
#include <SDL3/SDL_pixels.h>
#include <SDL3/SDL_platform.h>
#include <SDL3/SDL_power.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_quit.h>
#include <SDL3/SDL_rect.h>
#include <SDL3/SDL_render.h>
#include <SDL3/SDL_rwops.h>
#include <SDL3/SDL_scancode.h>
#include <SDL3/SDL_sensor.h>
#include <SDL3/SDL_shape.h>
#include <SDL3/SDL_surface.h>
#include <SDL3/SDL_system.h>
#include <SDL3/SDL_thread.h>
@ -75,6 +76,7 @@
#include <SDL3/SDL_touch.h>
#include <SDL3/SDL_version.h>
#include <SDL3/SDL_video.h>
#include "SDL3/SDL_video_capture.h"
#include <SDL3/SDL_oldnames.h>
#endif /* SDL_h_ */

4
include/SDL3/SDL_assert.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_assert.h
*
* \brief Header file for assertion SDL API functions
* Header file for assertion SDL API functions
*/
#ifndef SDL_assert_h_

15
include/SDL3/SDL_atomic.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_atomic.h
*
* \brief Atomic operations.
* Atomic operations.
*
* IMPORTANT:
* If you are not an expert in concurrent lockless programming, you should
@ -213,7 +213,7 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
#if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__) || defined(__ARM_ARCH_8A__)
#define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory")
#define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("dmb ish" : : : "memory")
#elif defined(__ARM_ARCH_6__) || defined(__ARM_ARCH_6J__) || defined(__ARM_ARCH_6K__) || defined(__ARM_ARCH_6T2__) || defined(__ARM_ARCH_6Z__) || defined(__ARM_ARCH_6ZK__) || defined(__ARM_ARCH_5TE__)
#elif defined(__ARM_ARCH_6__) || defined(__ARM_ARCH_6J__) || defined(__ARM_ARCH_6K__) || defined(__ARM_ARCH_6T2__) || defined(__ARM_ARCH_6Z__) || defined(__ARM_ARCH_6ZK__)
#ifdef __thumb__
/* The mcr instruction isn't available in thumb mode, use real functions */
#define SDL_MEMORY_BARRIER_USES_FUNCTION
@ -263,8 +263,9 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
/**
* \brief A type representing an atomic integer value. It is a struct
* so people don't accidentally use numeric operations on it.
* A type representing an atomic integer value.
*
* It is a struct so people don't accidentally use numeric operations on it.
*/
typedef struct { int value; } SDL_AtomicInt;
@ -340,14 +341,14 @@ extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a);
extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v);
/**
* \brief Increment an atomic variable used as a reference count.
* Increment an atomic variable used as a reference count.
*/
#ifndef SDL_AtomicIncRef
#define SDL_AtomicIncRef(a) SDL_AtomicAdd(a, 1)
#endif
/**
* \brief Decrement an atomic variable used as a reference count.
* Decrement an atomic variable used as a reference count.
*
* \return SDL_TRUE if the variable reached zero after decrementing,
* SDL_FALSE otherwise

35
include/SDL3/SDL_audio.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,18 +22,19 @@
/**
* \file SDL_audio.h
*
* \brief Audio functionality for the SDL library.
* Audio functionality for the SDL library.
*/
#ifndef SDL_audio_h_
#define SDL_audio_h_
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_endian.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_mutex.h>
#include <SDL3/SDL_thread.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_rwops.h>
#include <SDL3/SDL_thread.h>
#include <SDL3/SDL_begin_code.h>
/* Set up for C function definitions, even when using C++ */
@ -53,7 +54,7 @@ extern "C" {
*/
/**
* \brief Audio format flags.
* Audio format flags.
*
* These are what the 16 bits in SDL_AudioFormat currently mean...
* (Unspecified bits are always zero).
@ -659,7 +660,7 @@ extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_AudioStre
*
* \param src_spec The format details of the input audio
* \param dst_spec The format details of the output audio
* \returns 0 on success, or -1 on error.
* \returns a new audio stream on success, or NULL on failure.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -675,6 +676,19 @@ extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_AudioStre
*/
extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec);
/**
* Get the properties associated with an audio stream.
*
* \param stream the SDL_AudioStream to query
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream);
/**
* Query the current format of an audio stream.
@ -1267,8 +1281,7 @@ extern DECLSPEC int SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid,
* audio data allocated by the function is written to `audio_buf` and its
* length in bytes to `audio_len`. The SDL_AudioSpec members `freq`,
* `channels`, and `format` are set to the values of the audio data in the
* buffer. The `samples` member is set to a sane default and all others are
* set to zero.
* buffer.
*
* It's necessary to use SDL_free() to free the audio data returned in
* `audio_buf` when it is no longer used.
@ -1414,9 +1427,9 @@ extern DECLSPEC int SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * spec,
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_MixAudioFormat(Uint8 * dst,
const Uint8 * src,
SDL_AudioFormat format,
Uint32 len, int volume);
const Uint8 * src,
SDL_AudioFormat format,
Uint32 len, int volume);
/**
* Convert some audio data of one format to another format.

2
include/SDL3/SDL_begin_code.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages

4
include/SDL3/SDL_bits.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_bits.h
*
* \brief Functions for fiddling with bits and bitmasks.
* Functions for fiddling with bits and bitmasks.
*/
#ifndef SDL_bits_h_

10
include/SDL3/SDL_blendmode.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_blendmode.h
*
* \brief Header file declaring the SDL_BlendMode enumeration
* Header file declaring the SDL_BlendMode enumeration
*/
#ifndef SDL_blendmode_h_
@ -35,7 +35,7 @@ extern "C" {
#endif
/**
* \brief The blend mode used in SDL_RenderTexture() and drawing operations.
* The blend mode used in SDL_RenderTexture() and drawing operations.
*/
typedef enum
{
@ -60,7 +60,7 @@ typedef enum
} SDL_BlendMode;
/**
* \brief The blend operation used when combining source and destination pixel components
* The blend operation used when combining source and destination pixel components
*/
typedef enum
{
@ -72,7 +72,7 @@ typedef enum
} SDL_BlendOperation;
/**
* \brief The normalized factor used to multiply pixel components
* The normalized factor used to multiply pixel components
*/
typedef enum
{

4
include/SDL3/SDL_clipboard.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_clipboard.h
*
* \brief Include file for SDL clipboard handling
* Include file for SDL clipboard handling
*/
#ifndef SDL_clipboard_h_

2
include/SDL3/SDL_close_code.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages

4
include/SDL3/SDL_copying.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,5 +22,5 @@
/**
* \file SDL_copying.h
*
* \brief Header file containing SDL's license.
* Header file containing SDL's license.
*/

4
include/SDL3/SDL_cpuinfo.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_cpuinfo.h
*
* \brief CPU feature detection for SDL.
* CPU feature detection for SDL.
*/
#ifndef SDL_cpuinfo_h_

4
include/SDL3/SDL_egl.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_egl.h
*
* \brief This is a simple file to encapsulate the EGL API headers.
* This is a simple file to encapsulate the EGL API headers.
*/
#if !defined(_MSC_VER) && !defined(__ANDROID__) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS)

4
include/SDL3/SDL_endian.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_endian.h
*
* \brief Functions for reading and writing endian-specific values
* Functions for reading and writing endian-specific values
*/
#ifndef SDL_endian_h_

19
include/SDL3/SDL_error.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -102,23 +102,6 @@ extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fm
*/
extern DECLSPEC const char *SDLCALL SDL_GetError(void);
/**
* Get the last error message that was set for the current thread.
*
* This allows the caller to copy the error string into a provided buffer, but
* otherwise operates exactly the same as SDL_GetError().
*
* \param errstr A buffer to fill with the last error message that was set for
* the current thread
* \param maxlen The size of the buffer pointed to by the errstr parameter
* \returns the pointer passed in as the `errstr` parameter.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetError
*/
extern DECLSPEC char * SDLCALL SDL_GetErrorMsg(char *errstr, int maxlen);
/**
* Clear any previous error message for this thread.
*

312
include/SDL3/SDL_events.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -34,6 +34,7 @@
#include <SDL3/SDL_joystick.h>
#include <SDL3/SDL_keyboard.h>
#include <SDL3/SDL_mouse.h>
#include <SDL3/SDL_pen.h>
#include <SDL3/SDL_quit.h>
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_touch.h>
@ -92,8 +93,8 @@ typedef enum
/* Display events */
/* 0x150 was SDL_DISPLAYEVENT, reserve the number for sdl2-compat */
SDL_EVENT_DISPLAY_ORIENTATION = 0x151, /**< Display orientation has changed to data1 */
SDL_EVENT_DISPLAY_CONNECTED, /**< Display has been added to the system */
SDL_EVENT_DISPLAY_DISCONNECTED, /**< Display has been removed from the system */
SDL_EVENT_DISPLAY_ADDED, /**< Display has been added to the system */
SDL_EVENT_DISPLAY_REMOVED, /**< Display has been removed from the system */
SDL_EVENT_DISPLAY_MOVED, /**< Display has changed position */
SDL_EVENT_DISPLAY_CONTENT_SCALE_CHANGED, /**< Display has changed content scale */
SDL_EVENT_DISPLAY_FIRST = SDL_EVENT_DISPLAY_ORIENTATION,
@ -101,8 +102,8 @@ typedef enum
/* Window events */
/* 0x200 was SDL_WINDOWEVENT, reserve the number for sdl2-compat */
SDL_EVENT_SYSWM = 0x201, /**< System specific event */
SDL_EVENT_WINDOW_SHOWN, /**< Window has been shown */
/* 0x201 was SDL_EVENT_SYSWM, reserve the number for sdl2-compat */
SDL_EVENT_WINDOW_SHOWN = 0x202, /**< Window has been shown */
SDL_EVENT_WINDOW_HIDDEN, /**< Window has been hidden */
SDL_EVENT_WINDOW_EXPOSED, /**< Window has been exposed and should be redrawn */
SDL_EVENT_WINDOW_MOVED, /**< Window has been moved to data1, data2 */
@ -122,12 +123,16 @@ typedef enum
SDL_EVENT_WINDOW_DISPLAY_CHANGED, /**< Window has been moved to display data1 */
SDL_EVENT_WINDOW_DISPLAY_SCALE_CHANGED, /**< Window display scale has been changed */
SDL_EVENT_WINDOW_OCCLUDED, /**< The window has been occluded */
SDL_EVENT_WINDOW_ENTER_FULLSCREEN, /**< The window has entered fullscreen mode */
SDL_EVENT_WINDOW_LEAVE_FULLSCREEN, /**< The window has left fullscreen mode */
SDL_EVENT_WINDOW_DESTROYED, /**< The window with the associated ID is being or has been destroyed. If this message is being handled
in an event watcher, the window handle is still valid and can still be used to retrieve any userdata
associated with the window. Otherwise, the handle has already been destroyed and all resources
associated with it are invalid */
SDL_EVENT_WINDOW_PEN_ENTER, /**< Window has gained focus of the pressure-sensitive pen with ID "data1" */
SDL_EVENT_WINDOW_PEN_LEAVE, /**< Window has lost focus of the pressure-sensitive pen with ID "data1" */
SDL_EVENT_WINDOW_FIRST = SDL_EVENT_WINDOW_SHOWN,
SDL_EVENT_WINDOW_LAST = SDL_EVENT_WINDOW_DESTROYED,
SDL_EVENT_WINDOW_LAST = SDL_EVENT_WINDOW_PEN_LEAVE,
/* Keyboard events */
SDL_EVENT_KEY_DOWN = 0x300, /**< Key pressed */
@ -136,7 +141,6 @@ typedef enum
SDL_EVENT_TEXT_INPUT, /**< Keyboard text input */
SDL_EVENT_KEYMAP_CHANGED, /**< Keymap changed due to a system event such as an
input language or keyboard layout change. */
SDL_EVENT_TEXT_EDITING_EXT, /**< Extended keyboard text editing (composition) */
/* Mouse events */
SDL_EVENT_MOUSE_MOTION = 0x400, /**< Mouse moved */
@ -166,6 +170,7 @@ typedef enum
SDL_EVENT_GAMEPAD_TOUCHPAD_UP, /**< Gamepad touchpad finger was lifted */
SDL_EVENT_GAMEPAD_SENSOR_UPDATE, /**< Gamepad sensor was updated */
SDL_EVENT_GAMEPAD_UPDATE_COMPLETE, /**< Gamepad update is complete */
SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED, /**< Gamepad Steam handle has changed */
/* Touch events */
SDL_EVENT_FINGER_DOWN = 0x700,
@ -192,6 +197,13 @@ typedef enum
/* Sensor events */
SDL_EVENT_SENSOR_UPDATE = 0x1200, /**< A sensor was updated */
/* Pressure-sensitive pen events */
SDL_EVENT_PEN_DOWN = 0x1300, /**< Pressure-sensitive pen touched drawing surface */
SDL_EVENT_PEN_UP, /**< Pressure-sensitive pen stopped touching drawing surface */
SDL_EVENT_PEN_MOTION, /**< Pressure-sensitive pen moved, or angle/pressure changed */
SDL_EVENT_PEN_BUTTON_DOWN, /**< Pressure-sensitive pen button pressed */
SDL_EVENT_PEN_BUTTON_UP, /**< Pressure-sensitive pen button released */
/* Render events */
SDL_EVENT_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */
SDL_EVENT_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */
@ -211,7 +223,7 @@ typedef enum
} SDL_EventType;
/**
* \brief Fields shared by every event
* Fields shared by every event
*/
typedef struct SDL_CommonEvent
{
@ -220,7 +232,7 @@ typedef struct SDL_CommonEvent
} SDL_CommonEvent;
/**
* \brief Display state change event data (event.display.*)
* Display state change event data (event.display.*)
*/
typedef struct SDL_DisplayEvent
{
@ -231,25 +243,25 @@ typedef struct SDL_DisplayEvent
} SDL_DisplayEvent;
/**
* \brief Window state change event data (event.window.*)
* Window state change event data (event.window.*)
*/
typedef struct SDL_WindowEvent
{
Uint32 type; /**< ::SDL_WINDOWEVENT_* */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_WindowID windowID;/**< The associated window */
SDL_WindowID windowID; /**< The associated window */
Sint32 data1; /**< event dependent data */
Sint32 data2; /**< event dependent data */
} SDL_WindowEvent;
/**
* \brief Keyboard button event structure (event.key.*)
* Keyboard button event structure (event.key.*)
*/
typedef struct SDL_KeyboardEvent
{
Uint32 type; /**< ::SDL_EVENT_KEY_DOWN or ::SDL_EVENT_KEY_UP */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_WindowID windowID;/**< The window with keyboard focus, if any */
SDL_WindowID windowID; /**< The window with keyboard focus, if any */
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
Uint8 repeat; /**< Non-zero if this is a key repeat */
Uint8 padding2;
@ -257,55 +269,47 @@ typedef struct SDL_KeyboardEvent
SDL_Keysym keysym; /**< The key that was pressed or released */
} SDL_KeyboardEvent;
#define SDL_TEXTEDITINGEVENT_TEXT_SIZE (32)
#define SDL_TEXTEDITINGEVENT_TEXT_SIZE 64
/**
* \brief Keyboard text editing event structure (event.edit.*)
* Keyboard text editing event structure (event.edit.*)
*
* The `text` is owned by SDL and should be copied if the application
* wants to hold onto it beyond the scope of handling this event.
*/
typedef struct SDL_TextEditingEvent
{
Uint32 type; /**< ::SDL_EVENT_TEXT_EDITING */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_WindowID windowID; /**< The window with keyboard focus, if any */
char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE]; /**< The editing text */
Sint32 start; /**< The start cursor of selected editing text */
Sint32 length; /**< The length of selected editing text */
Uint32 type; /**< ::SDL_EVENT_TEXT_EDITING */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_WindowID windowID; /**< The window with keyboard focus, if any */
char *text; /**< The editing text */
Sint32 start; /**< The start cursor of selected editing text */
Sint32 length; /**< The length of selected editing text */
} SDL_TextEditingEvent;
#define SDL_TEXTINPUTEVENT_TEXT_SIZE 64
/**
* \brief Extended keyboard text editing event structure (event.editExt.*) when text would be
* truncated if stored in the text buffer SDL_TextEditingEvent
*/
typedef struct SDL_TextEditingExtEvent
{
Uint32 type; /**< ::SDL_EVENT_TEXT_EDITING_EXT */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_WindowID windowID; /**< The window with keyboard focus, if any */
char* text; /**< The editing text, which should be freed with SDL_free(), and will not be NULL */
Sint32 start; /**< The start cursor of selected editing text */
Sint32 length; /**< The length of selected editing text */
} SDL_TextEditingExtEvent;
#define SDL_TEXTINPUTEVENT_TEXT_SIZE (32)
/**
* \brief Keyboard text input event structure (event.text.*)
* Keyboard text input event structure (event.text.*)
*
* The `text` is owned by SDL and should be copied if the application
* wants to hold onto it beyond the scope of handling this event.
*/
typedef struct SDL_TextInputEvent
{
Uint32 type; /**< ::SDL_EVENT_TEXT_INPUT */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_WindowID windowID; /**< The window with keyboard focus, if any */
char text[SDL_TEXTINPUTEVENT_TEXT_SIZE]; /**< The input text */
Uint32 type; /**< ::SDL_EVENT_TEXT_INPUT */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_WindowID windowID; /**< The window with keyboard focus, if any */
char *text; /**< The input text */
} SDL_TextInputEvent;
/**
* \brief Mouse motion event structure (event.motion.*)
* Mouse motion event structure (event.motion.*)
*/
typedef struct SDL_MouseMotionEvent
{
Uint32 type; /**< ::SDL_EVENT_MOUSE_MOTION */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_WindowID windowID;/**< The window with mouse focus, if any */
SDL_MouseID which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
SDL_WindowID windowID; /**< The window with mouse focus, if any */
SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID, or SDL_PEN_MOUSEID */
Uint32 state; /**< The current button state */
float x; /**< X coordinate, relative to window */
float y; /**< Y coordinate, relative to window */
@ -314,14 +318,14 @@ typedef struct SDL_MouseMotionEvent
} SDL_MouseMotionEvent;
/**
* \brief Mouse button event structure (event.button.*)
* Mouse button event structure (event.button.*)
*/
typedef struct SDL_MouseButtonEvent
{
Uint32 type; /**< ::SDL_EVENT_MOUSE_BUTTON_DOWN or ::SDL_EVENT_MOUSE_BUTTON_UP */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_WindowID windowID;/**< The window with mouse focus, if any */
SDL_MouseID which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
SDL_WindowID windowID; /**< The window with mouse focus, if any */
SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID, or SDL_PEN_MOUSEID */
Uint8 button; /**< The mouse button index */
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
Uint8 clicks; /**< 1 for single-click, 2 for double-click, etc. */
@ -331,14 +335,14 @@ typedef struct SDL_MouseButtonEvent
} SDL_MouseButtonEvent;
/**
* \brief Mouse wheel event structure (event.wheel.*)
* Mouse wheel event structure (event.wheel.*)
*/
typedef struct SDL_MouseWheelEvent
{
Uint32 type; /**< ::SDL_EVENT_MOUSE_WHEEL */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_WindowID windowID;/**< The window with mouse focus, if any */
SDL_MouseID which; /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
SDL_WindowID windowID; /**< The window with mouse focus, if any */
SDL_MouseID which; /**< The mouse instance id, SDL_TOUCH_MOUSEID, or SDL_PEN_MOUSEID */
float x; /**< The amount scrolled horizontally, positive to the right and negative to the left */
float y; /**< The amount scrolled vertically, positive away from the user and negative toward the user */
Uint32 direction; /**< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back */
@ -347,7 +351,7 @@ typedef struct SDL_MouseWheelEvent
} SDL_MouseWheelEvent;
/**
* \brief Joystick axis motion event structure (event.jaxis.*)
* Joystick axis motion event structure (event.jaxis.*)
*/
typedef struct SDL_JoyAxisEvent
{
@ -363,7 +367,7 @@ typedef struct SDL_JoyAxisEvent
} SDL_JoyAxisEvent;
/**
* \brief Joystick hat position change event structure (event.jhat.*)
* Joystick hat position change event structure (event.jhat.*)
*/
typedef struct SDL_JoyHatEvent
{
@ -383,7 +387,7 @@ typedef struct SDL_JoyHatEvent
} SDL_JoyHatEvent;
/**
* \brief Joystick button event structure (event.jbutton.*)
* Joystick button event structure (event.jbutton.*)
*/
typedef struct SDL_JoyButtonEvent
{
@ -397,7 +401,7 @@ typedef struct SDL_JoyButtonEvent
} SDL_JoyButtonEvent;
/**
* \brief Joystick device event structure (event.jdevice.*)
* Joystick device event structure (event.jdevice.*)
*/
typedef struct SDL_JoyDeviceEvent
{
@ -407,7 +411,7 @@ typedef struct SDL_JoyDeviceEvent
} SDL_JoyDeviceEvent;
/**
* \brief Joysick battery level change event structure (event.jbattery.*)
* Joysick battery level change event structure (event.jbattery.*)
*/
typedef struct SDL_JoyBatteryEvent
{
@ -418,7 +422,7 @@ typedef struct SDL_JoyBatteryEvent
} SDL_JoyBatteryEvent;
/**
* \brief Gamepad axis motion event structure (event.gaxis.*)
* Gamepad axis motion event structure (event.gaxis.*)
*/
typedef struct SDL_GamepadAxisEvent
{
@ -435,7 +439,7 @@ typedef struct SDL_GamepadAxisEvent
/**
* \brief Gamepad button event structure (event.gbutton.*)
* Gamepad button event structure (event.gbutton.*)
*/
typedef struct SDL_GamepadButtonEvent
{
@ -450,17 +454,17 @@ typedef struct SDL_GamepadButtonEvent
/**
* \brief Gamepad device event structure (event.gdevice.*)
* Gamepad device event structure (event.gdevice.*)
*/
typedef struct SDL_GamepadDeviceEvent
{
Uint32 type; /**< ::SDL_EVENT_GAMEPAD_ADDED, ::SDL_EVENT_GAMEPAD_REMOVED, or ::SDL_EVENT_GAMEPAD_REMAPPED or ::SDL_EVENT_GAMEPAD_UPDATE_COMPLETE */
Uint32 type; /**< ::SDL_EVENT_GAMEPAD_ADDED, ::SDL_EVENT_GAMEPAD_REMOVED, or ::SDL_EVENT_GAMEPAD_REMAPPED, ::SDL_EVENT_GAMEPAD_UPDATE_COMPLETE or ::SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_JoystickID which; /**< The joystick instance id */
} SDL_GamepadDeviceEvent;
/**
* \brief Gamepad touchpad event structure (event.gtouchpad.*)
* Gamepad touchpad event structure (event.gtouchpad.*)
*/
typedef struct SDL_GamepadTouchpadEvent
{
@ -475,7 +479,7 @@ typedef struct SDL_GamepadTouchpadEvent
} SDL_GamepadTouchpadEvent;
/**
* \brief Gamepad sensor event structure (event.gsensor.*)
* Gamepad sensor event structure (event.gsensor.*)
*/
typedef struct SDL_GamepadSensorEvent
{
@ -488,7 +492,7 @@ typedef struct SDL_GamepadSensorEvent
} SDL_GamepadSensorEvent;
/**
* \brief Audio device event structure (event.adevice.*)
* Audio device event structure (event.adevice.*)
*/
typedef struct SDL_AudioDeviceEvent
{
@ -503,7 +507,7 @@ typedef struct SDL_AudioDeviceEvent
/**
* \brief Touch finger event structure (event.tfinger.*)
* Touch finger event structure (event.tfinger.*)
*/
typedef struct SDL_TouchFingerEvent
{
@ -516,27 +520,87 @@ typedef struct SDL_TouchFingerEvent
float dx; /**< Normalized in the range -1...1 */
float dy; /**< Normalized in the range -1...1 */
float pressure; /**< Normalized in the range 0...1 */
SDL_WindowID windowID;/**< The window underneath the finger, if any */
SDL_WindowID windowID; /**< The window underneath the finger, if any */
} SDL_TouchFingerEvent;
#define SDL_DROPEVENT_DATA_SIZE 64
/**
* \brief An event used to request a file open by the system (event.drop.*)
* This event is enabled by default, you can disable it with SDL_SetEventEnabled().
* \note If this event is enabled, you must free the filename in the event.
* Pressure-sensitive pen touched or stopped touching surface (event.ptip.*)
*/
typedef struct SDL_PenTipEvent
{
Uint32 type; /**< ::SDL_EVENT_PEN_DOWN or ::SDL_EVENT_PEN_UP */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
Uint32 windowID; /**< The window with pen focus, if any */
SDL_PenID which; /**< The pen instance id */
Uint8 tip; /**< ::SDL_PEN_TIP_INK when using a regular pen tip, or ::SDL_PEN_TIP_ERASER if the pen is being used as an eraser (e.g., flipped to use the eraser tip) */
Uint8 state; /**< ::SDL_PRESSED on ::SDL_EVENT_PEN_DOWN and ::SDL_RELEASED on ::SDL_EVENT_PEN_UP */
Uint16 pen_state; /**< Pen button masks (where SDL_BUTTON(1) is the first button, SDL_BUTTON(2) is the second button etc.),
::SDL_PEN_DOWN_MASK is set if the pen is touching the surface, and
::SDL_PEN_ERASER_MASK is set if the pen is (used as) an eraser. */
float x; /**< X coordinate, relative to window */
float y; /**< Y coordinate, relative to window */
float axes[SDL_PEN_NUM_AXES]; /**< Pen axes such as pressure and tilt (ordered as per ::SDL_PenAxis) */
} SDL_PenTipEvent;
/**
* Pressure-sensitive pen motion / pressure / angle event structure (event.pmotion.*)
*/
typedef struct SDL_PenMotionEvent
{
Uint32 type; /**< ::SDL_EVENT_PEN_MOTION */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
Uint32 windowID; /**< The window with pen focus, if any */
SDL_PenID which; /**< The pen instance id */
Uint8 padding1;
Uint8 padding2;
Uint16 pen_state; /**< Pen button masks (where SDL_BUTTON(1) is the first button, SDL_BUTTON(2) is the second button etc.),
::SDL_PEN_DOWN_MASK is set if the pen is touching the surface, and
::SDL_PEN_ERASER_MASK is set if the pen is (used as) an eraser. */
float x; /**< X coordinate, relative to window */
float y; /**< Y coordinate, relative to window */
float axes[SDL_PEN_NUM_AXES]; /**< Pen axes such as pressure and tilt (ordered as per ::SDL_PenAxis) */
} SDL_PenMotionEvent;
/**
* Pressure-sensitive pen button event structure (event.pbutton.*)
*/
typedef struct SDL_PenButtonEvent
{
Uint32 type; /**< ::SDL_EVENT_PEN_BUTTON_DOWN or ::SDL_EVENT_PEN_BUTTON_UP */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
Uint32 windowID; /**< The window with pen focus, if any */
SDL_PenID which; /**< The pen instance id */
Uint8 button; /**< The pen button index (1 represents the pen tip for compatibility with mouse events) */
Uint8 state; /**< ::SDL_PRESSED or ::SDL_RELEASED */
Uint16 pen_state; /**< Pen button masks (where SDL_BUTTON(1) is the first button, SDL_BUTTON(2) is the second button etc.),
::SDL_PEN_DOWN_MASK is set if the pen is touching the surface, and
::SDL_PEN_ERASER_MASK is set if the pen is (used as) an eraser. */
float x; /**< X coordinate, relative to window */
float y; /**< Y coordinate, relative to window */
float axes[SDL_PEN_NUM_AXES]; /**< Pen axes such as pressure and tilt (ordered as per ::SDL_PenAxis) */
} SDL_PenButtonEvent;
/**
* An event used to drop text or request a file open by the system (event.drop.*)
*
* The `data` is owned by SDL and should be copied if the application
* wants to hold onto it beyond the scope of handling this event.
*/
typedef struct SDL_DropEvent
{
Uint32 type; /**< ::SDL_EVENT_DROP_BEGIN or ::SDL_EVENT_DROP_FILE or ::SDL_EVENT_DROP_TEXT or ::SDL_EVENT_DROP_COMPLETE or ::SDL_EVENT_DROP_POSITION */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
char *file; /**< The file name, which should be freed with SDL_free(), is NULL on begin/complete */
SDL_WindowID windowID; /**< The window that was dropped on, if any */
float x; /**< X coordinate, relative to window (not on begin) */
float y; /**< Y coordinate, relative to window (not on begin) */
char *source; /**< The source app that sent this drop event, or NULL if that isn't available */
char *data; /**< The text for SDL_EVENT_DROP_TEXT and the file name for SDL_EVENT_DROP_FILE, NULL for other events */
} SDL_DropEvent;
/**
* \brief An event triggered when the clipboard contents have changed (event.clipboard.*)
* An event triggered when the clipboard contents have changed (event.clipboard.*)
*/
typedef struct SDL_ClipboardEvent
{
@ -545,19 +609,19 @@ typedef struct SDL_ClipboardEvent
} SDL_ClipboardEvent;
/**
* \brief Sensor event structure (event.sensor.*)
* Sensor event structure (event.sensor.*)
*/
typedef struct SDL_SensorEvent
{
Uint32 type; /**< ::SDL_EVENT_SENSOR_UPDATE */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_SensorID which; /**< The instance ID of the sensor */
SDL_SensorID which; /**< The instance ID of the sensor */
float data[6]; /**< Up to 6 values from the sensor - additional values can be queried using SDL_GetSensorData() */
Uint64 sensor_timestamp; /**< The timestamp of the sensor reading in nanoseconds, not necessarily synchronized with the system clock */
} SDL_SensorEvent;
/**
* \brief The "quit requested" event
* The "quit requested" event
*/
typedef struct SDL_QuitEvent
{
@ -566,46 +630,21 @@ typedef struct SDL_QuitEvent
} SDL_QuitEvent;
/**
* \brief OS Specific event
*/
typedef struct SDL_OSEvent
{
Uint32 type; /**< ::SDL_EVENT_QUIT */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
} SDL_OSEvent;
/**
* \brief A user-defined event type (event.user.*)
* A user-defined event type (event.user.*)
*/
typedef struct SDL_UserEvent
{
Uint32 type; /**< ::SDL_EVENT_USER through ::SDL_EVENT_LAST-1 */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_WindowID windowID;/**< The associated window if any */
SDL_WindowID windowID; /**< The associated window if any */
Sint32 code; /**< User defined event code */
void *data1; /**< User defined data pointer */
void *data2; /**< User defined data pointer */
} SDL_UserEvent;
struct SDL_SysWMmsg;
typedef struct SDL_SysWMmsg SDL_SysWMmsg;
/**
* \brief A video driver dependent system event (event.syswm.*)
* This event is disabled by default, you can enable it with SDL_SetEventEnabled()
*
* \note If you want to use this event, you should include SDL_syswm.h.
*/
typedef struct SDL_SysWMEvent
{
Uint32 type; /**< ::SDL_EVENT_SYSWM */
Uint64 timestamp; /**< In nanoseconds, populated using SDL_GetTicksNS() */
SDL_SysWMmsg *msg; /**< driver dependent data, defined in SDL_syswm.h */
} SDL_SysWMEvent;
/**
* \brief General event structure
* General event structure
*/
typedef union SDL_Event
{
@ -615,7 +654,6 @@ typedef union SDL_Event
SDL_WindowEvent window; /**< Window event data */
SDL_KeyboardEvent key; /**< Keyboard event data */
SDL_TextEditingEvent edit; /**< Text editing event data */
SDL_TextEditingExtEvent editExt; /**< Extended text editing event data */
SDL_TextInputEvent text; /**< Text input event data */
SDL_MouseMotionEvent motion; /**< Mouse motion event data */
SDL_MouseButtonEvent button; /**< Mouse button event data */
@ -634,10 +672,12 @@ typedef union SDL_Event
SDL_SensorEvent sensor; /**< Sensor event data */
SDL_QuitEvent quit; /**< Quit request event data */
SDL_UserEvent user; /**< Custom event data */
SDL_SysWMEvent syswm; /**< System dependent window event data */
SDL_TouchFingerEvent tfinger; /**< Touch finger event data */
SDL_PenTipEvent ptip; /**< Pen tip touching or leaving drawing surface */
SDL_PenMotionEvent pmotion; /**< Pen change in position, pressure, or angle */
SDL_PenButtonEvent pbutton; /**< Pen button press */
SDL_DropEvent drop; /**< Drag and drop event data */
SDL_ClipboardEvent clipboard; /**< Clipboard cancelled event data */
SDL_ClipboardEvent clipboard; /**< Clipboard event data */
/* This is necessary for ABI compatibility between Visual C++ and GCC.
Visual C++ will respect the push pack pragma and use 52 bytes (size of
@ -646,7 +686,7 @@ typedef union SDL_Event
largest datatype within the union, which is 8 bytes on 64-bit
architectures.
So... we'll add padding to force the size to be 56 bytes for both.
So... we'll add padding to force the size to be the same for both.
On architectures where pointers are 16 bytes, this needs rounding up to
the next multiple of 16, 64, and on architectures where pointers are
@ -731,9 +771,7 @@ typedef enum
* \sa SDL_PumpEvents
* \sa SDL_PushEvent
*/
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
SDL_eventaction action,
Uint32 minType, Uint32 maxType);
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents, SDL_eventaction action, Uint32 minType, Uint32 maxType);
/* @} */
/**
@ -852,18 +890,16 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
*
* \param event the SDL_Event structure to be filled with the next event from
* the queue, or NULL
* \returns 1 if there is a pending event or 0 if there are none available.
* \returns SDL_TRUE if this got an event or SDL_FALSE if there are none
* available.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetEventFilter
* \sa SDL_PeepEvents
* \sa SDL_PushEvent
* \sa SDL_SetEventFilter
* \sa SDL_WaitEvent
* \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
extern DECLSPEC SDL_bool SDLCALL SDL_PollEvent(SDL_Event *event);
/**
* Wait indefinitely for the next available event.
@ -876,16 +912,16 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
*
* \param event the SDL_Event structure to be filled in with the next event
* from the queue, or NULL
* \returns 1 on success or 0 if there was an error while waiting for events;
* call SDL_GetError() for more information.
* \returns SDL_TRUE on success or SDL_FALSE if there was an error while
* waiting for events; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_PushEvent
* \sa SDL_WaitEventTimeout
*/
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
extern DECLSPEC SDL_bool SDLCALL SDL_WaitEvent(SDL_Event *event);
/**
* Wait until the specified timeout (in milliseconds) for the next available
@ -904,17 +940,16 @@ extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
* from the queue, or NULL
* \param timeoutMS the maximum number of milliseconds to wait for the next
* available event
* \returns 1 on success or 0 if there was an error while waiting for events;
* call SDL_GetError() for more information. This also returns 0 if
* the timeout elapsed without an event arriving.
* \returns SDL_TRUE if this got an event or SDL_FALSE if the timeout elapsed
* without any events available.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_PushEvent
* \sa SDL_WaitEvent
*/
extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS);
extern DECLSPEC SDL_bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS);
/**
* Add an event to the event queue.
@ -948,7 +983,7 @@ extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeou
* \sa SDL_PollEvent
* \sa SDL_RegisterEvents
*/
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
/**
* A function pointer used for callbacks that watch the event queue.
@ -962,7 +997,7 @@ extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
* \sa SDL_SetEventFilter
* \sa SDL_AddEventWatch
*/
typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
typedef int (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event);
/**
* Set up a filter to process all events before they change internal state and
@ -1006,8 +1041,7 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
* \sa SDL_PeepEvents
* \sa SDL_PushEvent
*/
extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
void *userdata);
extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void *userdata);
/**
* Query the current event filter.
@ -1024,8 +1058,7 @@ extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
*
* \sa SDL_SetEventFilter
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
void **userdata);
extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter, void **userdata);
/**
* Add a callback to be triggered when an event is added to the event queue.
@ -1047,14 +1080,15 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
*
* \param filter an SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter`
* \returns 0 on success, or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_DelEventWatch
* \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
void *userdata);
extern DECLSPEC int SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void *userdata);
/**
* Remove an event watch callback added with SDL_AddEventWatch().
@ -1069,8 +1103,7 @@ extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
*
* \sa SDL_AddEventWatch
*/
extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
void *userdata);
extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter, void *userdata);
/**
* Run a specific filter function on the current event queue, removing any
@ -1088,8 +1121,7 @@ extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
* \sa SDL_GetEventFilter
* \sa SDL_SetEventFilter
*/
extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
void *userdata);
extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void *userdata);
/**
* Set the state of processing events by type.
@ -1135,6 +1167,20 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type);
*/
extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
/**
* Allocate dynamic memory for an SDL event
*
* You can use this to allocate memory for user events that will be
* automatically freed after the event is processed.
*
* \param size the amount of memory to allocate
* \returns a pointer to the memory allocated or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC void * SDLCALL SDL_AllocateEventMemory(size_t size);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}

8
include/SDL3/SDL_filesystem.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_filesystem.h
*
* \brief Include file for filesystem SDL API functions
* Include file for filesystem SDL API functions
*/
#ifndef SDL_filesystem_h_
@ -64,7 +64,7 @@ extern "C" {
* directory of the application as it is uncommon to store resources outside
* the executable. As such it is not a writable directory.
*
* The returned path is guaranteed to end with a path separator ('\' on
* The returned path is guaranteed to end with a path separator ('\\' on
* Windows, '/' on most other platforms).
*
* The pointer returned is owned by the caller. Please call SDL_free() on the
@ -120,7 +120,7 @@ extern DECLSPEC char *SDLCALL SDL_GetBasePath(void);
* - ...only use letters, numbers, and spaces. Avoid punctuation like "Game
* Name 2: Bad Guy's Revenge!" ... "Game Name 2" is sufficient.
*
* The returned path is guaranteed to end with a path separator ('\' on
* The returned path is guaranteed to end with a path separator ('\\' on
* Windows, '/' on most other platforms).
*
* The pointer returned is owned by the caller. Please call SDL_free() on the

155
include/SDL3/SDL_gamepad.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_gamepad.h
*
* \brief Include file for SDL gamepad event handling
* Include file for SDL gamepad event handling
*/
#ifndef SDL_gamepad_h_
@ -30,9 +30,10 @@
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_joystick.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_rwops.h>
#include <SDL3/SDL_sensor.h>
#include <SDL3/SDL_joystick.h>
#include <SDL3/SDL_begin_code.h>
/* Set up for C function definitions, even when using C++ */
@ -76,14 +77,31 @@ typedef enum
/**
* The list of buttons available on a gamepad
*
* For controllers that use a diamond pattern for the face buttons,
* the south/east/west/north buttons below correspond to the locations
* in the diamond pattern. For Xbox controllers, this would be A/B/X/Y,
* for Nintendo Switch controllers, this would be B/A/Y/X, for
* PlayStation controllers this would be Cross/Circle/Square/Triangle.
*
* For controllers that don't use a diamond pattern for the face buttons,
* the south/east/west/north buttons indicate the buttons labeled A, B,
* C, D, or 1, 2, 3, 4, or for controllers that aren't labeled, they are
* the primary, secondary, etc. buttons.
*
* The activate action is often the south button and the cancel action
* is often the east button, but in some regions this is reversed, so
* your game should allow remapping actions based on user preferences.
*
* You can query the labels for the face buttons using SDL_GetGamepadButtonLabel()
*/
typedef enum
{
SDL_GAMEPAD_BUTTON_INVALID = -1,
SDL_GAMEPAD_BUTTON_A,
SDL_GAMEPAD_BUTTON_B,
SDL_GAMEPAD_BUTTON_X,
SDL_GAMEPAD_BUTTON_Y,
SDL_GAMEPAD_BUTTON_SOUTH, /* Bottom face button (e.g. Xbox A button) */
SDL_GAMEPAD_BUTTON_EAST, /* Right face button (e.g. Xbox B button) */
SDL_GAMEPAD_BUTTON_WEST, /* Left face button (e.g. Xbox X button) */
SDL_GAMEPAD_BUTTON_NORTH, /* Top face button (e.g. Xbox Y button) */
SDL_GAMEPAD_BUTTON_BACK,
SDL_GAMEPAD_BUTTON_GUIDE,
SDL_GAMEPAD_BUTTON_START,
@ -95,15 +113,35 @@ typedef enum
SDL_GAMEPAD_BUTTON_DPAD_DOWN,
SDL_GAMEPAD_BUTTON_DPAD_LEFT,
SDL_GAMEPAD_BUTTON_DPAD_RIGHT,
SDL_GAMEPAD_BUTTON_MISC1, /* Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button) */
SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /* Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */
SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /* Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */
SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /* Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */
SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /* Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */
SDL_GAMEPAD_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */
SDL_GAMEPAD_BUTTON_MISC1, /* Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button) */
SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1, /* Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) */
SDL_GAMEPAD_BUTTON_LEFT_PADDLE1, /* Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) */
SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2, /* Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) */
SDL_GAMEPAD_BUTTON_LEFT_PADDLE2, /* Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) */
SDL_GAMEPAD_BUTTON_TOUCHPAD, /* PS4/PS5 touchpad button */
SDL_GAMEPAD_BUTTON_MAX
} SDL_GamepadButton;
/**
* The set of gamepad button labels
*
* This isn't a complete set, just the face buttons to make it easy to show button prompts.
*
* For a complete set, you should look at the button and gamepad type and have a set of symbols that work well with your art style.
*/
typedef enum
{
SDL_GAMEPAD_BUTTON_LABEL_UNKNOWN,
SDL_GAMEPAD_BUTTON_LABEL_A,
SDL_GAMEPAD_BUTTON_LABEL_B,
SDL_GAMEPAD_BUTTON_LABEL_X,
SDL_GAMEPAD_BUTTON_LABEL_Y,
SDL_GAMEPAD_BUTTON_LABEL_CROSS,
SDL_GAMEPAD_BUTTON_LABEL_CIRCLE,
SDL_GAMEPAD_BUTTON_LABEL_SQUARE,
SDL_GAMEPAD_BUTTON_LABEL_TRIANGLE
} SDL_GamepadButtonLabel;
/**
* The list of axes available on a gamepad
*
@ -111,7 +149,9 @@ typedef enum
* and are centered within ~8000 of zero, though advanced UI will allow users to set
* or autodetect the dead zone, which varies between gamepads.
*
* Trigger axis values range from 0 to SDL_JOYSTICK_AXIS_MAX.
* Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX
* (fully pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the
* same range that will be reported by the lower-level SDL_GetJoystickAxis().
*/
typedef enum
{
@ -273,25 +313,20 @@ extern DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file);
*/
extern DECLSPEC int SDLCALL SDL_ReloadGamepadMappings(void);
/**
* Get the number of mappings installed.
*
* \returns the number of mappings.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_GetNumGamepadMappings(void);
/**
* Get the mapping at a particular index.
*
* \param mapping_index mapping index
* \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
* the index is out of range.
* You must free the returned pointer with SDL_free() when you are done with
* it, but you do _not_ free each string in the array.
*
* \param count a pointer filled in with the number of mappings returned, can
* be NULL.
* \returns an array of the mapping strings, NULL-terminated. Must be freed
* with SDL_free(). Returns NULL on error.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC char * SDLCALL SDL_GetGamepadMappingForIndex(int mapping_index);
extern DECLSPEC char ** SDLCALL SDL_GetGamepadMappings(int *count);
/**
* Get the gamepad mapping string for a given GUID.
@ -554,6 +589,23 @@ extern DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromInstanceID(SDL_JoystickID
*/
extern DECLSPEC SDL_Gamepad *SDLCALL SDL_GetGamepadFromPlayerIndex(int player_index);
/**
* Get the properties associated with an opened gamepad.
*
* These properties are shared with the underlying joystick object.
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad()
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGamepadProperties(SDL_Gamepad *gamepad);
/**
* Get the instance ID of an opened gamepad.
*
@ -708,6 +760,19 @@ extern DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *gamepa
*/
extern DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad);
/**
* Get the Steam Input handle of an opened gamepad, if available.
*
* Returns an InputHandle_t for the gamepad that can be used with Steam Input
* API: https://partner.steamgames.com/doc/api/ISteamInput
*
* \param gamepad the gamepad object to query.
* \returns the gamepad handle, or 0 if unavailable.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC Uint64 SDLCALL SDL_GetGamepadSteamHandle(SDL_Gamepad *gamepad);
/**
* Get the battery level of a gamepad, if available.
*
@ -898,8 +963,12 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasAxis(SDL_Gamepad *gamepad, SDL_Ga
*
* The axis indices start at index 0.
*
* The state is a value ranging from -32768 to 32767. Triggers, however, range
* from 0 to 32767 (they never return a negative value).
* For thumbsticks, the state is a value ranging from -32768 (up/left) to
* 32767 (down/right).
*
* Triggers range from 0 when released to 32767 when fully pressed, and never
* return a negative value. Note that this differs from the value reported by
* the lower-level SDL_GetJoystickAxis(), which normally uses the full range.
*
* \param gamepad a gamepad
* \param axis an axis index (one of the SDL_GamepadAxis values)
@ -922,7 +991,7 @@ extern DECLSPEC Sint16 SDLCALL SDL_GetGamepadAxis(SDL_Gamepad *gamepad, SDL_Game
*
* \param str string representing a SDL_Gamepad axis
* \returns the SDL_GamepadButton enum corresponding to the input string, or
* `SDL_GAMEPAD_AXIS_INVALID` if no match was found.
* `SDL_GAMEPAD_BUTTON_INVALID` if no match was found.
*
* \since This function is available since SDL 3.0.0.
*/
@ -972,6 +1041,32 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad, SDL_
*/
extern DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_GamepadButton button);
/**
* Get the label of a button on a gamepad.
*
* \param type the type of gamepad to check
* \param button a button index (one of the SDL_GamepadButton values)
* \returns the SDL_GamepadButtonLabel enum corresponding to the button label
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetGamepadButtonLabel
*/
extern DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabelForType(SDL_GamepadType type, SDL_GamepadButton button);
/**
* Get the label of a button on a gamepad.
*
* \param gamepad a gamepad
* \param button a button index (one of the SDL_GamepadButton values)
* \returns the SDL_GamepadButtonLabel enum corresponding to the button label
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetGamepadButtonLabelForType
*/
extern DECLSPEC SDL_GamepadButtonLabel SDLCALL SDL_GetGamepadButtonLabel(SDL_Gamepad *gamepad, SDL_GamepadButton button);
/**
* Get the number of touchpads on a gamepad.
*

4
include/SDL3/SDL_guid.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_guid.h
*
* \brief Include file for handling ::SDL_GUID values.
* Include file for handling ::SDL_GUID values.
*/
#ifndef SDL_guid_h_

73
include/SDL3/SDL_haptic.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,8 +22,7 @@
/**
* \file SDL_haptic.h
*
* \brief The SDL haptic subsystem allows you to control haptic (force feedback)
* devices.
* The SDL haptic subsystem manages haptic (force feedback) devices.
*
* The basic usage is as follows:
* - Initialize the subsystem (::SDL_INIT_HAPTIC).
@ -131,7 +130,7 @@ extern "C" {
/**
* \typedef SDL_Haptic
*
* \brief The haptic structure used to identify an SDL haptic.
* The haptic structure used to identify an SDL haptic.
*
* \sa SDL_HapticOpen
* \sa SDL_HapticOpenFromJoystick
@ -154,7 +153,7 @@ typedef struct SDL_Haptic SDL_Haptic;
/* @{ */
/**
* \brief Constant effect supported.
* Constant effect supported.
*
* Constant haptic effect.
*
@ -163,7 +162,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_CONSTANT (1u<<0)
/**
* \brief Sine wave effect supported.
* Sine wave effect supported.
*
* Periodic haptic effect that simulates sine waves.
*
@ -172,7 +171,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_SINE (1u<<1)
/**
* \brief Left/Right effect supported.
* Left/Right effect supported.
*
* Haptic effect for direct control over high/low frequency motors.
*
@ -186,7 +185,7 @@ typedef struct SDL_Haptic SDL_Haptic;
/* #define SDL_HAPTIC_SQUARE (1<<2) */
/**
* \brief Triangle wave effect supported.
* Triangle wave effect supported.
*
* Periodic haptic effect that simulates triangular waves.
*
@ -195,7 +194,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_TRIANGLE (1u<<3)
/**
* \brief Sawtoothup wave effect supported.
* Sawtoothup wave effect supported.
*
* Periodic haptic effect that simulates saw tooth up waves.
*
@ -204,7 +203,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_SAWTOOTHUP (1u<<4)
/**
* \brief Sawtoothdown wave effect supported.
* Sawtoothdown wave effect supported.
*
* Periodic haptic effect that simulates saw tooth down waves.
*
@ -213,7 +212,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5)
/**
* \brief Ramp effect supported.
* Ramp effect supported.
*
* Ramp haptic effect.
*
@ -222,7 +221,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_RAMP (1u<<6)
/**
* \brief Spring effect supported - uses axes position.
* Spring effect supported - uses axes position.
*
* Condition haptic effect that simulates a spring. Effect is based on the
* axes position.
@ -232,7 +231,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_SPRING (1u<<7)
/**
* \brief Damper effect supported - uses axes velocity.
* Damper effect supported - uses axes velocity.
*
* Condition haptic effect that simulates dampening. Effect is based on the
* axes velocity.
@ -242,7 +241,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_DAMPER (1u<<8)
/**
* \brief Inertia effect supported - uses axes acceleration.
* Inertia effect supported - uses axes acceleration.
*
* Condition haptic effect that simulates inertia. Effect is based on the axes
* acceleration.
@ -252,7 +251,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_INERTIA (1u<<9)
/**
* \brief Friction effect supported - uses axes movement.
* Friction effect supported - uses axes movement.
*
* Condition haptic effect that simulates friction. Effect is based on the
* axes movement.
@ -262,7 +261,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_FRICTION (1u<<10)
/**
* \brief Custom effect is supported.
* Custom effect is supported.
*
* User defined custom haptic effect.
*/
@ -273,7 +272,7 @@ typedef struct SDL_Haptic SDL_Haptic;
/* These last few are features the device has, not effects */
/**
* \brief Device can set global gain.
* Device can set global gain.
*
* Device supports setting the global gain.
*
@ -282,7 +281,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_GAIN (1u<<12)
/**
* \brief Device can set autocenter.
* Device can set autocenter.
*
* Device supports setting autocenter.
*
@ -291,7 +290,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_AUTOCENTER (1u<<13)
/**
* \brief Device can be queried for effect status.
* Device can be queried for effect status.
*
* Device supports querying effect status.
*
@ -300,7 +299,7 @@ typedef struct SDL_Haptic SDL_Haptic;
#define SDL_HAPTIC_STATUS (1u<<14)
/**
* \brief Device can be paused.
* Device can be paused.
*
* Devices supports being paused.
*
@ -316,31 +315,33 @@ typedef struct SDL_Haptic SDL_Haptic;
/* @{ */
/**
* \brief Uses polar coordinates for the direction.
* Uses polar coordinates for the direction.
*
* \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_POLAR 0
/**
* \brief Uses cartesian coordinates for the direction.
* Uses cartesian coordinates for the direction.
*
* \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_CARTESIAN 1
/**
* \brief Uses spherical coordinates for the direction.
* Uses spherical coordinates for the direction.
*
* \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_SPHERICAL 2
/**
* \brief Use this value to play an effect on the steering wheel axis. This
* provides better compatibility across platforms and devices as SDL will guess
* the correct axis.
* \sa SDL_HapticDirection
* Use this value to play an effect on the steering wheel axis.
*
* This provides better compatibility across platforms and devices as SDL
* will guess the correct axis.
*
* \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_STEERING_AXIS 3
@ -353,7 +354,7 @@ typedef struct SDL_Haptic SDL_Haptic;
*/
/**
* \brief Used to play a device an infinite number of times.
* Used to play a device an infinite number of times.
*
* \sa SDL_HapticRunEffect
*/
@ -361,7 +362,7 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
* \brief Structure that represents a haptic direction.
* Structure that represents a haptic direction.
*
* This is the direction where the force comes from,
* instead of the direction in which the force is exerted.
@ -464,7 +465,7 @@ typedef struct SDL_HapticDirection
/**
* \brief A structure containing a template for a Constant effect.
* A structure containing a template for a Constant effect.
*
* This struct is exclusively for the ::SDL_HAPTIC_CONSTANT effect.
*
@ -499,7 +500,7 @@ typedef struct SDL_HapticConstant
} SDL_HapticConstant;
/**
* \brief A structure containing a template for a Periodic effect.
* A structure containing a template for a Periodic effect.
*
* The struct handles the following effects:
* - ::SDL_HAPTIC_SINE
@ -585,7 +586,7 @@ typedef struct SDL_HapticPeriodic
} SDL_HapticPeriodic;
/**
* \brief A structure containing a template for a Condition effect.
* A structure containing a template for a Condition effect.
*
* The struct handles the following effects:
* - ::SDL_HAPTIC_SPRING: Effect based on axes position.
@ -633,7 +634,7 @@ typedef struct SDL_HapticCondition
} SDL_HapticCondition;
/**
* \brief A structure containing a template for a Ramp effect.
* A structure containing a template for a Ramp effect.
*
* This struct is exclusively for the ::SDL_HAPTIC_RAMP effect.
*
@ -671,7 +672,7 @@ typedef struct SDL_HapticRamp
} SDL_HapticRamp;
/**
* \brief A structure containing a template for a Left/Right effect.
* A structure containing a template for a Left/Right effect.
*
* This struct is exclusively for the ::SDL_HAPTIC_LEFTRIGHT effect.
*
@ -696,7 +697,7 @@ typedef struct SDL_HapticLeftRight
} SDL_HapticLeftRight;
/**
* \brief A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
* A structure containing a template for the ::SDL_HAPTIC_CUSTOM effect.
*
* This struct is exclusively for the ::SDL_HAPTIC_CUSTOM effect.
*
@ -738,7 +739,7 @@ typedef struct SDL_HapticCustom
} SDL_HapticCustom;
/**
* \brief The generic template for any haptic effect.
* The generic template for any haptic effect.
*
* All values max at 32767 (0x7FFF). Signed values also can be negative.
* Time values unless specified otherwise are in milliseconds.

10
include/SDL3/SDL_hidapi.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_hidapi.h
*
* \brief Header file for SDL HIDAPI functions.
* Header file for SDL HIDAPI functions.
*
* This is an adaptation of the original HIDAPI interface by Alan Ott,
* and includes source code licensed under the following BSD license:
@ -71,13 +71,13 @@ extern "C" {
#endif
/**
* \brief A handle representing an open HID device
* A handle representing an open HID device
*/
struct SDL_hid_device_;
typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */
/**
* \brief HID underlying bus types.
* HID underlying bus types.
*/
typedef enum {
/** Unknown bus type */
@ -109,7 +109,7 @@ typedef enum {
/** hidapi info structure */
/**
* \brief Information about a connected HID device
* Information about a connected HID device
*/
typedef struct SDL_hid_device_info
{

744
include/SDL3/SDL_hints.h
View File

File diff suppressed because it is too large Load Diff

6
include/SDL3/SDL_init.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_init.h
*
* \brief Init and quit header for the SDL library
* Init and quit header for the SDL library
*/
#ifndef SDL_init_h_
@ -39,7 +39,7 @@ extern "C" {
/* As of version 0.5, SDL is loaded dynamically into the application */
/**
* \brief Initialization flags for SDL_Init and/or SDL_InitSubSystem
* Initialization flags for SDL_Init and/or SDL_InitSubSystem
*
* These are the flags which may be passed to SDL_Init(). You should
* specify the subsystems which you will be using in your application.

4
include/SDL3/SDL_intrin.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_intrin.h
*
* \brief Header file for CPU intrinsics for SDL
* Header file for CPU intrinsics for SDL
*/
#ifndef SDL_intrin_h_

23
include/SDL3/SDL_joystick.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_joystick.h
*
* \brief Include file for SDL joystick event handling
* Include file for SDL joystick event handling
*
* The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
* then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
@ -42,6 +42,7 @@
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_guid.h>
#include <SDL3/SDL_mutex.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_begin_code.h>
/* Set up for C function definitions, even when using C++ */
@ -342,7 +343,7 @@ typedef struct SDL_VirtualJoystickDesc
Uint16 product_id; /**< the USB product ID of this joystick */
Uint16 padding; /**< unused */
Uint32 button_mask; /**< A mask of which buttons are valid for this controller
e.g. (1 << SDL_GAMEPAD_BUTTON_A) */
e.g. (1 << SDL_GAMEPAD_BUTTON_SOUTH) */
Uint32 axis_mask; /**< A mask of which axes are valid for this controller
e.g. (1 << SDL_GAMEPAD_AXIS_LEFTX) */
const char *name; /**< the name of the joystick */
@ -358,7 +359,7 @@ typedef struct SDL_VirtualJoystickDesc
} SDL_VirtualJoystickDesc;
/**
* \brief The current version of the SDL_VirtualJoystickDesc structure
* The current version of the SDL_VirtualJoystickDesc structure
*/
#define SDL_VIRTUAL_JOYSTICK_DESC_VERSION 1
@ -456,6 +457,20 @@ extern DECLSPEC int SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick,
*/
extern DECLSPEC int SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value);
/**
* Get the properties associated with a joystick.
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick);
/**
* Get the implementation dependent name of a joystick.
*

9
include/SDL3/SDL_keyboard.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_keyboard.h
*
* \brief Include file for SDL keyboard event handling
* Include file for SDL keyboard event handling
*/
#ifndef SDL_keyboard_h_
@ -40,7 +40,7 @@ extern "C" {
#endif
/**
* \brief The SDL keysym structure, used in key events.
* The SDL keysym structure, used in key events.
*
* \note If you are looking for translated character input, see the ::SDL_EVENT_TEXT_INPUT event.
*/
@ -302,6 +302,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_TextInputShown(void);
/**
* Set the rectangle used to type Unicode text inputs.
*
* Native input methods will place a window with word suggestions near it,
* without covering the text being inputted.
*
* To start text input in a given location, this function is intended to be
* called before SDL_StartTextInput, although some platforms support moving
* the rectangle even while text input (and a composition) is active.

8
include/SDL3/SDL_keycode.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_keycode.h
*
* \brief Defines constants which identify keyboard keys and modifiers.
* Defines constants which identify keyboard keys and modifiers.
*/
#ifndef SDL_keycode_h_
@ -32,7 +32,7 @@
#include <SDL3/SDL_scancode.h>
/**
* \brief The SDL virtual key representation.
* The SDL virtual key representation.
*
* Values of this type are used to represent keyboard keys using the current
* layout of the keyboard. These values include Unicode values representing
@ -327,7 +327,7 @@ typedef enum
} SDL_KeyCode;
/**
* \brief Enumeration of valid key mods (possibly OR'd together).
* Enumeration of valid key mods (possibly OR'd together).
*/
typedef enum
{

4
include/SDL3/SDL_loadso.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_loadso.h
*
* \brief System dependent library loading routines
* System dependent library loading routines
*
* Some things to keep in mind:
* \li These functions only work on C function names. Other languages may

4
include/SDL3/SDL_locale.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_locale.h
*
* \brief Include file for SDL locale services
* Include file for SDL locale services
*/
#ifndef SDL_locale_h

15
include/SDL3/SDL_log.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_log.h
*
* \brief Simple log messages with categories and priorities.
* Simple log messages with categories and priorities.
*
* By default logs are quiet, but if you're debugging SDL you might want:
*
@ -47,14 +47,14 @@ extern "C" {
/**
* \brief The maximum size of a log message prior to SDL 2.0.24
* The maximum size of a log message prior to SDL 2.0.24
*
* As of 2.0.24 there is no limit to the length of SDL log messages.
*/
#define SDL_MAX_LOG_MESSAGE 4096
/**
* \brief The predefined log categories
* The predefined log categories
*
* By default the application category is enabled at the INFO level,
* the assert category is enabled at the WARN level, test is enabled
@ -97,7 +97,7 @@ typedef enum
} SDL_LogCategory;
/**
* \brief The predefined log priorities
* The predefined log priorities
*/
typedef enum
{
@ -163,8 +163,7 @@ extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void);
/**
* Log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO.
*
* = * \param fmt a printf() style message format string
*
* \param fmt a printf() style message format string
* \param ... additional parameters matching % tokens in the `fmt` string, if
* any
*
@ -352,7 +351,7 @@ extern DECLSPEC void SDLCALL SDL_LogMessage(int category,
*/
extern DECLSPEC void SDLCALL SDL_LogMessageV(int category,
SDL_LogPriority priority,
const char *fmt, va_list ap);
SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3);
/**
* The prototype for the log output callback function.

237
include/SDL3/SDL_main.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -23,11 +23,20 @@
#define SDL_main_h_
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_events.h>
/*
* For details on how SDL_main works, and how to use it, please refer to:
*
* https://wiki.libsdl.org/SDL3/README/main-functions
*
* (or docs/README-main-functions.md in the SDL source tree)
*/
/**
* \file SDL_main.h
*
* \brief Redefine main() on some platforms so that it is called by SDL.
* Redefine main() on some platforms so that it is called by SDL.
*/
#ifndef SDL_MAIN_HANDLED
@ -140,7 +149,7 @@
* \endcode
*/
#if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE)
#if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS)
#define main SDL_main
#endif
@ -149,11 +158,198 @@
extern "C" {
#endif
typedef int (SDLCALL *SDL_AppInit_func)(int argc, char *argv[]);
typedef int (SDLCALL *SDL_AppIterate_func)(void);
typedef int (SDLCALL *SDL_AppEvent_func)(const SDL_Event *event);
typedef void (SDLCALL *SDL_AppQuit_func)(void);
/**
* You can (optionally!) define SDL_MAIN_USE_CALLBACKS before including
* SDL_main.h, and then your application will _not_ have a standard
* "main" entry point. Instead, it will operate as a collection of
* functions that are called as necessary by the system. On some
* platforms, this is just a layer where SDL drives your program
* instead of your program driving SDL, on other platforms this might
* hook into the OS to manage the lifecycle. Programs on most platforms
* can use whichever approach they prefer, but the decision boils down
* to:
*
* - Using a standard "main" function: this works like it always has for
* the past 50+ years in C programming, and your app is in control.
* - Using the callback functions: this might clean up some code,
* avoid some #ifdef blocks in your program for some platforms, be more
* resource-friendly to the system, and possibly be the primary way to
* access some future platforms (but none require this at the moment).
*
* This is up to the app; both approaches are considered valid and supported
* ways to write SDL apps.
*
* If using the callbacks, don't define a "main" function. Instead, implement
* the functions listed below in your program.
*/
#ifdef SDL_MAIN_USE_CALLBACKS
/**
* App-implemented initial entry point for SDL_MAIN_USE_CALLBACKS apps.
*
* Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
* using a standard "main" function, you should not supply this.
*
* This function is called by SDL once, at startup. The function should
* initialize whatever is necessary, possibly create windows and open
* audio devices, etc. The `argc` and `argv` parameters work like they would
* with a standard "main" function.
*
* This function should not go into an infinite mainloop; it should do any
* one-time setup it requires and then return.
*
* If this function returns 0, the app will proceed to normal operation,
* and will begin receiving repeated calls to SDL_AppIterate and SDL_AppEvent
* for the life of the program. If this function 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 SDL calls SDL_AppQuit
* and terminates with an exit code that reports success to the platform.
*
* \param argc The standard ANSI C main's argc; number of elements in `argv`
* \param argv The standard ANSI C main's argv; array of command line arguments.
* \returns -1 to terminate with an error, 1 to terminate with success, 0 to continue.
*
* \threadsafety This function is not thread safe.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_AppIterate
* \sa SDL_AppEvent
* \sa SDL_AppQuit
*/
extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppInit(int argc, char *argv[]);
/**
* App-implemented iteration entry point for SDL_MAIN_USE_CALLBACKS apps.
*
* Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
* using a standard "main" function, you should not supply this.
*
* This function is called repeatedly by SDL after SDL_AppInit returns 0.
* The function should operate as a single iteration the program's primary
* loop; it should update whatever state it needs and draw a new frame of
* video, usually.
*
* On some platforms, this function will be called at the refresh rate of
* the display (which might change during the life of your app!). There are
* no promises made about what frequency this function might run at. You
* should use SDL's timer functions if you need to see how much time has
* passed since the last iteration.
*
* There is no need to process the SDL event queue during this function;
* SDL will send events as they arrive in SDL_AppEvent, and in most cases
* the event queue will be empty when this function runs anyhow.
*
* This function should not go into an infinite mainloop; it should do one
* iteration of whatever the program does and return.
*
* If this function returns 0, the app will continue normal operation,
* receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life
* of the program. If this function 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 SDL calls SDL_AppQuit and terminates with
* an exit code that reports success to the platform.
*
* \returns -1 to terminate with an error, 1 to terminate with success, 0 to continue.
*
* \threadsafety This function is not thread safe.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_AppInit
* \sa SDL_AppEvent
* \sa SDL_AppQuit
*/
extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppIterate(void);
/**
* App-implemented event entry point for SDL_MAIN_USE_CALLBACKS apps.
*
* Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
* using a standard "main" function, you should not supply this.
*
* This function is called as needed by SDL after SDL_AppInit returns 0;
* It is called once for each new event.
*
* There is (currently) no guarantee about what thread this will be called
* from; whatever thread pushes an event onto SDL's queue will trigger this
* function. SDL is responsible for pumping the event queue between
* each call to SDL_AppIterate, so in normal operation one should only
* get events in a serial fashion, but be careful if you have a thread that
* explicitly calls SDL_PushEvent.
*
* Events sent to this function are not owned by the app; if you need to
* save the data, you should copy it.
*
* You do not need to free event data (such as the `file` string in
* SDL_EVENT_DROP_FILE), as SDL will free it once this function returns.
* Note that this is different than one might expect when using a standard
* "main" function!
*
* This function should not go into an infinite mainloop; it should handle
* the provided event appropriately and return.
*
* If this function returns 0, the app will continue normal operation,
* receiving repeated calls to SDL_AppIterate and SDL_AppEvent for the life
* of the program. If this function 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 SDL calls SDL_AppQuit and terminates with
* an exit code that reports success to the platform.
*
* \returns -1 to terminate with an error, 1 to terminate with success, 0 to continue.
*
* \threadsafety This function is not thread safe.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_AppInit
* \sa SDL_AppIterate
* \sa SDL_AppQuit
*/
extern SDLMAIN_DECLSPEC int SDLCALL SDL_AppEvent(const SDL_Event *event);
/**
* App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps.
*
* Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If
* using a standard "main" function, you should not supply this.
*
* This function is called once by SDL before terminating the program.
*
* This function will be called no matter what, even if SDL_AppInit
* requests termination.
*
* This function should not go into an infinite mainloop; it should
* deinitialize any resources necessary, perform whatever shutdown
* activities, and return.
*
* You do not need to call SDL_Quit() in this function, as SDL will call
* it after this function returns and before the process terminates, but
* it is safe to do so.
*
* \threadsafety This function is not thread safe.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_AppInit
* \sa SDL_AppIterate
* \sa SDL_AppEvent
*/
extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void);
#endif /* SDL_MAIN_USE_CALLBACKS */
/**
* The prototype for the application's main() function
*/
typedef int (*SDL_main_func)(int argc, char *argv[]);
extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]);
typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]);
extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]);
/**
@ -198,6 +394,34 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
*/
extern DECLSPEC int SDLCALL SDL_RunApp(int argc, char* argv[], SDL_main_func mainFunction, void * reserved);
/**
* An entry point for SDL's use in SDL_MAIN_USE_CALLBACKS.
*
* Generally, you should not call this function directly. This only exists to
* hand off work into SDL as soon as possible, where it has a lot more control
* and functionality available, and make the inline code in SDL_main.h as
* small as possible.
*
* Not all platforms use this, it's actual use is hidden in a magic
* header-only library, and you should not call this directly unless you
* _really_ know what you're doing.
*
* \param argc standard Unix main argc
* \param argv standard Unix main argv
* \param appinit The application's SDL_AppInit function
* \param appiter The application's SDL_AppIterate function
* \param appevent The application's SDL_AppEvent function
* \param appquit The application's SDL_AppQuit function
* \returns standard Unix main return value
*
* \threadsafety It is not safe to call this anywhere except as the only
* function call in SDL_main.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char* argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit);
#if defined(__WIN32__) || defined(__GDK__)
/**
@ -282,7 +506,8 @@ extern DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void);
#if !defined(SDL_MAIN_HANDLED) && !defined(SDL_MAIN_NOIMPL)
/* include header-only SDL_main implementations */
#if defined(__WIN32__) || defined(__GDK__) || defined(__IOS__) || defined(__TVOS__) \
#if defined(SDL_MAIN_USE_CALLBACKS) \
|| defined(__WIN32__) || defined(__GDK__) || defined(__IOS__) || defined(__TVOS__) \
|| defined(__3DS__) || defined(__NGAGE__) || defined(__PS2__) || defined(__PSP__)
/* platforms which main (-equivalent) can be implemented in plain C */

59
include/SDL3/SDL_main_impl.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -41,6 +41,30 @@
# undef main
#endif /* main */
#ifdef SDL_MAIN_USE_CALLBACKS
#if 0
/* currently there are no platforms that _need_ a magic entry point here
for callbacks, but if one shows up, implement it here. */
#else /* use a standard SDL_main, which the app SHOULD NOT ALSO SUPPLY. */
/* this define makes the normal SDL_main entry point stuff work...we just provide SDL_main() instead of the app. */
#define SDL_MAIN_CALLBACK_STANDARD 1
int SDL_main(int argc, char **argv)
{
return SDL_EnterAppMainCallbacks(argc, argv, SDL_AppInit, SDL_AppIterate, SDL_AppEvent, SDL_AppQuit);
}
#endif /* platform-specific tests */
#endif /* SDL_MAIN_USE_CALLBACKS */
/* set up the usual SDL_main stuff if we're not using callbacks or if we are but need the normal entry point. */
#if !defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD)
#if defined(__WIN32__) || defined(__GDK__)
/* these defines/typedefs are needed for the WinMain() definition */
@ -48,12 +72,6 @@
#define WINAPI __stdcall
#endif
#include <SDL3/SDL_begin_code.h>
#ifdef __cplusplus
extern "C" {
#endif
typedef struct HINSTANCE__ * HINSTANCE;
typedef char* LPSTR;
typedef wchar_t* PWSTR;
@ -82,6 +100,10 @@ int main(int argc, char *argv[])
#endif /* _MSC_VER && ! __GDK__ */
/* This is where execution begins [windowed apps and GDK] */
#ifdef __cplusplus
extern "C" {
#endif
#if defined( UNICODE ) && UNICODE
int WINAPI wWinMain(HINSTANCE hInst, HINSTANCE hPrev, PWSTR szCmdLine, int sw)
#else /* ANSI */
@ -94,13 +116,10 @@ int WINAPI WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR szCmdLine, int sw)
(void)sw;
return SDL_RunApp(0, NULL, SDL_main, NULL);
}
#ifdef __cplusplus
} /* extern "C" */
#endif
#include <SDL3/SDL_close_code.h>
/* end of __WIN32__ and __GDK__ impls */
#elif defined(__WINRT__)
@ -151,10 +170,16 @@ int WINAPI WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR szCmdLine, int sw)
#pragma comment(lib, "runtimeobject.lib")
#endif
#ifdef __cplusplus
extern "C" {
#endif
int CALLBACK WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
{
return SDL_RunApp(0, NULL, SDL_main, NULL);
}
#ifdef __cplusplus
} /* extern "C" */
#endif
/* end of WinRT impl */
#elif defined(__NGAGE__)
@ -172,27 +197,17 @@ TInt E32Main()
#else /* platforms that use a standard main() and just call SDL_RunApp(), like iOS and 3DS */
#include <SDL3/SDL_begin_code.h>
#ifdef __cplusplus
extern "C" {
#endif
int main(int argc, char *argv[])
{
return SDL_RunApp(argc, argv, SDL_main, NULL);
}
#ifdef __cplusplus
} /* extern "C" */
#endif
#include <SDL3/SDL_close_code.h>
/* end of impls for standard-conforming platforms */
#endif /* __WIN32__ etc */
#endif /* !defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_CALLBACK_STANDARD) */
/* rename users main() function to SDL_main() so it can be called from the wrappers above */
#define main SDL_main

2
include/SDL3/SDL_messagebox.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages

6
include/SDL3/SDL_metal.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_metal.h
*
* \brief Header file for functions to creating Metal layers and views on SDL windows.
* Header file for functions to creating Metal layers and views on SDL windows.
*/
#ifndef SDL_metal_h_
@ -37,7 +37,7 @@ extern "C" {
#endif
/**
* \brief A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS).
* A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS).
*
* \note This can be cast directly to an NSView or UIView.
*/

4
include/SDL3/SDL_misc.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_misc.h
*
* \brief Include file for SDL API functions that don't fit elsewhere.
* Include file for SDL API functions that don't fit elsewhere.
*/
#ifndef SDL_misc_h_

16
include/SDL3/SDL_mouse.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_mouse.h
*
* \brief Include file for SDL mouse event handling.
* Include file for SDL mouse event handling.
*/
#ifndef SDL_mouse_h_
@ -43,7 +43,7 @@ typedef Uint32 SDL_MouseID;
typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */
/**
* \brief Cursor types for SDL_CreateSystemCursor().
* Cursor types for SDL_CreateSystemCursor().
*/
typedef enum
{
@ -59,11 +59,19 @@ typedef enum
SDL_SYSTEM_CURSOR_SIZEALL, /**< Four pointed arrow pointing north, south, east, and west */
SDL_SYSTEM_CURSOR_NO, /**< Slashed circle or crossbones */
SDL_SYSTEM_CURSOR_HAND, /**< Hand */
SDL_SYSTEM_CURSOR_WINDOW_TOPLEFT, /**< Window resize top-left (or SIZENWSE) */
SDL_SYSTEM_CURSOR_WINDOW_TOP, /**< Window resize top (or SIZENS) */
SDL_SYSTEM_CURSOR_WINDOW_TOPRIGHT, /**< Window resize top-right (or SIZENESW) */
SDL_SYSTEM_CURSOR_WINDOW_RIGHT, /**< Window resize right (or SIZEWE) */
SDL_SYSTEM_CURSOR_WINDOW_BOTTOMRIGHT, /**< Window resize bottom-right (or SIZENWSE) */
SDL_SYSTEM_CURSOR_WINDOW_BOTTOM, /**< Window resize bottom (or SIZENS) */
SDL_SYSTEM_CURSOR_WINDOW_BOTTOMLEFT, /**< Window resize bottom-left (or SIZENESW) */
SDL_SYSTEM_CURSOR_WINDOW_LEFT, /**< Window resize left (or SIZEWE) */
SDL_NUM_SYSTEM_CURSORS
} SDL_SystemCursor;
/**
* \brief Scroll direction types for the Scroll event
* Scroll direction types for the Scroll event
*/
typedef enum
{

73
include/SDL3/SDL_mutex.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -25,7 +25,7 @@
/**
* \file SDL_mutex.h
*
* \brief Functions to provide thread synchronization primitives.
* Functions to provide thread synchronization primitives.
*/
#include <SDL3/SDL_stdinc.h>
@ -121,11 +121,6 @@ extern "C" {
*/
#define SDL_MUTEX_TIMEDOUT 1
/**
* This is the timeout value which corresponds to never time out.
*/
#define SDL_MUTEX_MAXWAIT -1
/**
* \name Mutex functions
@ -169,13 +164,15 @@ extern DECLSPEC SDL_Mutex *SDLCALL SDL_CreateMutex(void);
* unlock it the same number of times before it is actually made available for
* other threads in the system (this is known as a "recursive mutex").
*
* This function does not fail; if mutex is NULL, it will return immediately
* having locked nothing. If the mutex is valid, this function will always
* block until it can lock the mutex, and return with it locked.
*
* \param mutex the mutex to lock
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mutex);
extern DECLSPEC void SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mutex);
/**
* Try to lock a mutex without blocking.
@ -186,9 +183,13 @@ extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mutex);
* This technique is useful if you need exclusive access to a resource but
* don't want to wait for it, and will return to it to try again later.
*
* This function does not fail; if mutex is NULL, it will return 0 immediately
* having locked nothing. If the mutex is valid, this function will always
* either lock the mutex and return 0, or return SDL_MUTEX_TIMEOUT and lock
* nothing.
*
* \param mutex the mutex to try to lock
* \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for
* more information.
* \returns 0 or `SDL_MUTEX_TIMEDOUT`
*
* \since This function is available since SDL 3.0.0.
*
@ -210,12 +211,10 @@ extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQUIRE(0
* thread, and doing so results in undefined behavior.
*
* \param mutex the mutex to unlock.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_Mutex *mutex) SDL_RELEASE(mutex);
extern DECLSPEC void SDLCALL SDL_UnlockMutex(SDL_Mutex *mutex) SDL_RELEASE(mutex);
/**
* Destroy a mutex created with SDL_CreateMutex().
@ -321,15 +320,17 @@ extern DECLSPEC SDL_RWLock *SDLCALL SDL_CreateRWLock(void);
* lock before requesting a read-only lock. (But, of course, if you have the
* write lock, you don't need further locks to read in any case.)
*
* This function does not fail; if rwlock is NULL, it will return immediately
* having locked nothing. If the rwlock is valid, this function will always
* block until it can lock the mutex, and return with it locked.
*
* \param rwlock the read/write lock to lock
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_UnlockRWLock
*/
extern DECLSPEC int SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SDL_ACQUIRE_SHARED(rwlock);
extern DECLSPEC void SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SDL_ACQUIRE_SHARED(rwlock);
/**
* Lock the read/write lock for _write_ operations.
@ -348,15 +349,17 @@ extern DECLSPEC int SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SDL_ACQ
* read-only lock. Doing so results in undefined behavior. Unlock the
* read-only lock before requesting a write lock.
*
* This function does not fail; if rwlock is NULL, it will return immediately
* having locked nothing. If the rwlock is valid, this function will always
* block until it can lock the mutex, and return with it locked.
*
* \param rwlock the read/write lock to lock
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_UnlockRWLock
*/
extern DECLSPEC int SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SDL_ACQUIRE(rwlock);
extern DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SDL_ACQUIRE(rwlock);
/**
* Try to lock a read/write lock _for reading_ without blocking.
@ -370,9 +373,13 @@ extern DECLSPEC int SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SDL_ACQ
* Trying to lock for read-only access can succeed if other threads are
* holding read-only locks, as this won't prevent access.
*
* This function does not fail; if rwlock is NULL, it will return 0
* immediately having locked nothing. If rwlock is valid, this function will
* always either lock the rwlock and return 0, or return SDL_RWLOCK_TIMEOUT
* and lock nothing.
*
* \param rwlock the rwlock to try to lock
* \returns 0, `SDL_RWLOCK_TIMEDOUT`, or -1 on error; call SDL_GetError() for
* more information.
* \returns 0 or `SDL_RWLOCK_TIMEDOUT`
*
* \since This function is available since SDL 3.0.0.
*
@ -400,9 +407,13 @@ extern DECLSPEC int SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) SDL_
* read-only lock. Doing so results in undefined behavior. Unlock the
* read-only lock before requesting a write lock.
*
* This function does not fail; if rwlock is NULL, it will return 0
* immediately having locked nothing. If rwlock is valid, this function will
* always either lock the rwlock and return 0, or return SDL_RWLOCK_TIMEOUT
* and lock nothing.
*
* \param rwlock the rwlock to try to lock
* \returns 0, `SDL_RWLOCK_TIMEDOUT`, or -1 on error; call SDL_GetError() for
* more information.
* \returns 0 or `SDL_RWLOCK_TIMEDOUT`
*
* \since This function is available since SDL 3.0.0.
*
@ -428,12 +439,10 @@ extern DECLSPEC int SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) SDL_
* thread, and doing so results in undefined behavior.
*
* \param rwlock the rwlock to unlock.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_UnlockRWLock(SDL_RWLock *rwlock) SDL_RELEASE_SHARED(rwlock);
extern DECLSPEC void SDLCALL SDL_UnlockRWLock(SDL_RWLock *rwlock) SDL_RELEASE_GENERIC(rwlock);
/**
* Destroy a read/write lock created with SDL_CreateRWLock().
@ -521,7 +530,7 @@ extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem);
* semaphore value.
*
* This function is the equivalent of calling SDL_WaitSemaphoreTimeout() with
* a time length of `SDL_MUTEX_MAXWAIT`.
* a time length of -1.
*
* \param sem the semaphore wait on
* \returns 0 on success or a negative error code on failure; call
@ -708,7 +717,7 @@ extern DECLSPEC int SDLCALL SDL_BroadcastCondition(SDL_Condition *cond);
* behavior.
*
* This function is the equivalent of calling SDL_WaitConditionTimeout() with
* a time length of `SDL_MUTEX_MAXWAIT`.
* a time length of -1.
*
* \param cond the condition variable to wait on
* \param mutex the mutex used to coordinate thread access
@ -740,8 +749,8 @@ extern DECLSPEC int SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mutex *mu
*
* \param cond the condition variable to wait on
* \param mutex the mutex used to coordinate thread access
* \param timeoutMS the maximum time to wait, in milliseconds, or
* `SDL_MUTEX_MAXWAIT` to wait indefinitely
* \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait
* indefinitely
* \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
* the condition is not signaled in the allotted time, or a negative
* error code on failure; call SDL_GetError() for more information.

66
include/SDL3/SDL_oldnames.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_oldnames.h
*
* \brief Definitions to ease transition from SDL2 code
* Definitions to ease transition from SDL2 code
*/
#ifndef SDL_oldnames_h_
@ -83,6 +83,7 @@
#define SDL_CONTROLLERDEVICEREMAPPED SDL_EVENT_GAMEPAD_REMAPPED
#define SDL_CONTROLLERDEVICEREMOVED SDL_EVENT_GAMEPAD_REMOVED
#define SDL_CONTROLLERSENSORUPDATE SDL_EVENT_GAMEPAD_SENSOR_UPDATE
#define SDL_CONTROLLERSTEAMHANDLEUPDATED SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED
#define SDL_CONTROLLERTOUCHPADDOWN SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN
#define SDL_CONTROLLERTOUCHPADMOTION SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION
#define SDL_CONTROLLERTOUCHPADUP SDL_EVENT_GAMEPAD_TOUCHPAD_UP
@ -91,8 +92,8 @@
#define SDL_ControllerDeviceEvent SDL_GamepadDeviceEvent
#define SDL_ControllerSensorEvent SDL_GamepadSensorEvent
#define SDL_ControllerTouchpadEvent SDL_GamepadTouchpadEvent
#define SDL_DISPLAYEVENT_CONNECTED SDL_EVENT_DISPLAY_CONNECTED
#define SDL_DISPLAYEVENT_DISCONNECTED SDL_EVENT_DISPLAY_DISCONNECTED
#define SDL_DISPLAYEVENT_CONNECTED SDL_EVENT_DISPLAY_ADDED
#define SDL_DISPLAYEVENT_DISCONNECTED SDL_EVENT_DISPLAY_REMOVED
#define SDL_DISPLAYEVENT_MOVED SDL_EVENT_DISPLAY_MOVED
#define SDL_DISPLAYEVENT_ORIENTATION SDL_EVENT_DISPLAY_ORIENTATION
#define SDL_DROPBEGIN SDL_EVENT_DROP_BEGIN
@ -124,7 +125,6 @@
#define SDL_RENDER_DEVICE_RESET SDL_EVENT_RENDER_DEVICE_RESET
#define SDL_RENDER_TARGETS_RESET SDL_EVENT_RENDER_TARGETS_RESET
#define SDL_SENSORUPDATE SDL_EVENT_SENSOR_UPDATE
#define SDL_SYSWMEVENT SDL_EVENT_SYSWM
#define SDL_TEXTEDITING SDL_EVENT_TEXT_EDITING
#define SDL_TEXTEDITING_EXT SDL_EVENT_TEXT_EDITING_EXT
#define SDL_TEXTINPUT SDL_EVENT_TEXT_INPUT
@ -148,7 +148,7 @@
#define SDL_WINDOWEVENT_SIZE_CHANGED SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED
#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_EVENT_WINDOW_TAKE_FOCUS
/* ##SDL_gamepad.h */
/* ##SDL_gamecontroller.h */
#define SDL_CONTROLLER_AXIS_INVALID SDL_GAMEPAD_AXIS_INVALID
#define SDL_CONTROLLER_AXIS_LEFTX SDL_GAMEPAD_AXIS_LEFTX
#define SDL_CONTROLLER_AXIS_LEFTY SDL_GAMEPAD_AXIS_LEFTY
@ -161,8 +161,8 @@
#define SDL_CONTROLLER_BINDTYPE_BUTTON SDL_GAMEPAD_BINDTYPE_BUTTON
#define SDL_CONTROLLER_BINDTYPE_HAT SDL_GAMEPAD_BINDTYPE_HAT
#define SDL_CONTROLLER_BINDTYPE_NONE SDL_GAMEPAD_BINDTYPE_NONE
#define SDL_CONTROLLER_BUTTON_A SDL_GAMEPAD_BUTTON_A
#define SDL_CONTROLLER_BUTTON_B SDL_GAMEPAD_BUTTON_B
#define SDL_CONTROLLER_BUTTON_A SDL_GAMEPAD_BUTTON_SOUTH
#define SDL_CONTROLLER_BUTTON_B SDL_GAMEPAD_BUTTON_EAST
#define SDL_CONTROLLER_BUTTON_BACK SDL_GAMEPAD_BUTTON_BACK
#define SDL_CONTROLLER_BUTTON_DPAD_DOWN SDL_GAMEPAD_BUTTON_DPAD_DOWN
#define SDL_CONTROLLER_BUTTON_DPAD_LEFT SDL_GAMEPAD_BUTTON_DPAD_LEFT
@ -182,8 +182,8 @@
#define SDL_CONTROLLER_BUTTON_RIGHTSTICK SDL_GAMEPAD_BUTTON_RIGHT_STICK
#define SDL_CONTROLLER_BUTTON_START SDL_GAMEPAD_BUTTON_START
#define SDL_CONTROLLER_BUTTON_TOUCHPAD SDL_GAMEPAD_BUTTON_TOUCHPAD
#define SDL_CONTROLLER_BUTTON_X SDL_GAMEPAD_BUTTON_X
#define SDL_CONTROLLER_BUTTON_Y SDL_GAMEPAD_BUTTON_Y
#define SDL_CONTROLLER_BUTTON_X SDL_GAMEPAD_BUTTON_WEST
#define SDL_CONTROLLER_BUTTON_Y SDL_GAMEPAD_BUTTON_NORTH
#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT
#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR
#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT
@ -222,6 +222,7 @@
#define SDL_GameControllerGetSensorData SDL_GetGamepadSensorData
#define SDL_GameControllerGetSensorDataRate SDL_GetGamepadSensorDataRate
#define SDL_GameControllerGetSerial SDL_GetGamepadSerial
#define SDL_GameControllerGetSteamHandle SDL_GetGamepadSteamHandle
#define SDL_GameControllerGetStringForAxis SDL_GetGamepadStringForAxis
#define SDL_GameControllerGetStringForButton SDL_GetGamepadStringForButton
#define SDL_GameControllerGetTouchpadFinger SDL_GetGamepadTouchpadFinger
@ -236,9 +237,7 @@
#define SDL_GameControllerIsSensorEnabled SDL_GamepadSensorEnabled
#define SDL_GameControllerMapping SDL_GetGamepadMapping
#define SDL_GameControllerMappingForGUID SDL_GetGamepadMappingForGUID
#define SDL_GameControllerMappingForIndex SDL_GetGamepadMappingForIndex
#define SDL_GameControllerName SDL_GetGamepadName
#define SDL_GameControllerNumMappings SDL_GetNumGamepadMappings
#define SDL_GameControllerOpen SDL_OpenGamepad
#define SDL_GameControllerPath SDL_GetGamepadPath
#define SDL_GameControllerRumble SDL_RumbleGamepad
@ -395,6 +394,7 @@
#define SDL_RenderDrawRectsF SDL_RenderRects
#define SDL_RenderFillRectF SDL_RenderFillRect
#define SDL_RenderFillRectsF SDL_RenderFillRects
#define SDL_RenderFlush SDL_FlushRenderer
#define SDL_RenderGetClipRect SDL_GetRenderClipRect
#define SDL_RenderGetLogicalSize SDL_GetRenderLogicalPresentation
#define SDL_RenderGetMetalCommandEncoder SDL_GetRenderMetalCommandEncoder
@ -462,10 +462,6 @@
#define SDL_UpperBlit SDL_BlitSurface
#define SDL_UpperBlitScaled SDL_BlitSurfaceScaled
/* ##SDL_system.h */
#define SDL_RenderGetD3D11Device SDL_GetRenderD3D11Device
#define SDL_RenderGetD3D9Device SDL_GetRenderD3D9Device
/* ##SDL_thread.h */
#define SDL_TLSCleanup SDL_CleanupTLS
#define SDL_TLSCreate SDL_CreateTLS
@ -524,23 +520,24 @@
#define SDL_AUDIODEVICEADDED SDL_AUDIODEVICEADDED_renamed_SDL_EVENT_AUDIO_DEVICE_ADDED
#define SDL_AUDIODEVICEREMOVED SDL_AUDIODEVICEREMOVED_renamed_SDL_EVENT_AUDIO_DEVICE_REMOVED
#define SDL_CLIPBOARDUPDATE SDL_CLIPBOARDUPDATE_renamed_SDL_EVENT_CLIPBOARD_UPDATE
#define SDL_CONTROLLERAXISMOTION SDL_CONTROLLERAXISMOTION_renamed_SDL_GAMEPADAXISMOTION
#define SDL_CONTROLLERBUTTONDOWN SDL_CONTROLLERBUTTONDOWN_renamed_SDL_GAMEPADBUTTONDOWN
#define SDL_CONTROLLERBUTTONUP SDL_CONTROLLERBUTTONUP_renamed_SDL_GAMEPADBUTTONUP
#define SDL_CONTROLLERAXISMOTION SDL_CONTROLLERAXISMOTION_renamed_SDL_EVENT_GAMEPAD_AXIS_MOTION
#define SDL_CONTROLLERBUTTONDOWN SDL_CONTROLLERBUTTONDOWN_renamed_SDL_EVENT_GAMEPAD_BUTTON_DOWN
#define SDL_CONTROLLERBUTTONUP SDL_CONTROLLERBUTTONUP_renamed_SDL_EVENT_GAMEPAD_BUTTON_UP
#define SDL_CONTROLLERDEVICEADDED SDL_CONTROLLERDEVICEADDED_renamed_SDL_EVENT_GAMEPAD_ADDED
#define SDL_CONTROLLERDEVICEREMAPPED SDL_CONTROLLERDEVICEREMAPPED_renamed_SDL_EVENT_GAMEPAD_REMAPPED
#define SDL_CONTROLLERDEVICEREMOVED SDL_CONTROLLERDEVICEREMOVED_renamed_SDL_EVENT_GAMEPAD_REMOVED
#define SDL_CONTROLLERSENSORUPDATE SDL_CONTROLLERSENSORUPDATE_renamed_SDL_GAMEPADSENSORUPDATE
#define SDL_CONTROLLERTOUCHPADDOWN SDL_CONTROLLERTOUCHPADDOWN_renamed_SDL_GAMEPADTOUCHPADDOWN
#define SDL_CONTROLLERTOUCHPADMOTION SDL_CONTROLLERTOUCHPADMOTION_renamed_SDL_GAMEPADTOUCHPADMOTION
#define SDL_CONTROLLERTOUCHPADUP SDL_CONTROLLERTOUCHPADUP_renamed_SDL_GAMEPADTOUCHPADUP
#define SDL_CONTROLLERSENSORUPDATE SDL_CONTROLLERSENSORUPDATE_renamed_SDL_EVENT_GAMEPAD_SENSOR_UPDATE
#define SDL_CONTROLLERSTEAMHANDLEUPDATED SDL_CONTROLLERSTEAMHANDLEUPDATED_renamed_SDL_EVENT_GAMEPAD_STEAM_HANDLE_UPDATED
#define SDL_CONTROLLERTOUCHPADDOWN SDL_CONTROLLERTOUCHPADDOWN_renamed_SDL_EVENT_GAMEPAD_TOUCHPAD_DOWN
#define SDL_CONTROLLERTOUCHPADMOTION SDL_CONTROLLERTOUCHPADMOTION_renamed_SDL_EVENT_GAMEPAD_TOUCHPAD_MOTION
#define SDL_CONTROLLERTOUCHPADUP SDL_CONTROLLERTOUCHPADUP_renamed_SDL_EVENT_GAMEPAD_TOUCHPAD_UP
#define SDL_ControllerAxisEvent SDL_ControllerAxisEvent_renamed_SDL_GamepadAxisEvent
#define SDL_ControllerButtonEvent SDL_ControllerButtonEvent_renamed_SDL_GamepadButtonEvent
#define SDL_ControllerDeviceEvent SDL_ControllerDeviceEvent_renamed_SDL_GamepadDeviceEvent
#define SDL_ControllerSensorEvent SDL_ControllerSensorEvent_renamed_SDL_GamepadSensorEvent
#define SDL_ControllerTouchpadEvent SDL_ControllerTouchpadEvent_renamed_SDL_GamepadTouchpadEvent
#define SDL_DISPLAYEVENT_CONNECTED SDL_DISPLAYEVENT_CONNECTED_renamed_SDL_EVENT_DISPLAY_CONNECTED
#define SDL_DISPLAYEVENT_DISCONNECTED SDL_DISPLAYEVENT_DISCONNECTED_renamed_SDL_EVENT_DISPLAY_DISCONNECTED
#define SDL_DISPLAYEVENT_CONNECTED SDL_DISPLAYEVENT_CONNECTED_renamed_SDL_EVENT_DISPLAY_ADDED
#define SDL_DISPLAYEVENT_DISCONNECTED SDL_DISPLAYEVENT_DISCONNECTED_renamed_SDL_EVENT_DISPLAY_REMOVED
#define SDL_DISPLAYEVENT_MOVED SDL_DISPLAYEVENT_MOVED_renamed_SDL_EVENT_DISPLAY_MOVED
#define SDL_DISPLAYEVENT_ORIENTATION SDL_DISPLAYEVENT_ORIENTATION_renamed_SDL_EVENT_DISPLAY_ORIENTATION
#define SDL_DROPBEGIN SDL_DROPBEGIN_renamed_SDL_EVENT_DROP_BEGIN
@ -572,7 +569,6 @@
#define SDL_RENDER_DEVICE_RESET SDL_RENDER_DEVICE_RESET_renamed_SDL_EVENT_RENDER_DEVICE_RESET
#define SDL_RENDER_TARGETS_RESET SDL_RENDER_TARGETS_RESET_renamed_SDL_EVENT_RENDER_TARGETS_RESET
#define SDL_SENSORUPDATE SDL_SENSORUPDATE_renamed_SDL_EVENT_SENSOR_UPDATE
#define SDL_SYSWMEVENT SDL_SYSWMEVENT_renamed_SDL_EVENT_SYSWM
#define SDL_TEXTEDITING SDL_TEXTEDITING_renamed_SDL_EVENT_TEXT_EDITING
#define SDL_TEXTEDITING_EXT SDL_TEXTEDITING_EXT_renamed_SDL_EVENT_TEXT_EDITING_EXT
#define SDL_TEXTINPUT SDL_TEXTINPUT_renamed_SDL_EVENT_TEXT_INPUT
@ -596,7 +592,7 @@
#define SDL_WINDOWEVENT_SIZE_CHANGED SDL_WINDOWEVENT_SIZE_CHANGED_renamed_SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED
#define SDL_WINDOWEVENT_TAKE_FOCUS SDL_WINDOWEVENT_TAKE_FOCUS_renamed_SDL_EVENT_WINDOW_TAKE_FOCUS
/* ##SDL_gamepad.h */
/* ##SDL_gamecontroller.h */
#define SDL_CONTROLLER_AXIS_INVALID SDL_CONTROLLER_AXIS_INVALID_renamed_SDL_GAMEPAD_AXIS_INVALID
#define SDL_CONTROLLER_AXIS_LEFTX SDL_CONTROLLER_AXIS_LEFTX_renamed_SDL_GAMEPAD_AXIS_LEFTX
#define SDL_CONTROLLER_AXIS_LEFTY SDL_CONTROLLER_AXIS_LEFTY_renamed_SDL_GAMEPAD_AXIS_LEFTY
@ -609,8 +605,8 @@
#define SDL_CONTROLLER_BINDTYPE_BUTTON SDL_CONTROLLER_BINDTYPE_BUTTON_renamed_SDL_GAMEPAD_BINDTYPE_BUTTON
#define SDL_CONTROLLER_BINDTYPE_HAT SDL_CONTROLLER_BINDTYPE_HAT_renamed_SDL_GAMEPAD_BINDTYPE_HAT
#define SDL_CONTROLLER_BINDTYPE_NONE SDL_CONTROLLER_BINDTYPE_NONE_renamed_SDL_GAMEPAD_BINDTYPE_NONE
#define SDL_CONTROLLER_BUTTON_A SDL_CONTROLLER_BUTTON_A_renamed_SDL_GAMEPAD_BUTTON_A
#define SDL_CONTROLLER_BUTTON_B SDL_CONTROLLER_BUTTON_B_renamed_SDL_GAMEPAD_BUTTON_B
#define SDL_CONTROLLER_BUTTON_A SDL_CONTROLLER_BUTTON_A_renamed_SDL_GAMEPAD_BUTTON_SOUTH
#define SDL_CONTROLLER_BUTTON_B SDL_CONTROLLER_BUTTON_B_renamed_SDL_GAMEPAD_BUTTON_EAST
#define SDL_CONTROLLER_BUTTON_BACK SDL_CONTROLLER_BUTTON_BACK_renamed_SDL_GAMEPAD_BUTTON_BACK
#define SDL_CONTROLLER_BUTTON_DPAD_DOWN SDL_CONTROLLER_BUTTON_DPAD_DOWN_renamed_SDL_GAMEPAD_BUTTON_DPAD_DOWN
#define SDL_CONTROLLER_BUTTON_DPAD_LEFT SDL_CONTROLLER_BUTTON_DPAD_LEFT_renamed_SDL_GAMEPAD_BUTTON_DPAD_LEFT
@ -630,8 +626,8 @@
#define SDL_CONTROLLER_BUTTON_RIGHTSTICK SDL_CONTROLLER_BUTTON_RIGHTSTICK_renamed_SDL_GAMEPAD_BUTTON_RIGHT_STICK
#define SDL_CONTROLLER_BUTTON_START SDL_CONTROLLER_BUTTON_START_renamed_SDL_GAMEPAD_BUTTON_START
#define SDL_CONTROLLER_BUTTON_TOUCHPAD SDL_CONTROLLER_BUTTON_TOUCHPAD_renamed_SDL_GAMEPAD_BUTTON_TOUCHPAD
#define SDL_CONTROLLER_BUTTON_X SDL_CONTROLLER_BUTTON_X_renamed_SDL_GAMEPAD_BUTTON_X
#define SDL_CONTROLLER_BUTTON_Y SDL_CONTROLLER_BUTTON_Y_renamed_SDL_GAMEPAD_BUTTON_Y
#define SDL_CONTROLLER_BUTTON_X SDL_CONTROLLER_BUTTON_X_renamed_SDL_GAMEPAD_BUTTON_WEST
#define SDL_CONTROLLER_BUTTON_Y SDL_CONTROLLER_BUTTON_Y_renamed_SDL_GAMEPAD_BUTTON_NORTH
#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT_renamed_SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT
#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR_renamed_SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR
#define SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT_renamed_SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT
@ -670,6 +666,7 @@
#define SDL_GameControllerGetSensorData SDL_GameControllerGetSensorData_renamed_SDL_GetGamepadSensorData
#define SDL_GameControllerGetSensorDataRate SDL_GameControllerGetSensorDataRate_renamed_SDL_GetGamepadSensorDataRate
#define SDL_GameControllerGetSerial SDL_GameControllerGetSerial_renamed_SDL_GetGamepadSerial
#define SDL_GameControllerGetSteamHandle SDL_GameControllerGetSteamHandle_renamed_SDL_GetGamepadSteamHandle
#define SDL_GameControllerGetStringForAxis SDL_GameControllerGetStringForAxis_renamed_SDL_GetGamepadStringForAxis
#define SDL_GameControllerGetStringForButton SDL_GameControllerGetStringForButton_renamed_SDL_GetGamepadStringForButton
#define SDL_GameControllerGetTouchpadFinger SDL_GameControllerGetTouchpadFinger_renamed_SDL_GetGamepadTouchpadFinger
@ -685,9 +682,7 @@
#define SDL_GameControllerMapping SDL_GameControllerMapping_renamed_SDL_GetGamepadMapping
#define SDL_GameControllerMappingForDeviceIndex SDL_GameControllerMappingForDeviceIndex_renamed_SDL_GetGamepadMappingForDeviceIndex
#define SDL_GameControllerMappingForGUID SDL_GameControllerMappingForGUID_renamed_SDL_GetGamepadMappingForGUID
#define SDL_GameControllerMappingForIndex SDL_GameControllerMappingForIndex_renamed_SDL_GetGamepadMappingForIndex
#define SDL_GameControllerName SDL_GameControllerName_renamed_SDL_GetGamepadName
#define SDL_GameControllerNumMappings SDL_GameControllerNumMappings_renamed_SDL_GetNumGamepadMappings
#define SDL_GameControllerOpen SDL_GameControllerOpen_renamed_SDL_OpenGamepad
#define SDL_GameControllerPath SDL_GameControllerPath_renamed_SDL_GetGamepadPath
#define SDL_GameControllerRumble SDL_GameControllerRumble_renamed_SDL_RumbleGamepad
@ -844,6 +839,7 @@
#define SDL_RenderDrawRectsF SDL_RenderDrawRectsF_renamed_SDL_RenderRects
#define SDL_RenderFillRectF SDL_RenderFillRectF_renamed_SDL_RenderFillRect
#define SDL_RenderFillRectsF SDL_RenderFillRectsF_renamed_SDL_RenderFillRects
#define SDL_RenderFlush SDL_RenderFlush_renamed_SDL_FlushRenderer
#define SDL_RenderGetClipRect SDL_RenderGetClipRect_renamed_SDL_GetRenderClipRect
#define SDL_RenderGetLogicalSize SDL_RenderGetLogicalSize_renamed_SDL_GetRenderLogicalPresentation
#define SDL_RenderGetMetalCommandEncoder SDL_RenderGetMetalCommandEncoder_renamed_SDL_GetRenderMetalCommandEncoder
@ -911,10 +907,6 @@
#define SDL_UpperBlit SDL_UpperBlit_renamed_SDL_BlitSurface
#define SDL_UpperBlitScaled SDL_UpperBlitScaled_renamed_SDL_BlitSurfaceScaled
/* ##SDL_system.h */
#define SDL_RenderGetD3D11Device SDL_RenderGetD3D11Device_renamed_SDL_GetRenderD3D11Device
#define SDL_RenderGetD3D9Device SDL_RenderGetD3D9Device_renamed_SDL_GetRenderD3D9Device
/* ##SDL_thread.h */
#define SDL_TLSCleanup SDL_TLSCleanup_renamed_SDL_CleanupTLS
#define SDL_TLSCreate SDL_TLSCreate_renamed_SDL_CreateTLS

4
include/SDL3/SDL_opengl.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_opengl.h
*
* \brief This is a simple file to encapsulate the OpenGL API headers.
* This is a simple file to encapsulate the OpenGL API headers.
*/
/**

4
include/SDL3/SDL_opengles.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_opengles.h
*
* \brief This is a simple file to encapsulate the OpenGL ES 1.X API headers.
* This is a simple file to encapsulate the OpenGL ES 1.X API headers.
*/
#include <SDL3/SDL_platform_defines.h>

4
include/SDL3/SDL_opengles2.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_opengles2.h
*
* \brief This is a simple file to encapsulate the OpenGL ES 2.0 API headers.
* This is a simple file to encapsulate the OpenGL ES 2.0 API headers.
*/
#include <SDL3/SDL_platform_defines.h>

285
include/SDL3/SDL_pen.h Normal file
View File

@ -0,0 +1,285 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_pen.h
*
* Include file for SDL pen event handling.
*
* This file describes operations for pressure-sensitive pen (stylus and/or eraser) handling, e.g., for input
* and drawing tablets or suitably equipped mobile / tablet devices.
*
* To get started with pens:
* - Listen to ::SDL_PenMotionEvent and ::SDL_PenButtonEvent
* - To avoid treating pen events as mouse events, ignore ::SDL_MouseMotionEvent and ::SDL_MouseButtonEvent
* whenever "which" == ::SDL_PEN_MOUSEID.
*
* This header file describes advanced functionality that can be useful for managing user configuration
* and understanding the capabilities of the attached pens.
*
* We primarily identify pens by ::SDL_PenID. The implementation makes a best effort to relate each :SDL_PenID
* to the same physical device during a session. Formerly valid ::SDL_PenID values remain valid
* even if a device disappears.
*
* For identifying pens across sessions, the API provides the type ::SDL_GUID .
*/
#ifndef SDL_pen_h_
#define SDL_pen_h_
#include "SDL_error.h"
#include "SDL_guid.h"
#include "SDL_stdinc.h"
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {
#endif
typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a session */
#define SDL_PEN_INVALID ((Uint32)0) /**< Reserved invalid ::SDL_PenID is valid */
#define SDL_PEN_MOUSEID ((Uint32)-2) /**< Device ID for mouse events triggered by pen events */
#define SDL_PEN_INFO_UNKNOWN (-1) /**< Marks unknown information when querying the pen */
/**
* Pen axis indices
*
* Below are the valid indices to the "axis" array from ::SDL_PenMotionEvent and ::SDL_PenButtonEvent.
* The axis indices form a contiguous range of ints from 0 to ::SDL_PEN_AXIS_LAST, inclusive.
* All "axis[]" entries are either normalised to 0..1 or report a (positive or negative)
* angle in degrees, with 0.0 representing the centre.
* Not all pens/backends support all axes: unsupported entries are always "0.0f".
*
* To convert angles for tilt and rotation into vector representation, use
* SDL_sinf on the XTILT, YTILT, or ROTATION component, e.g., "SDL_sinf(xtilt * SDL_PI_F / 180.0)".
*/
typedef enum
{
SDL_PEN_AXIS_PRESSURE = 0, /**< Pen pressure. Unidirectional: 0..1.0 */
SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0..90.0 (left-to-right).
The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo */
SDL_PEN_AXIS_YTILT, /**< Pen vertical tilt angle. Bidirectional: -90.0..90.0 (top-to-down).
The physical max/min tilt may be smaller than -90.0 / 90.0, cf. SDL_PenCapabilityInfo */
SDL_PEN_AXIS_DISTANCE, /**< Pen distance to drawing surface. Unidirectional: 0.0..1.0 */
SDL_PEN_AXIS_ROTATION, /**< Pen barrel rotation. Bidirectional: -180..179.9 (clockwise, 0 is facing up, -180.0 is facing down). */
SDL_PEN_AXIS_SLIDER, /**< Pen finger wheel or slider (e.g., Airbrush Pen). Unidirectional: 0..1.0 */
SDL_PEN_NUM_AXES, /**< Last valid axis index */
SDL_PEN_AXIS_LAST = SDL_PEN_NUM_AXES - 1 /**< Last axis index plus 1 */
} SDL_PenAxis;
/* Pen flags. These share a bitmask space with ::SDL_BUTTON_LEFT and friends. */
#define SDL_PEN_FLAG_DOWN_BIT_INDEX 13 /* Bit for storing that pen is touching the surface */
#define SDL_PEN_FLAG_INK_BIT_INDEX 14 /* Bit for storing has-non-eraser-capability status */
#define SDL_PEN_FLAG_ERASER_BIT_INDEX 15 /* Bit for storing is-eraser or has-eraser-capability property */
#define SDL_PEN_FLAG_AXIS_BIT_OFFSET 16 /* Bit for storing has-axis-0 property */
#define SDL_PEN_CAPABILITY(capbit) (1ul << (capbit))
#define SDL_PEN_AXIS_CAPABILITY(axis) SDL_PEN_CAPABILITY((axis) + SDL_PEN_FLAG_AXIS_BIT_OFFSET)
/**
* Pen tips
* @{
*/
#define SDL_PEN_TIP_INK SDL_PEN_FLAG_INK_BIT_INDEX /**< Regular pen tip (for drawing) touched the surface */
#define SDL_PEN_TIP_ERASER SDL_PEN_FLAG_ERASER_BIT_INDEX /**< Eraser pen tip touched the surface */
/** @} */
/**
* \defgroup SDL_PEN_CAPABILITIES Pen capabilities
* Pen capabilities reported by ::SDL_GetPenCapabilities
* @{
*/
#define SDL_PEN_DOWN_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_DOWN_BIT_INDEX) /**< Pen tip is currently touching the drawing surface. */
#define SDL_PEN_INK_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_INK_BIT_INDEX) /**< Pen has a regular drawing tip (::SDL_GetPenCapabilities). For events (::SDL_PenButtonEvent, ::SDL_PenMotionEvent, ::SDL_GetPenStatus) this flag is mutually exclusive with ::SDL_PEN_ERASER_MASK . */
#define SDL_PEN_ERASER_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_ERASER_BIT_INDEX) /**< Pen has an eraser tip (::SDL_GetPenCapabilities) or is being used as eraser (::SDL_PenButtonEvent , ::SDL_PenMotionEvent , ::SDL_GetPenStatus) */
#define SDL_PEN_AXIS_PRESSURE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE) /**< Pen provides pressure information in axis ::SDL_PEN_AXIS_PRESSURE */
#define SDL_PEN_AXIS_XTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_XTILT) /**< Pen provides horizontal tilt information in axis ::SDL_PEN_AXIS_XTILT */
#define SDL_PEN_AXIS_YTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_YTILT) /**< Pen provides vertical tilt information in axis ::SDL_PEN_AXIS_YTILT */
#define SDL_PEN_AXIS_DISTANCE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_DISTANCE) /**< Pen provides distance to drawing tablet in ::SDL_PEN_AXIS_DISTANCE */
#define SDL_PEN_AXIS_ROTATION_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_ROTATION) /**< Pen provides barrel rotation information in axis ::SDL_PEN_AXIS_ROTATION */
#define SDL_PEN_AXIS_SLIDER_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_SLIDER) /**< Pen provides slider / finger wheel or similar in axis ::SDL_PEN_AXIS_SLIDER */
#define SDL_PEN_AXIS_BIDIRECTIONAL_MASKS (SDL_PEN_AXIS_XTILT_MASK | SDL_PEN_AXIS_YTILT_MASK)
/**< Masks for all axes that may be bidirectional */
/** @} */
/**
* Pen types
*
* Some pens identify as a particular type of drawing device (e.g., an airbrush or a pencil).
*
*/
typedef enum
{
SDL_PEN_TYPE_ERASER = 1, /**< Eraser */
SDL_PEN_TYPE_PEN, /**< Generic pen; this is the default. */
SDL_PEN_TYPE_PENCIL, /**< Pencil */
SDL_PEN_TYPE_BRUSH, /**< Brush-like device */
SDL_PEN_TYPE_AIRBRUSH, /**< Airbrush device that "sprays" ink */
SDL_PEN_TYPE_LAST = SDL_PEN_TYPE_AIRBRUSH /**< Last valid pen type */
} SDL_PenSubtype;
/* Function prototypes */
/**
* Retrieves all pens that are connected to the system.
*
* Yields an array of ::SDL_PenID values. These identify and track pens
* throughout a session. To track pens across sessions (program restart), use
* ::SDL_GUID .
*
* \param count The number of pens in the array (number of array elements
* minus 1, i.e., not counting the terminator 0).
* \returns A 0 terminated array of ::SDL_PenID values, or NULL on error. The
* array must be freed with ::SDL_free(). On a NULL return,
* ::SDL_GetError() is set.
*
* \since This function is available since SDL 3.0.0
*/
extern DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count);
/**
* Retrieves the pen's current status.
*
* If the pen is detached (cf. ::SDL_PenConnected), this operation may return
* default values.
*
* \param instance_id The pen to query.
* \param x Out-mode parameter for pen x coordinate. May be NULL.
* \param y Out-mode parameter for pen y coordinate. May be NULL.
* \param axes Out-mode parameter for axis information. May be null. The axes
* are in the same order as ::SDL_PenAxis.
* \param num_axes Maximum number of axes to write to "axes".
* \returns a bit mask with the current pen button states (::SDL_BUTTON_LMASK
* etc.), possibly ::SDL_PEN_DOWN_MASK, and exactly one of
* ::SDL_PEN_INK_MASK or ::SDL_PEN_ERASER_MASK , or 0 on error (see
* ::SDL_GetError()).
*
* \since This function is available since SDL 3.0.0
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x, float *y, float *axes, size_t num_axes);
/**
* Retrieves an ::SDL_PenID for the given ::SDL_GUID.
*
* \param guid A pen GUID.
* \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching
* SDL_PenID.
*
* \since This function is available since SDL 3.0.0
*
* \sa SDL_GUID
*/
extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
/**
* Retrieves the ::SDL_GUID for a given ::SDL_PenID.
*
* \param instance_id The pen to query.
* \returns The corresponding pen GUID; persistent across multiple sessions.
* If "instance_id" is ::SDL_PEN_INVALID, returns an all-zeroes GUID.
*
* \since This function is available since SDL 3.0.0
*
* \sa SDL_PenForID
*/
extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id);
/**
* Checks whether a pen is still attached.
*
* If a pen is detached, it will not show up for ::SDL_GetPens(). Other
* operations will still be available but may return default values.
*
* \param instance_id A pen ID.
* \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is
* attached, or SDL_FALSE otherwise.
*
* \since This function is available since SDL 3.0.0
*/
extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
/**
* Retrieves a human-readable description for a ::SDL_PenID.
*
* \param instance_id The pen to query.
* \returns A string that contains the name of the pen, intended for human
* consumption. The string might or might not be localised, depending
* on platform settings. It is not guaranteed to be unique; use
* ::SDL_GetPenGUID() for (best-effort) unique identifiers. The
* pointer is managed by the SDL pen subsystem and must not be
* deallocated. The pointer remains valid until SDL is shut down.
* Returns NULL on error (cf. ::SDL_GetError())
*
* \since This function is available since SDL 3.0.0
*/
extern DECLSPEC const char *SDLCALL SDL_GetPenName(SDL_PenID instance_id);
/**
* Pen capabilities, as reported by ::SDL_GetPenCapabilities()
*/
typedef struct SDL_PenCapabilityInfo
{
float max_tilt; /**< Physical maximum tilt angle, for XTILT and YTILT, or SDL_PEN_INFO_UNKNOWN . Pens cannot typically tilt all the way to 90 degrees, so this value is usually less than 90.0. */
Uint32 wacom_id; /**< For Wacom devices: wacom tool type ID, otherwise 0 (useful e.g. with libwacom) */
Sint8 num_buttons; /**< Number of pen buttons (not counting the pen tip), or SDL_PEN_INFO_UNKNOWN */
} SDL_PenCapabilityInfo;
/**
* Retrieves capability flags for a given ::SDL_PenID.
*
* \param instance_id The pen to query.
* \param capabilities Detail information about pen capabilities, such as the
* number of buttons
* \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES
*
* \since This function is available since SDL 3.0.0
*/
extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL_PenCapabilityInfo *capabilities);
/**
* Retrieves the pen type for a given ::SDL_PenID.
*
* \param instance_id The pen to query.
* \returns The corresponding pen type (cf. ::SDL_PenSubtype) or 0 on error.
* Note that the pen type does not dictate whether the pen tip is
* ::SDL_PEN_TIP_INK or ::SDL_PEN_TIP_ERASER; to determine whether a
* pen is being used for drawing or in eraser mode, check either the
* pen tip on ::SDL_EVENT_PEN_DOWN, or the flag ::SDL_PEN_ERASER_MASK
* in the pen state.
*
* \since This function is available since SDL 3.0.0
*/
extern DECLSPEC SDL_PenSubtype SDLCALL SDL_GetPenType(SDL_PenID instance_id);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif
#endif /* SDL_pen_h_ */
/* vi: set ts=4 sw=4 expandtab: */

64
include/SDL3/SDL_pixels.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,43 @@
/**
* \file SDL_pixels.h
*
* \brief Header for the enumerated pixel format definitions.
* Header for the enumerated pixel format definitions.
*
* SDL's pixel formats have the following naming convention:
*
* * Names with a list of components and a single bit count, such as
* RGB24 and ABGR32, define a platform-independent encoding into
* bytes in the order specified. For example, in RGB24 data, each
* pixel is encoded in 3 bytes (red, green, blue) in that order,
* and in ABGR32 data, each pixel is encoded in 4 bytes
* (alpha, blue, green, red) in that order. Use these names if the
* property of a format that is important to you is the order of
* the bytes in memory or on disk.
*
* * Names with a bit count per component, such as ARGB8888 and
* XRGB1555, are "packed" into an appropriately-sized integer in
* the platform's native endianness. For example, ARGB8888 is
* a sequence of 32-bit integers; in each integer, the most
* significant bits are alpha, and the least significant bits are
* blue. On a little-endian CPU such as x86, the least significant
* bits of each integer are arranged first in memory, but on a
* big-endian CPU such as s390x, the most significant bits are
* arranged first. Use these names if the property of a format that
* is important to you is the meaning of each bit position within a
* native-endianness integer.
*
* * In indexed formats such as INDEX4LSB, each pixel is represented
* by encoding an index into the palette into the indicated number
* of bits, with multiple pixels packed into each byte if appropriate.
* In LSB formats, the first (leftmost) pixel is stored in the
* least-significant bits of the byte; in MSB formats, it's stored
* in the most-significant bits. INDEX8 does not need LSB/MSB
* variants, because each pixel exactly fills one byte.
*
* The 32-bit byte-array encodings such as RGBA32 are aliases for the
* appropriate 8888 encoding for the current platform. For example,
* RGBA32 is an alias for ABGR8888 on little-endian CPUs like x86,
* or an alias for RGBA8888 on big-endian CPUs.
*/
#ifndef SDL_pixels_h_
@ -61,7 +97,9 @@ typedef enum
SDL_PIXELTYPE_ARRAYU16,
SDL_PIXELTYPE_ARRAYU32,
SDL_PIXELTYPE_ARRAYF16,
SDL_PIXELTYPE_ARRAYF32
SDL_PIXELTYPE_ARRAYF32,
/* appended at the end for compatibility with sdl2-compat: */
SDL_PIXELTYPE_INDEX2
} SDL_PixelType;
/** Bitmap pixel order, high bit -> low bit. */
@ -130,6 +168,7 @@ typedef enum
#define SDL_ISPIXELFORMAT_INDEXED(format) \
(!SDL_ISPIXELFORMAT_FOURCC(format) && \
((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX2) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \
(SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8)))
@ -154,6 +193,10 @@ typedef enum
(SDL_PIXELORDER(format) == SDL_PACKEDORDER_ABGR) || \
(SDL_PIXELORDER(format) == SDL_PACKEDORDER_BGRA))))
#define SDL_ISPIXELFORMAT_10BIT(format) \
((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32) && \
(SDL_PIXELLAYOUT(format) == SDL_PACKEDLAYOUT_2101010))
/* The flag is set to 1 because 0x1? is not in the printable ASCII range */
#define SDL_ISPIXELFORMAT_FOURCC(format) \
((format) && (SDL_PIXELFLAG(format) != 1))
@ -168,6 +211,12 @@ typedef enum
SDL_PIXELFORMAT_INDEX1MSB =
SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX1, SDL_BITMAPORDER_1234, 0,
1, 0),
SDL_PIXELFORMAT_INDEX2LSB =
SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_4321, 0,
2, 0),
SDL_PIXELFORMAT_INDEX2MSB =
SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX2, SDL_BITMAPORDER_1234, 0,
2, 0),
SDL_PIXELFORMAT_INDEX4LSB =
SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_INDEX4, SDL_BITMAPORDER_4321, 0,
4, 0),
@ -255,9 +304,18 @@ typedef enum
SDL_PIXELFORMAT_BGRA8888 =
SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_BGRA,
SDL_PACKEDLAYOUT_8888, 32, 4),
SDL_PIXELFORMAT_XRGB2101010 =
SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XRGB,
SDL_PACKEDLAYOUT_2101010, 32, 4),
SDL_PIXELFORMAT_XBGR2101010 =
SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_XBGR,
SDL_PACKEDLAYOUT_2101010, 32, 4),
SDL_PIXELFORMAT_ARGB2101010 =
SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
SDL_PACKEDLAYOUT_2101010, 32, 4),
SDL_PIXELFORMAT_ABGR2101010 =
SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ABGR,
SDL_PACKEDLAYOUT_2101010, 32, 4),
/* Aliases for RGBA byte arrays of color data, for the current platform */
#if SDL_BYTEORDER == SDL_BIG_ENDIAN

4
include/SDL3/SDL_platform.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_platform.h
*
* \brief Header file for platform functions.
* Header file for platform functions.
*/
#ifndef SDL_platform_h_

4
include/SDL3/SDL_platform_defines.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_platform_defines.h
*
* \brief Try to get a standard set of platform defines.
* Try to get a standard set of platform defines.
*/
#ifndef SDL_platform_defines_h_

4
include/SDL3/SDL_power.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -25,7 +25,7 @@
/**
* \file SDL_power.h
*
* \brief Header for the SDL power management routines.
* Header for the SDL power management routines.
*/
#include <SDL3/SDL_stdinc.h>

411
include/SDL3/SDL_properties.h Normal file
View File

@ -0,0 +1,411 @@
/*
Simple DiretMedia Layer
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_properties.h
*
* Header file for SDL properties.
*/
#ifndef SDL_properties_h_
#define SDL_properties_h_
#include <SDL3/SDL_begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {
#endif
/**
* SDL properties ID
*/
typedef Uint32 SDL_PropertiesID;
/**
* SDL property type
*/
typedef enum
{
SDL_PROPERTY_TYPE_INVALID,
SDL_PROPERTY_TYPE_POINTER,
SDL_PROPERTY_TYPE_STRING,
SDL_PROPERTY_TYPE_NUMBER,
SDL_PROPERTY_TYPE_FLOAT,
SDL_PROPERTY_TYPE_BOOLEAN,
} SDL_PropertyType;
/**
* Get the global SDL properties
*
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void);
/**
* Create a set of properties
*
* All properties are automatically destroyed when SDL_Quit() is called.
*
* \returns an ID for a new set of properties, or 0 on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_DestroyProperties
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
/**
* Lock a set of properties
*
* Obtain a multi-threaded lock for these properties. Other threads will wait
* while trying to lock these properties until they are unlocked. Properties
* must be unlocked before they are destroyed.
*
* The lock is automatically taken when setting individual properties, this
* function is only needed when you want to set several properties atomically
* or want to guarantee that properties being queried aren't freed in another
* thread.
*
* \param props the properties to lock
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_UnlockProperties
*/
extern DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props);
/**
* Unlock a set of properties
*
* \param props the properties to unlock
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_LockProperties
*/
extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
/**
* Set a property on a set of properties with a cleanup function that is
* called when the property is deleted
*
* \param props the properties to modify
* \param name the name of the property to modify
* \param value the new value of the property, or NULL to delete the property
* \param cleanup the function to call when this property is deleted, or NULL
* if no cleanup is necessary
* \param userdata a pointer that is passed to the cleanup function
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata);
/**
* Set a property on a set of properties
*
* \param props the properties to modify
* \param name the name of the property to modify
* \param value the new value of the property, or NULL to delete the property
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetPropertyWithCleanup
*/
extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value);
/**
* Set a string property on a set of properties
*
* \param props the properties to modify
* \param name the name of the property to modify
* \param value the new value of the property, or NULL to delete the property
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetStringProperty
*/
extern DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value);
/**
* Set an integer property on a set of properties
*
* \param props the properties to modify
* \param name the name of the property to modify
* \param value the new value of the property
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetNumberProperty
*/
extern DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value);
/**
* Set a floating point property on a set of properties
*
* \param props the properties to modify
* \param name the name of the property to modify
* \param value the new value of the property
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetFloatProperty
*/
extern DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value);
/**
* Set a boolean property on a set of properties
*
* \param props the properties to modify
* \param name the name of the property to modify
* \param value the new value of the property
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetBooleanProperty
*/
extern DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value);
/**
* Get the type of a property on a set of properties
*
* \param props the properties to query
* \param name the name of the property to query
* \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is
* not set.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID props, const char *name);
/**
* Get a property on a set of properties
*
* By convention, the names of properties that SDL exposes on objects will
* start with "SDL.", and properties that SDL uses internally will start with
* "SDL.internal.". These should be considered read-only and should not be
* modified by applications.
*
* \param props the properties to query
* \param name the name of the property to query
* \param default_value the default value of the property
* \returns the value of the property, or `default_value` if it is not set or
* not a pointer property.
*
* \threadsafety It is safe to call this function from any thread, although
* the data returned is not protected and could potentially be
* freed if you call SDL_SetProperty() or SDL_ClearProperty() on
* these properties from another thread. If you need to avoid
* this, use SDL_LockProperties() and SDL_UnlockProperties().
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetPropertyType
* \sa SDL_SetProperty
*/
extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char *name, void *default_value);
/**
* Get a string property on a set of properties
*
* \param props the properties to query
* \param name the name of the property to query
* \param default_value the default value of the property
* \returns the value of the property, or `default_value` if it is not set or
* not a string property.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetPropertyType
* \sa SDL_SetStringProperty
*/
extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value);
/**
* Get a number property on a set of properties
*
* You can use SDL_GetPropertyType() to query whether the property exists and
* is a number property.
*
* \param props the properties to query
* \param name the name of the property to query
* \param default_value the default value of the property
* \returns the value of the property, or `default_value` if it is not set or
* not a number property.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetPropertyType
* \sa SDL_SetNumberProperty
*/
extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value);
/**
* Get a floating point property on a set of properties
*
* You can use SDL_GetPropertyType() to query whether the property exists and
* is a floating point property.
*
* \param props the properties to query
* \param name the name of the property to query
* \param default_value the default value of the property
* \returns the value of the property, or `default_value` if it is not set or
* not a float property.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetPropertyType
* \sa SDL_SetFloatProperty
*/
extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value);
/**
* Get a boolean property on a set of properties
*
* You can use SDL_GetPropertyType() to query whether the property exists and
* is a boolean property.
*
* \param props the properties to query
* \param name the name of the property to query
* \param default_value the default value of the property
* \returns the value of the property, or `default_value` if it is not set or
* not a float property.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetPropertyType
* \sa SDL_SetBooleanProperty
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value);
/**
* Clear a property on a set of properties
*
* \param props the properties to modify
* \param name the name of the property to clear
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
*/
extern DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name);
typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name);
/**
* Enumerate the properties on a set of properties
*
* The callback function is called for each property on the set of properties.
* The properties are locked during enumeration.
*
* \param props the properties to query
* \param callback the function to call for each property
* \param userdata a pointer that is passed to `callback`
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata);
/**
* Destroy a set of properties
*
* All properties are deleted and their cleanup functions will be called, if
* any.
*
* \param props the properties to destroy
*
* \threadsafety This function should not be called while these properties are
* locked or other threads might be setting or getting values
* from these properties.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateProperties
*/
extern DECLSPEC void SDLCALL SDL_DestroyProperties(SDL_PropertiesID props);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif
#include <SDL3/SDL_close_code.h>
#endif /* SDL_properties_h_ */

4
include/SDL3/SDL_quit.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_quit.h
*
* \brief Include file for SDL quit event handling.
* Include file for SDL quit event handling.
*/
#ifndef SDL_quit_h_

4
include/SDL3/SDL_rect.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_rect.h
*
* \brief Header file for SDL_rect definition and management functions.
* Header file for SDL_rect definition and management functions.
*/
#ifndef SDL_rect_h_

414
include/SDL3/SDL_render.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_render.h
*
* \brief Header file for SDL 2D rendering functions.
* Header file for SDL 2D rendering functions.
*
* This API supports the following features:
* * single pixel points
@ -50,6 +50,7 @@
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_events.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_rect.h>
#include <SDL3/SDL_video.h>
@ -94,16 +95,6 @@ typedef struct SDL_Vertex
SDL_FPoint tex_coord; /**< Normalized texture coordinates, if needed */
} SDL_Vertex;
/**
* The scaling mode for a texture.
*/
typedef enum
{
SDL_SCALEMODE_NEAREST, /**< nearest pixel sampling */
SDL_SCALEMODE_LINEAR, /**< linear filtering */
SDL_SCALEMODE_BEST /**< anisotropic filtering */
} SDL_ScaleMode;
/**
* The access pattern allowed for a texture.
*/
@ -114,16 +105,6 @@ typedef enum
SDL_TEXTUREACCESS_TARGET /**< Texture can be used as a render target */
} SDL_TextureAccess;
/**
* The texture channel modulation used in SDL_RenderTexture().
*/
typedef enum
{
SDL_TEXTUREMODULATE_NONE = 0x00000000, /**< No modulation */
SDL_TEXTUREMODULATE_COLOR = 0x00000001, /**< srcC = srcC * color */
SDL_TEXTUREMODULATE_ALPHA = 0x00000002 /**< srcA = srcA * alpha */
} SDL_TextureModulate;
/**
* Flip constants for SDL_RenderTextureRotated
*/
@ -204,7 +185,6 @@ extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
*/
extern DECLSPEC const char *SDLCALL SDL_GetRenderDriver(int index);
/**
* Create a window and default renderer.
*
@ -224,14 +204,13 @@ extern DECLSPEC const char *SDLCALL SDL_GetRenderDriver(int index);
*/
extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(int width, int height, Uint32 window_flags, SDL_Window **window, SDL_Renderer **renderer);
/**
* Create a 2D rendering context for a window.
*
* If you want a specific renderer, you can specify its name here. A list of
* available renderers can be obtained by calling SDL_GetRenderDriver multiple
* times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you don't
* need a specific renderer, specify NULL and SDL will attempt to chooes the
* need a specific renderer, specify NULL and SDL will attempt to choose the
* best option for you, based on what is available on the user's system.
*
* By default the rendering size matches the window size in pixels, but you
@ -247,13 +226,46 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(int width, int height, U
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateRendererWithProperties
* \sa SDL_CreateSoftwareRenderer
* \sa SDL_DestroyRenderer
* \sa SDL_GetNumRenderDrivers
* \sa SDL_GetRenderDriver
* \sa SDL_GetRendererInfo
*/
extern DECLSPEC SDL_Renderer *SDLCALL SDL_CreateRenderer(SDL_Window *window, const char *name, Uint32 flags);
extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window, const char *name, Uint32 flags);
/**
* Create a 2D rendering context for a window, with the specified properties.
*
* These are the supported properties:
*
* - `SDL_PROPERTY_RENDERER_CREATE_WINDOW_POINTER`: the window where rendering
* is displayed
* - `SDL_PROPERTY_RENDERER_CREATE_SURFACE_POINTER`: the surface where
* rendering is displayed, if you want a software renderer without a window
* - `SDL_PROPERTY_RENDERER_CREATE_NAME_STRING`: the name of the rendering
* driver to use, if a specific one is desired
* - `SDL_PROPERTY_RENDERER_CREATE_PRESENT_VSYNC_BOOLEAN`: true if you want
* present synchronized with the refresh rate
*
* \param props the properties to use
* \returns a valid rendering context or NULL if there was an error; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateRenderer
* \sa SDL_CreateSoftwareRenderer
* \sa SDL_DestroyRenderer
* \sa SDL_GetRendererInfo
*/
extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRendererWithProperties(SDL_PropertiesID props);
#define SDL_PROPERTY_RENDERER_CREATE_WINDOW_POINTER "window"
#define SDL_PROPERTY_RENDERER_CREATE_SURFACE_POINTER "surface"
#define SDL_PROPERTY_RENDERER_CREATE_NAME_STRING "name"
#define SDL_PROPERTY_RENDERER_CREATE_PRESENT_VSYNC_BOOLEAN "present_vsync"
/**
* Create a 2D software rendering context for a surface.
@ -315,6 +327,36 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer);
*/
extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_RendererInfo *info);
/**
* Get the properties associated with a renderer.
*
* The following read-only properties are provided by SDL:
*
* - `SDL_PROPERTY_RENDERER_D3D9_DEVICE_POINTER`: the IDirect3DDevice9
* associated with the renderer
* - `SDL_PROPERTY_RENDERER_D3D11_DEVICE_POINTER`: the ID3D11Device associated
* with the renderer
* - `SDL_PROPERTY_RENDERER_D3D12_DEVICE_POINTER`: the ID3D12Device associated
* with the renderer
* - `SDL_PROPERTY_RENDERER_D3D12_COMMAND_QUEUE_POINTER`: the
* ID3D12CommandQueue associated with the renderer
*
* \param renderer the rendering context
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Renderer *renderer);
#define SDL_PROPERTY_RENDERER_D3D9_DEVICE_POINTER "SDL.renderer.d3d9.device"
#define SDL_PROPERTY_RENDERER_D3D11_DEVICE_POINTER "SDL.renderer.d3d11.device"
#define SDL_PROPERTY_RENDERER_D3D12_DEVICE_POINTER "SDL.renderer.d3d12.device"
#define SDL_PROPERTY_RENDERER_D3D12_COMMAND_QUEUE_POINTER "SDL.renderer.d3d12.command_queue"
/**
* Get the output size in pixels of a rendering context.
*
@ -372,6 +414,7 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *rendere
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateTextureFromSurface
* \sa SDL_CreateTextureWithProperties
* \sa SDL_DestroyTexture
* \sa SDL_QueryTexture
* \sa SDL_UpdateTexture
@ -399,11 +442,217 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTexture(SDL_Renderer *renderer, U
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateTexture
* \sa SDL_CreateTextureWithProperties
* \sa SDL_DestroyTexture
* \sa SDL_QueryTexture
*/
extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *renderer, SDL_Surface *surface);
/**
* Create a texture for a rendering context with the specified properties.
*
* These are the supported properties:
*
* - `SDL_PROPERTY_TEXTURE_CREATE_FORMAT_NUMBER`: one of the enumerated values
* in SDL_PixelFormatEnum, defaults to the best RGBA format for the renderer
* - `SDL_PROPERTY_TEXTURE_CREATE_ACCESS_NUMBER`: one of the enumerated values
* in SDL_TextureAccess, defaults to SDL_TEXTUREACCESS_STATIC
* - `SDL_PROPERTY_TEXTURE_CREATE_WIDTH_NUMBER`: the width of the texture in
* pixels, required
* - `SDL_PROPERTY_TEXTURE_CREATE_HEIGHT_NUMBER`: the height of the texture in
* pixels, required
*
* With the direct3d11 renderer:
*
* - `SDL_PROPERTY_TEXTURE_CREATE_D3D11_TEXTURE_POINTER`: the ID3D11Texture2D
* associated with the texture, if you want to wrap an existing texture.
* - `SDL_PROPERTY_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER`: the
* ID3D11Texture2D associated with the U plane of a YUV texture, if you want
* to wrap an existing texture.
* - `SDL_PROPERTY_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER`: the
* ID3D11Texture2D associated with the V plane of a YUV texture, if you want
* to wrap an existing texture.
*
* With the direct3d12 renderer:
*
* - `SDL_PROPERTY_TEXTURE_CREATE_D3D12_TEXTURE_POINTER`: the ID3D12Resource
* associated with the texture, if you want to wrap an existing texture.
* - `SDL_PROPERTY_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER`: the ID3D12Resource
* associated with the U plane of a YUV texture, if you want to wrap an
* existing texture.
* - `SDL_PROPERTY_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER`: the ID3D12Resource
* associated with the V plane of a YUV texture, if you want to wrap an
* existing texture.
*
* With the opengl renderer:
*
* - `SDL_PROPERTY_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER`: the GLuint texture
* associated with the texture, if you want to wrap an existing texture.
* - `SDL_PROPERTY_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER`: the GLuint
* texture associated with the UV plane of an NV12 texture, if you want to
* wrap an existing texture.
* - `SDL_PROPERTY_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER`: the GLuint texture
* associated with the U plane of a YUV texture, if you want to wrap an
* existing texture.
* - `SDL_PROPERTY_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER`: the GLuint texture
* associated with the V plane of a YUV texture, if you want to wrap an
* existing texture.
*
* With the opengles2 renderer:
*
* - `SDL_PROPERTY_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER`: the GLuint
* texture associated with the texture, if you want to wrap an existing
* texture.
* - `SDL_PROPERTY_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER`: the GLuint
* texture associated with the texture, if you want to wrap an existing
* texture.
* - `SDL_PROPERTY_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER`: the GLuint
* texture associated with the UV plane of an NV12 texture, if you want to
* wrap an existing texture.
* - `SDL_PROPERTY_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER`: the GLuint
* texture associated with the U plane of a YUV texture, if you want to wrap
* an existing texture.
* - `SDL_PROPERTY_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER`: the GLuint
* texture associated with the V plane of a YUV texture, if you want to wrap
* an existing texture.
*
* \param renderer the rendering context
* \param props the properties to use
* \returns a pointer to the created texture or NULL if no rendering context
* was active, the format was unsupported, or the width or height
* were out of range; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateTextureFromSurface
* \sa SDL_CreateTexture
* \sa SDL_DestroyTexture
* \sa SDL_QueryTexture
* \sa SDL_UpdateTexture
*/
extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureWithProperties(SDL_Renderer *renderer, SDL_PropertiesID props);
#define SDL_PROPERTY_TEXTURE_CREATE_FORMAT_NUMBER "format"
#define SDL_PROPERTY_TEXTURE_CREATE_ACCESS_NUMBER "access"
#define SDL_PROPERTY_TEXTURE_CREATE_WIDTH_NUMBER "width"
#define SDL_PROPERTY_TEXTURE_CREATE_HEIGHT_NUMBER "height"
#define SDL_PROPERTY_TEXTURE_CREATE_D3D11_TEXTURE_POINTER "d3d11.texture"
#define SDL_PROPERTY_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER "d3d11.texture_u"
#define SDL_PROPERTY_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER "d3d11.texture_v"
#define SDL_PROPERTY_TEXTURE_CREATE_D3D12_TEXTURE_POINTER "d3d12.texture"
#define SDL_PROPERTY_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER "d3d12.texture_u"
#define SDL_PROPERTY_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER "d3d12.texture_v"
#define SDL_PROPERTY_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER "opengl.texture"
#define SDL_PROPERTY_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER "opengl.texture_uv"
#define SDL_PROPERTY_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER "opengl.texture_u"
#define SDL_PROPERTY_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER "opengl.texture_v"
#define SDL_PROPERTY_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER "opengles2.texture"
#define SDL_PROPERTY_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER "opengles2.texture"
#define SDL_PROPERTY_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER "opengles2.texture_uv"
#define SDL_PROPERTY_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER "opengles2.texture_u"
#define SDL_PROPERTY_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER "opengles2.texture_v"
/**
* Get the properties associated with a texture.
*
* The following read-only properties are provided by SDL:
*
* With the direct3d11 renderer:
*
* - `SDL_PROPERTY_TEXTURE_D3D11_TEXTURE_POINTER`: the ID3D11Texture2D
* associated with the texture
* - `SDL_PROPERTY_TEXTURE_D3D11_TEXTURE_U_POINTER`: the ID3D11Texture2D
* associated with the U plane of a YUV texture
* - `SDL_PROPERTY_TEXTURE_D3D11_TEXTURE_V_POINTER`: the ID3D11Texture2D
* associated with the V plane of a YUV texture
*
* With the direct3d12 renderer:
*
* - `SDL_PROPERTY_TEXTURE_D3D12_TEXTURE_POINTER`: the ID3D12Resource
* associated with the texture
* - `SDL_PROPERTY_TEXTURE_D3D12_TEXTURE_U_POINTER`: the ID3D12Resource
* associated with the U plane of a YUV texture
* - `SDL_PROPERTY_TEXTURE_D3D12_TEXTURE_V_POINTER`: the ID3D12Resource
* associated with the V plane of a YUV texture
*
* With the opengl renderer:
*
* - `SDL_PROPERTY_TEXTURE_OPENGL_TEXTURE_NUMBER`: the GLuint texture
* associated with the texture
* - `SDL_PROPERTY_TEXTURE_OPENGL_TEXTURE_UV_NUMBER`: the GLuint texture
* associated with the UV plane of an NV12 texture
* - `SDL_PROPERTY_TEXTURE_OPENGL_TEXTURE_U_NUMBER`: the GLuint texture
* associated with the U plane of a YUV texture
* - `SDL_PROPERTY_TEXTURE_OPENGL_TEXTURE_V_NUMBER`: the GLuint texture
* associated with the V plane of a YUV texture
* - `SDL_PROPERTY_TEXTURE_OPENGL_TEXTURE_TARGET`: the GLenum for the texture
* target (`GL_TEXTURE_2D`, `GL_TEXTURE_RECTANGLE_ARB`, etc)
* - `SDL_PROPERTY_TEXTURE_OPENGL_TEX_W_FLOAT`: the texture coordinate width
* of the texture (0.0 - 1.0)
* - `SDL_PROPERTY_TEXTURE_OPENGL_TEX_H_FLOAT`: the texture coordinate height
* of the texture (0.0 - 1.0)
*
* With the opengles2 renderer:
*
* - `SDL_PROPERTY_TEXTURE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture
* associated with the texture
* - `SDL_PROPERTY_TEXTURE_OPENGLES2_TEXTURE_UV_NUMBER`: the GLuint texture
* associated with the UV plane of an NV12 texture
* - `SDL_PROPERTY_TEXTURE_OPENGLES2_TEXTURE_U_NUMBER`: the GLuint texture
* associated with the U plane of a YUV texture
* - `SDL_PROPERTY_TEXTURE_OPENGLES2_TEXTURE_V_NUMBER`: the GLuint texture
* associated with the V plane of a YUV texture
* - `SDL_PROPERTY_TEXTURE_OPENGLES2_TEXTURE_TARGET`: the GLenum for the
* texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_EXTERNAL_OES`, etc)
*
* \param texture the texture to query
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Texture *texture);
#define SDL_PROPERTY_TEXTURE_D3D11_TEXTURE_POINTER "SDL.texture.d3d11.texture"
#define SDL_PROPERTY_TEXTURE_D3D11_TEXTURE_U_POINTER "SDL.texture.d3d11.texture_u"
#define SDL_PROPERTY_TEXTURE_D3D11_TEXTURE_V_POINTER "SDL.texture.d3d11.texture_v"
#define SDL_PROPERTY_TEXTURE_D3D12_TEXTURE_POINTER "SDL.texture.d3d12.texture"
#define SDL_PROPERTY_TEXTURE_D3D12_TEXTURE_U_POINTER "SDL.texture.d3d12.texture_u"
#define SDL_PROPERTY_TEXTURE_D3D12_TEXTURE_V_POINTER "SDL.texture.d3d12.texture_v"
#define SDL_PROPERTY_TEXTURE_OPENGL_TEXTURE_NUMBER "SDL.texture.opengl.texture"
#define SDL_PROPERTY_TEXTURE_OPENGL_TEXTURE_UV_NUMBER "SDL.texture.opengl.texture_uv"
#define SDL_PROPERTY_TEXTURE_OPENGL_TEXTURE_U_NUMBER "SDL.texture.opengl.texture_u"
#define SDL_PROPERTY_TEXTURE_OPENGL_TEXTURE_V_NUMBER "SDL.texture.opengl.texture_v"
#define SDL_PROPERTY_TEXTURE_OPENGL_TEXTURE_TARGET "SDL.texture.opengl.target"
#define SDL_PROPERTY_TEXTURE_OPENGL_TEX_W_FLOAT "SDL.texture.opengl.tex_w"
#define SDL_PROPERTY_TEXTURE_OPENGL_TEX_H_FLOAT "SDL.texture.opengl.tex_h"
#define SDL_PROPERTY_TEXTURE_OPENGLES2_TEXTURE_NUMBER "SDL.texture.opengles2.texture"
#define SDL_PROPERTY_TEXTURE_OPENGLES2_TEXTURE_UV_NUMBER "SDL.texture.opengles2.texture_uv"
#define SDL_PROPERTY_TEXTURE_OPENGLES2_TEXTURE_U_NUMBER "SDL.texture.opengles2.texture_u"
#define SDL_PROPERTY_TEXTURE_OPENGLES2_TEXTURE_V_NUMBER "SDL.texture.opengles2.texture_v"
#define SDL_PROPERTY_TEXTURE_OPENGLES2_TEXTURE_TARGET "SDL.texture.opengles2.target"
/**
* Get the renderer that created an SDL_Texture.
*
* \param texture the texture to query
* \returns a pointer to the SDL_Renderer that created the texture, or NULL on
* failure; call SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateTexture
* \sa SDL_CreateTextureFromSurface
* \sa SDL_CreateTextureWithProperties
*/
extern DECLSPEC SDL_Renderer *SDLCALL SDL_GetRendererFromTexture(SDL_Texture *texture);
/**
* Query the attributes of a texture.
*
@ -572,33 +821,6 @@ extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_Sc
*/
extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode);
/**
* Associate a user-specified pointer with a texture.
*
* \param texture the texture to update.
* \param userdata the pointer to associate with the texture.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetTextureUserData
*/
extern DECLSPEC int SDLCALL SDL_SetTextureUserData(SDL_Texture *texture, void *userdata);
/**
* Get the user-specified pointer associated with a texture
*
* \param texture the texture to query.
* \returns the pointer associated with the texture, or NULL if the texture is
* not valid.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_SetTextureUserData
*/
extern DECLSPEC void *SDLCALL SDL_GetTextureUserData(SDL_Texture *texture);
/**
* Update the given texture rectangle with new pixel data.
*
@ -1445,27 +1667,27 @@ extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture);
extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer);
/**
* Force the rendering context to flush any pending commands to the underlying
* rendering API.
* Force the rendering context to flush any pending commands and state.
*
* You do not need to (and in fact, shouldn't) call this function unless you
* are planning to call into OpenGL/Direct3D/Metal/whatever directly in
* are planning to call into OpenGL/Direct3D/Metal/whatever directly, in
* addition to using an SDL_Renderer.
*
* This is for a very-specific case: if you are using SDL's render API, you
* asked for a specific renderer backend (OpenGL, Direct3D, etc), you set
* SDL_HINT_RENDER_BATCHING to "1", and you plan to make OpenGL/D3D/whatever
* calls in addition to SDL render API calls. If all of this applies, you
* should call SDL_RenderFlush() between calls to SDL's render API and the
* low-level API you're using in cooperation.
* This is for a very-specific case: if you are using SDL's render API, and
* you plan to make OpenGL/D3D/whatever calls in addition to SDL render API
* calls. If this applies, you should call this function between calls to
* SDL's render API and the low-level API you're using in cooperation.
*
* In all other cases, you can ignore this function. This is only here to get
* maximum performance out of a specific situation. In all other cases, SDL
* will do the right thing, perhaps at a performance loss.
* In all other cases, you can ignore this function.
*
* This function is first available in SDL 2.0.10, and is not needed in 2.0.9
* and earlier, as earlier versions did not queue rendering commands at all,
* instead flushing them to the OS immediately.
* This call makes SDL flush any pending rendering work it was queueing up to
* do later in a single batch, and marks any internal cached state as invalid,
* so it'll prepare all its state again later, from scratch.
*
* This means you do not need to save state in your rendering code to protect
* the SDL renderer. However, there lots of arbitrary pieces of Direct3D and
* OpenGL state that can confuse things; you should use your best judgement
* and be prepared to make changes if specific state needs to be protected.
*
* \param renderer the rendering context
* \returns 0 on success or a negative error code on failure; call
@ -1473,61 +1695,7 @@ extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer);
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer *renderer);
/**
* Bind an OpenGL/ES/ES2 texture to the current context.
*
* This is for use with OpenGL instructions when rendering OpenGL primitives
* directly.
*
* If not NULL, `texw` and `texh` will be filled with the width and height
* values suitable for the provided texture. In most cases, both will be 1.0,
* however, on systems that support the GL_ARB_texture_rectangle extension,
* these values will actually be the pixel width and height used to create the
* texture, so this factor needs to be taken into account when providing
* texture coordinates to OpenGL.
*
* You need a renderer to create an SDL_Texture, therefore you can only use
* this function with an implicit OpenGL context from SDL_CreateRenderer(),
* not with your own OpenGL context. If you need control over your OpenGL
* context, you need to write your own texture-loading methods.
*
* Also note that SDL may upload RGB textures as BGR (or vice-versa), and
* re-order the color channels in the shaders phase, so the uploaded texture
* may have swapped color channels.
*
* \param texture the texture to bind to the current OpenGL/ES/ES2 context
* \param texw a pointer to a float value which will be filled with the
* texture width or NULL if you don't need that value
* \param texh a pointer to a float value which will be filled with the
* texture height or NULL if you don't need that value
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GL_MakeCurrent
* \sa SDL_GL_UnbindTexture
*/
extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw, float *texh);
/**
* Unbind an OpenGL/ES/ES2 texture from the current context.
*
* See SDL_GL_BindTexture() for examples on how to use these functions
*
* \param texture the texture to unbind from the current OpenGL/ES/ES2 context
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GL_BindTexture
* \sa SDL_GL_MakeCurrent
*/
extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture);
extern DECLSPEC int SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer);
/**
* Get the CAMetalLayer associated with the given Metal renderer.

4
include/SDL3/SDL_revision.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_revision.h
*
* \brief Header file containing the SDL revision
* Header file containing the SDL revision
*/
#ifndef SDL_revision_h_

66
include/SDL3/SDL_rwops.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -31,6 +31,7 @@
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_begin_code.h>
/* Set up for C function definitions, even when using C++ */
@ -99,6 +100,7 @@ typedef struct SDL_RWops
Uint32 type;
Uint32 status;
SDL_PropertiesID props;
union
{
#ifdef __ANDROID__
@ -331,6 +333,20 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_CreateRW(void);
*/
extern DECLSPEC void SDLCALL SDL_DestroyRW(SDL_RWops *context);
/**
* Get the properties associated with an SDL_RWops.
*
* \param context a pointer to an SDL_RWops structure
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRWProperties(SDL_RWops *context);
#define SDL_RW_SEEK_SET 0 /**< Seek from the beginning of data */
#define SDL_RW_SEEK_CUR 1 /**< Seek relative to current read point */
#define SDL_RW_SEEK_END 2 /**< Seek relative to the end of data */
@ -474,11 +490,59 @@ extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context, void *ptr, size_t
* \sa SDL_RWFromConstMem
* \sa SDL_RWFromFile
* \sa SDL_RWFromMem
* \sa SDL_RWprint
* \sa SDL_RWread
* \sa SDL_RWseek
*/
extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context, const void *ptr, size_t size);
/**
* Print to an SDL_RWops data stream.
*
* This function does formatted printing to the stream.
*
* \param context a pointer to an SDL_RWops structure
* \param fmt a printf() style format string
* \param ... additional parameters matching % tokens in the `fmt` string, if
* any
* \returns the number of bytes written, or 0 on error; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_RWclose
* \sa SDL_RWFromConstMem
* \sa SDL_RWFromFile
* \sa SDL_RWFromMem
* \sa SDL_RWread
* \sa SDL_RWseek
* \sa SDL_RWwrite
*/
extern DECLSPEC size_t SDLCALL SDL_RWprintf(SDL_RWops *context, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
* Print to an SDL_RWops data stream.
*
* This function does formatted printing to the stream.
*
* \param context a pointer to an SDL_RWops structure
* \param fmt a printf() style format string
* \param ap a variable argument list
* \returns the number of bytes written, or 0 on error; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_RWclose
* \sa SDL_RWFromConstMem
* \sa SDL_RWFromFile
* \sa SDL_RWFromMem
* \sa SDL_RWread
* \sa SDL_RWseek
* \sa SDL_RWwrite
*/
extern DECLSPEC size_t SDLCALL SDL_RWvprintf(SDL_RWops *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
/**
* Close and free an allocated SDL_RWops structure.
*

6
include/SDL3/SDL_scancode.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_scancode.h
*
* \brief Defines keyboard scancodes.
* Defines keyboard scancodes.
*/
#ifndef SDL_scancode_h_
@ -31,7 +31,7 @@
#include <SDL3/SDL_stdinc.h>
/**
* \brief The SDL keyboard scancode representation.
* The SDL keyboard scancode representation.
*
* Values of this type are used to represent keyboard keys, among other places
* in the \link SDL_Keysym::scancode key.keysym.scancode \endlink field of the

21
include/SDL3/SDL_sensor.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_sensor.h
*
* \brief Include file for SDL sensor event handling
* Include file for SDL sensor event handling
*/
#ifndef SDL_sensor_h_
@ -30,6 +30,7 @@
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_begin_code.h>
/* Set up for C function definitions, even when using C++ */
@ -40,7 +41,7 @@ extern "C" {
#endif
/**
* \brief SDL_sensor.h
* SDL_sensor.h
*
* In order to use these functions, SDL_Init() must have been called
* with the ::SDL_INIT_SENSOR flag. This causes SDL to scan the system
@ -189,6 +190,20 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_OpenSensor(SDL_SensorID instance_id);
*/
extern DECLSPEC SDL_Sensor *SDLCALL SDL_GetSensorFromInstanceID(SDL_SensorID instance_id);
/**
* Get the properties associated with a sensor.
*
* \param sensor The SDL_Sensor object
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor *sensor);
/**
* Get the implementation dependent name of a sensor
*

150
include/SDL3/SDL_shape.h
View File

@ -1,150 +0,0 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
*/
#ifndef SDL_shape_h_
#define SDL_shape_h_
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_pixels.h>
#include <SDL3/SDL_rect.h>
#include <SDL3/SDL_surface.h>
#include <SDL3/SDL_video.h>
#include <SDL3/SDL_begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {
#endif
/** \file SDL_shape.h
*
* \brief Header file for the shaped window API.
*/
#define SDL_NONSHAPEABLE_WINDOW -1
#define SDL_INVALID_SHAPE_ARGUMENT -2
#define SDL_WINDOW_LACKS_SHAPE -3
/**
* Create a window that can be shaped with the specified dimensions and flags.
*
* \param title The title of the window, in UTF-8 encoding.
* \param w The width of the window.
* \param h The height of the window.
* \param flags The flags for the window, a mask of SDL_WINDOW_BORDERLESS with
* any of the following: ::SDL_WINDOW_OPENGL,
* ::SDL_WINDOW_MOUSE_GRABBED, ::SDL_WINDOW_HIDDEN,
* ::SDL_WINDOW_RESIZABLE, ::SDL_WINDOW_MAXIMIZED,
* ::SDL_WINDOW_MINIMIZED, ::SDL_WINDOW_BORDERLESS is always set,
* and ::SDL_WINDOW_FULLSCREEN is always unset.
* \returns the window created, or NULL if window creation failed.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_DestroyWindow
*/
extern DECLSPEC SDL_Window *SDLCALL SDL_CreateShapedWindow(const char *title, int w, int h, Uint32 flags);
/**
* Return whether the given window is a shaped window.
*
* \param window The window to query for being shaped.
* \returns SDL_TRUE if the window is a window that can be shaped, SDL_FALSE
* if the window is unshaped or NULL.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateShapedWindow
*/
extern DECLSPEC SDL_bool SDLCALL SDL_IsShapedWindow(const SDL_Window *window);
/** \brief An enum denoting the specific type of contents present in an SDL_WindowShapeParams union. */
typedef enum {
/** \brief The default mode, a binarized alpha cutoff of 1. */
ShapeModeDefault,
/** \brief A binarized alpha cutoff with a given integer value. */
ShapeModeBinarizeAlpha,
/** \brief A binarized alpha cutoff with a given integer value, but with the opposite comparison. */
ShapeModeReverseBinarizeAlpha,
/** \brief A color key is applied. */
ShapeModeColorKey
} WindowShapeMode;
#define SDL_SHAPEMODEALPHA(mode) (mode == ShapeModeDefault || mode == ShapeModeBinarizeAlpha || mode == ShapeModeReverseBinarizeAlpha)
/** \brief A union containing parameters for shaped windows. */
typedef union {
/** \brief A cutoff alpha value for binarization of the window shape's alpha channel. */
Uint8 binarizationCutoff;
SDL_Color colorKey;
} SDL_WindowShapeParams;
/** \brief A struct that tags the SDL_WindowShapeParams union with an enum describing the type of its contents. */
typedef struct SDL_WindowShapeMode {
/** \brief The mode of these window-shape parameters. */
WindowShapeMode mode;
/** \brief Window-shape parameters. */
SDL_WindowShapeParams parameters;
} SDL_WindowShapeMode;
/**
* Set the shape and parameters of a shaped window.
*
* \param window The shaped window whose parameters should be set.
* \param shape A surface encoding the desired shape for the window.
* \param shape_mode The parameters to set for the shaped window.
* \returns 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
* argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
* not reference a valid shaped window.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_WindowShapeMode
* \sa SDL_GetShapedWindowMode
*/
extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *shape,SDL_WindowShapeMode *shape_mode);
/**
* Get the shape parameters of a shaped window.
*
* \param window The shaped window whose parameters should be retrieved.
* \param shape_mode An empty shape-mode structure to fill, or NULL to check
* whether the window has a shape.
* \returns 0 if the window has a shape and, provided shape_mode was not NULL,
* shape_mode has been filled with the mode data,
* SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped
* window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a
* shapeable window currently lacking a shape.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_WindowShapeMode
* \sa SDL_SetWindowShape
*/
extern DECLSPEC int SDLCALL SDL_GetShapedWindowMode(SDL_Window *window,SDL_WindowShapeMode *shape_mode);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif
#include <SDL3/SDL_close_code.h>
#endif /* SDL_shape_h_ */

96
include/SDL3/SDL_stdinc.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_stdinc.h
*
* \brief This is a general header that includes C language support.
* This is a general header that includes C language support.
*/
#ifndef SDL_stdinc_h_
@ -37,26 +37,34 @@
#include <stdint.h>
#include <wchar.h>
#ifndef alloca
# ifdef HAVE_ALLOCA_H
# include <alloca.h>
# elif defined(__GNUC__)
# define alloca __builtin_alloca
# elif defined(_MSC_VER)
# include <malloc.h>
# define alloca _alloca
# elif defined(__WATCOMC__)
# include <malloc.h>
# elif defined(__BORLANDC__)
# include <malloc.h>
# elif defined(__DMC__)
# include <stdlib.h>
# elif defined(__AIX__)
#pragma alloca
# elif defined(__MRC__)
#ifndef SDL_DISABLE_ALLOCA
# ifndef alloca
# ifdef HAVE_ALLOCA_H
# include <alloca.h>
# elif defined(__NETBSD__)
# if defined(__STRICT_ANSI__)
# define SDL_DISABLE_ALLOCA
# else
# include <stdlib.h>
# endif
# elif defined(__GNUC__)
# define alloca __builtin_alloca
# elif defined(_MSC_VER)
# include <malloc.h>
# define alloca _alloca
# elif defined(__WATCOMC__)
# include <malloc.h>
# elif defined(__BORLANDC__)
# include <malloc.h>
# elif defined(__DMC__)
# include <stdlib.h>
# elif defined(__AIX__)
# pragma alloca
# elif defined(__MRC__)
void *alloca(unsigned);
# else
# else
char *alloca();
# endif
# endif
#endif
@ -120,64 +128,58 @@ char *alloca();
*/
/* @{ */
#ifdef __CC_ARM
/* ARM's compiler throws warnings if we use an enum: like "SDL_bool x = a < b;" */
/**
* A boolean type.
*/
#define SDL_FALSE 0
#define SDL_TRUE 1
typedef int SDL_bool;
#else
typedef enum
{
SDL_FALSE = 0,
SDL_TRUE = 1
} SDL_bool;
#endif
/**
* \brief A signed 8-bit integer type.
* A signed 8-bit integer type.
*/
#define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */
#define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */
typedef int8_t Sint8;
/**
* \brief An unsigned 8-bit integer type.
* An unsigned 8-bit integer type.
*/
#define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */
#define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */
typedef uint8_t Uint8;
/**
* \brief A signed 16-bit integer type.
* A signed 16-bit integer type.
*/
#define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */
#define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */
typedef int16_t Sint16;
/**
* \brief An unsigned 16-bit integer type.
* An unsigned 16-bit integer type.
*/
#define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */
#define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */
typedef uint16_t Uint16;
/**
* \brief A signed 32-bit integer type.
* A signed 32-bit integer type.
*/
#define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */
#define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */
typedef int32_t Sint32;
/**
* \brief An unsigned 32-bit integer type.
* An unsigned 32-bit integer type.
*/
#define SDL_MAX_UINT32 ((Uint32)0xFFFFFFFFu) /* 4294967295 */
#define SDL_MIN_UINT32 ((Uint32)0x00000000) /* 0 */
typedef uint32_t Uint32;
/**
* \brief A signed 64-bit integer type.
* A signed 64-bit integer type.
*/
#define SDL_MAX_SINT64 ((Sint64)0x7FFFFFFFFFFFFFFFll) /* 9223372036854775807 */
#define SDL_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */
typedef int64_t Sint64;
/**
* \brief An unsigned 64-bit integer type.
* An unsigned 64-bit integer type.
*/
#define SDL_MAX_UINT64 ((Uint64)0xFFFFFFFFFFFFFFFFull) /* 18446744073709551615 */
#define SDL_MIN_UINT64 ((Uint64)(0x0000000000000000ull)) /* 0 */
@ -285,7 +287,9 @@ typedef uint64_t Uint64;
#define SDL_PRINTF_FORMAT_STRING
#define SDL_SCANF_FORMAT_STRING
#define SDL_PRINTF_VARARG_FUNC( fmtargnumber )
#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber )
#define SDL_SCANF_VARARG_FUNC( fmtargnumber )
#define SDL_SCANF_VARARG_FUNCV( fmtargnumber )
#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber )
#define SDL_WSCANF_VARARG_FUNC( fmtargnumber )
#else
@ -313,12 +317,16 @@ typedef uint64_t Uint64;
#endif
#ifdef __GNUC__
#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 )))
#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 )))
#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 )))
#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 )))
#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */
#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wscanf__, fmtargnumber, fmtargnumber+1 ))) */
#else
#define SDL_PRINTF_VARARG_FUNC( fmtargnumber )
#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber )
#define SDL_SCANF_VARARG_FUNC( fmtargnumber )
#define SDL_SCANF_VARARG_FUNCV( fmtargnumber )
#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber )
#define SDL_WSCANF_VARARG_FUNC( fmtargnumber )
#endif
@ -379,7 +387,7 @@ SDL_COMPILE_TIME_ASSERT(enum, sizeof(SDL_DUMMY_ENUM) == sizeof(int));
extern "C" {
#endif
#ifdef HAVE_ALLOCA
#ifndef SDL_DISABLE_ALLOCA
#define SDL_stack_alloc(type, count) (type*)alloca(sizeof(type)*(count))
#define SDL_stack_free(data)
#else
@ -538,6 +546,7 @@ extern DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *dst, c
extern DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen);
extern DECLSPEC wchar_t *SDLCALL SDL_wcsdup(const wchar_t *wstr);
extern DECLSPEC wchar_t *SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle);
extern DECLSPEC wchar_t *SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen);
extern DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2);
extern DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen);
@ -558,6 +567,7 @@ extern DECLSPEC char *SDLCALL SDL_strlwr(char *str);
extern DECLSPEC char *SDLCALL SDL_strchr(const char *str, int c);
extern DECLSPEC char *SDLCALL SDL_strrchr(const char *str, int c);
extern DECLSPEC char *SDLCALL SDL_strstr(const char *haystack, const char *needle);
extern DECLSPEC char *SDLCALL SDL_strnstr(const char *haystack, const char *needle, size_t maxlen);
extern DECLSPEC char *SDLCALL SDL_strcasestr(const char *haystack, const char *needle);
extern DECLSPEC char *SDLCALL SDL_strtok_r(char *s1, const char *s2, char **saveptr);
extern DECLSPEC size_t SDLCALL SDL_utf8strlen(const char *str);
@ -584,13 +594,13 @@ extern DECLSPEC int SDLCALL SDL_strcasecmp(const char *str1, const char *str2);
extern DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, size_t len);
extern DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2);
extern DECLSPEC int SDLCALL SDL_vsscanf(const char *text, const char *fmt, va_list ap);
extern DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2);
extern DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ... ) SDL_PRINTF_VARARG_FUNC(3);
extern DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ... ) SDL_WPRINTF_VARARG_FUNC(3);
extern DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, const char *fmt, va_list ap);
extern DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3);
extern DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, const wchar_t *fmt, va_list ap);
extern DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
extern DECLSPEC int SDLCALL SDL_vasprintf(char **strp, const char *fmt, va_list ap);
extern DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
#ifndef SDL_PI_D
#define SDL_PI_D 3.141592653589793238462643383279502884 /**< pi (double) */
@ -684,8 +694,8 @@ extern DECLSPEC char *SDLCALL SDL_iconv_string(const char *tocode,
const char *inbuf,
size_t inbytesleft);
#define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1)
#define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2-INTERNAL", "UTF-8", S, SDL_strlen(S)+1)
#define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4-INTERNAL", "UTF-8", S, SDL_strlen(S)+1)
#define SDL_iconv_utf8_ucs2(S) (Uint16 *)SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1)
#define SDL_iconv_utf8_ucs4(S) (Uint32 *)SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1)
#define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", (char *)S, (SDL_wcslen(S)+1)*sizeof(wchar_t))
/* force builds using Clang's static analysis tools to use literal C runtime

118
include/SDL3/SDL_surface.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,16 +22,17 @@
/**
* \file SDL_surface.h
*
* \brief Header file for ::SDL_Surface definition and management functions.
* Header file for ::SDL_Surface definition and management functions.
*/
#ifndef SDL_surface_h_
#define SDL_surface_h_
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_pixels.h>
#include <SDL3/SDL_rect.h>
#include <SDL3/SDL_blendmode.h>
#include <SDL3/SDL_pixels.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_rect.h>
#include <SDL3/SDL_rwops.h>
#include <SDL3/SDL_begin_code.h>
@ -49,11 +50,12 @@ extern "C" {
* Used internally (read-only).
*/
/* @{ */
#define SDL_SWSURFACE 0 /**< Just here for compatibility */
#define SDL_PREALLOC 0x00000001 /**< Surface uses preallocated memory */
#define SDL_RLEACCEL 0x00000002 /**< Surface is RLE encoded */
#define SDL_DONTFREE 0x00000004 /**< Surface is referenced internally */
#define SDL_SIMD_ALIGNED 0x00000008 /**< Surface uses aligned memory */
#define SDL_SWSURFACE 0 /**< Just here for compatibility */
#define SDL_PREALLOC 0x00000001 /**< Surface uses preallocated memory */
#define SDL_RLEACCEL 0x00000002 /**< Surface is RLE encoded */
#define SDL_DONTFREE 0x00000004 /**< Surface is referenced internally */
#define SDL_SIMD_ALIGNED 0x00000008 /**< Surface uses aligned memory */
#define SDL_SURFACE_USES_PROPERTIES 0x00000010 /**< Surface uses properties */
/* @} *//* Surface flags */
/**
@ -64,10 +66,35 @@ extern "C" {
typedef struct SDL_BlitMap SDL_BlitMap; /* this is an opaque type. */
/**
* \brief A collection of pixels used in software blitting.
* The scaling mode
*/
typedef enum
{
SDL_SCALEMODE_NEAREST, /**< nearest pixel sampling */
SDL_SCALEMODE_LINEAR, /**< linear filtering */
SDL_SCALEMODE_BEST /**< anisotropic filtering */
} SDL_ScaleMode;
/**
* A collection of pixels used in software blitting.
*
* Pixels are arranged in memory in rows, with the top row first.
* Each row occupies an amount of memory given by the pitch (sometimes
* known as the row stride in non-SDL APIs).
*
* Within each row, pixels are arranged from left to right until the
* width is reached.
* Each pixel occupies a number of bits appropriate for its format, with
* most formats representing each pixel as one or more whole bytes
* (in some indexed formats, instead multiple pixels are packed into
* each byte), and a byte order given by the format.
* After encoding all pixels, any remaining bytes to reach the pitch are
* used as padding to reach a desired alignment, and have undefined contents.
*
* \note This structure should be treated as read-only, except for \c pixels,
* which, if not NULL, contains the raw pixel data for the surface.
* \sa SDL_CreateSurfaceFrom
*/
typedef struct SDL_Surface
{
@ -77,8 +104,7 @@ typedef struct SDL_Surface
int pitch; /**< Read-only */
void *pixels; /**< Read-write */
/** Application data associated with the surface */
void *userdata; /**< Read-write */
void *reserved; /**< Private */
/** information needed for surfaces requiring locks */
int locked; /**< Read-only */
@ -97,13 +123,13 @@ typedef struct SDL_Surface
} SDL_Surface;
/**
* \brief The type of function used for surface blitting functions.
* The type of function used for surface blitting functions.
*/
typedef int (SDLCALL *SDL_blit) (struct SDL_Surface *src, const SDL_Rect *srcrect,
struct SDL_Surface *dst, const SDL_Rect *dstrect);
/**
* \brief The formula used for converting between YUV and RGB
* The formula used for converting between YUV and RGB
*/
typedef enum
{
@ -175,6 +201,20 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurfaceFrom
*/
extern DECLSPEC void SDLCALL SDL_DestroySurface(SDL_Surface *surface);
/**
* Get the properties associated with a surface.
*
* \param surface the SDL_Surface structure to query
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surface *surface);
/**
* Set the palette used by a surface.
*
@ -817,10 +857,10 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
SDL_Surface *dst, const SDL_Rect *dstrect);
/**
* Perform a fast, low quality, stretch blit between two surfaces of the same
* format.
* Perform stretch blit between two surfaces of the same format.
*
* **WARNING**: Please use SDL_BlitSurfaceScaled() instead.
* Using SDL_SCALEMODE_NEAREST: fast, low quality. Using SDL_SCALEMODE_LINEAR:
* bilinear scaling, slower, better quality, only 32BPP.
*
* \param src the SDL_Surface structure to be copied from
* \param srcrect the SDL_Rect structure representing the rectangle to be
@ -828,35 +868,19 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
* \param dst the SDL_Surface structure that is the blit target
* \param dstrect the SDL_Rect structure representing the target rectangle in
* the destination surface
* \param scaleMode scale algorithm to be used
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_BlitSurfaceScaled
*/
extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src,
const SDL_Rect *srcrect,
SDL_Surface *dst,
const SDL_Rect *dstrect);
/**
* Perform bilinear scaling between two surfaces of the same format, 32BPP.
*
* \param src the SDL_Surface structure to be copied from
* \param srcrect the SDL_Rect structure representing the rectangle to be
* copied
* \param dst the SDL_Surface structure that is the blit target
* \param dstrect the SDL_Rect structure representing the target rectangle in
* the destination surface
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface *src,
const SDL_Rect *srcrect,
SDL_Surface *dst,
const SDL_Rect *dstrect);
const SDL_Rect *dstrect,
SDL_ScaleMode scaleMode);
/**
* Perform a scaled surface copy to a destination surface.
@ -868,6 +892,7 @@ extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface *src,
* \param dstrect the SDL_Rect structure representing the target rectangle in
* the destination surface, filled with the actual rectangle
* used after clipping
* \param scaleMode scale algorithm to be used
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -875,9 +900,11 @@ extern DECLSPEC int SDLCALL SDL_SoftStretchLinear(SDL_Surface *src,
*
* \sa SDL_BlitSurface
*/
extern DECLSPEC int SDLCALL SDL_BlitSurfaceScaled
(SDL_Surface *src, const SDL_Rect *srcrect,
SDL_Surface *dst, SDL_Rect *dstrect);
extern DECLSPEC int SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src,
const SDL_Rect *srcrect,
SDL_Surface *dst,
SDL_Rect *dstrect,
SDL_ScaleMode scaleMode);
/**
* Perform low-level surface scaled blitting only.
@ -891,6 +918,7 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceScaled
* \param dst the SDL_Surface structure that is the blit target
* \param dstrect the SDL_Rect structure representing the target rectangle in
* the destination surface
* \param scaleMode scale algorithm to be used
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -898,9 +926,11 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceScaled
*
* \sa SDL_BlitSurfaceScaled
*/
extern DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled
(SDL_Surface *src, const SDL_Rect *srcrect,
SDL_Surface *dst, const SDL_Rect *dstrect);
extern DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src,
const SDL_Rect *srcrect,
SDL_Surface *dst,
const SDL_Rect *dstrect,
SDL_ScaleMode scaleMode);
/**
* Set the YUV conversion mode

175
include/SDL3/SDL_system.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_system.h
*
* \brief Include file for platform specific SDL API functions
* Include file for platform specific SDL API functions
*/
#ifndef SDL_system_h_
@ -40,14 +40,21 @@ extern "C" {
#endif
/* Platform specific functions for Windows */
/*
* Platform specific functions for Windows
*/
#if defined(__WIN32__) || defined(__GDK__)
typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsigned int message, Uint64 wParam, Sint64 lParam);
typedef struct tagMSG MSG;
typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg);
/**
* Set a callback for every Windows message, run before TranslateMessage().
*
* The callback may modify the message, and should return SDL_TRUE if the
* message should continue to be processed, or SDL_FALSE to prevent further
* processing.
*
* \param callback The SDL_WindowsMessageHook function to call.
* \param userdata a pointer to pass to every iteration of `callback`
*
@ -73,60 +80,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook ca
*/
extern DECLSPEC int SDLCALL SDL_Direct3D9GetAdapterIndex(SDL_DisplayID displayID);
typedef struct IDirect3DDevice9 IDirect3DDevice9;
/**
* Get the D3D9 device associated with a renderer.
*
* Once you are done using the device, you should release it to avoid a
* resource leak.
*
* \param renderer the renderer from which to get the associated D3D device
* \returns the D3D9 device associated with given renderer or NULL if it is
* not a D3D9 renderer; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC IDirect3DDevice9* SDLCALL SDL_GetRenderD3D9Device(SDL_Renderer * renderer);
typedef struct ID3D11Device ID3D11Device;
/**
* Get the D3D11 device associated with a renderer.
*
* Once you are done using the device, you should release it to avoid a
* resource leak.
*
* \param renderer the renderer from which to get the associated D3D11 device
* \returns the D3D11 device associated with given renderer or NULL if it is
* not a D3D11 renderer; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC ID3D11Device* SDLCALL SDL_GetRenderD3D11Device(SDL_Renderer * renderer);
#endif /* defined(__WIN32__) || defined(__WINGDK__) */
#if defined(__WIN32__) || defined(__GDK__)
typedef struct ID3D12Device ID3D12Device;
/**
* Get the D3D12 device associated with a renderer.
*
* Once you are done using the device, you should release it to avoid a
* resource leak.
*
* \param renderer the renderer from which to get the associated D3D12 device
* \returns the D3D12 device associated with given renderer or NULL if it is
* not a D3D12 renderer; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC ID3D12Device* SDLCALL SDL_RenderGetD3D12Device(SDL_Renderer* renderer);
#endif /* defined(__WIN32__) || defined(__GDK__) */
#if defined(__WIN32__) || defined(__WINGDK__)
/**
@ -148,7 +103,30 @@ extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo(SDL_DisplayID displayID,
#endif /* defined(__WIN32__) || defined(__WINGDK__) */
/* Platform specific functions for Linux */
/*
* Platform specific functions for UNIX
*/
typedef union _XEvent XEvent;
typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);
/**
* Set a callback for every X11 event
*
* The callback may modify the event, and should return SDL_TRUE if the event
* should continue to be processed, or SDL_FALSE to prevent further
* processing.
*
* \param callback The SDL_X11EventHook function to call.
* \param userdata a pointer to pass to every iteration of `callback`
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata);
/*
* Platform specific functions for Linux
*/
#ifdef __LINUX__
/**
@ -182,7 +160,9 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriorityAndPolicy(Sint64 threadID,
#endif /* __LINUX__ */
/* Platform specific functions for iOS */
/*
* Platform specific functions for iOS
*/
#ifdef __IOS__
#define SDL_iOSSetAnimationCallback(window, interval, callback, callbackParam) SDL_iPhoneSetAnimationCallback(window, interval, callback, callbackParam)
@ -242,7 +222,9 @@ extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(SDL_bool enabled);
#endif /* __IOS__ */
/* Platform specific functions for Android */
/*
* Platform specific functions for Android
*/
#ifdef __ANDROID__
/**
@ -289,28 +271,31 @@ extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void);
/**
* Query Android API level of the current device.
*
* - API level 31: Android 12
* - API level 30: Android 11
* - API level 29: Android 10
* - API level 28: Android 9
* - API level 27: Android 8.1
* - API level 26: Android 8.0
* - API level 25: Android 7.1
* - API level 24: Android 7.0
* - API level 23: Android 6.0
* - API level 22: Android 5.1
* - API level 21: Android 5.0
* - API level 20: Android 4.4W
* - API level 19: Android 4.4
* - API level 18: Android 4.3
* - API level 17: Android 4.2
* - API level 16: Android 4.1
* - API level 15: Android 4.0.3
* - API level 14: Android 4.0
* - API level 13: Android 3.2
* - API level 12: Android 3.1
* - API level 11: Android 3.0
* - API level 10: Android 2.3.3
* - API level 34: Android 14 (UPSIDE_DOWN_CAKE)
* - API level 33: Android 13 (TIRAMISU)
* - API level 32: Android 12L (S_V2)
* - API level 31: Android 12 (S)
* - API level 30: Android 11 (R)
* - API level 29: Android 10 (Q)
* - API level 28: Android 9 (P)
* - API level 27: Android 8.1 (O_MR1)
* - API level 26: Android 8.0 (O)
* - API level 25: Android 7.1 (N_MR1)
* - API level 24: Android 7.0 (N)
* - API level 23: Android 6.0 (M)
* - API level 22: Android 5.1 (LOLLIPOP_MR1)
* - API level 21: Android 5.0 (LOLLIPOP, L)
* - API level 20: Android 4.4W (KITKAT_WATCH)
* - API level 19: Android 4.4 (KITKAT)
* - API level 18: Android 4.3 (JELLY_BEAN_MR2)
* - API level 17: Android 4.2 (JELLY_BEAN_MR1)
* - API level 16: Android 4.1 (JELLY_BEAN)
* - API level 15: Android 4.0.3 (ICE_CREAM_SANDWICH_MR1)
* - API level 14: Android 4.0 (ICE_CREAM_SANDWICH)
* - API level 13: Android 3.2 (HONEYCOMB_MR2)
* - API level 12: Android 3.1 (HONEYCOMB_MR1)
* - API level 11: Android 3.0 (HONEYCOMB)
* - API level 10: Android 2.3.3 (GINGERBREAD_MR1)
*
* \returns the Android API level.
*
@ -468,48 +453,50 @@ extern DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param);
#endif /* __ANDROID__ */
/* Platform specific functions for WinRT */
/*
* Platform specific functions for WinRT
*/
#ifdef __WINRT__
/**
* \brief WinRT / Windows Phone path types
* WinRT / Windows Phone path types
*/
typedef enum
{
/** \brief The installed app's root directory.
/** The installed app's root directory.
Files here are likely to be read-only. */
SDL_WINRT_PATH_INSTALLED_LOCATION,
/** \brief The app's local data store. Files may be written here */
/** The app's local data store. Files may be written here */
SDL_WINRT_PATH_LOCAL_FOLDER,
/** \brief The app's roaming data store. Unsupported on Windows Phone.
/** The app's roaming data store. Unsupported on Windows Phone.
Files written here may be copied to other machines via a network
connection.
*/
SDL_WINRT_PATH_ROAMING_FOLDER,
/** \brief The app's temporary data store. Unsupported on Windows Phone.
/** The app's temporary data store. Unsupported on Windows Phone.
Files written here may be deleted at any time. */
SDL_WINRT_PATH_TEMP_FOLDER
} SDL_WinRT_Path;
/**
* \brief WinRT Device Family
* WinRT Device Family
*/
typedef enum
{
/** \brief Unknown family */
/** Unknown family */
SDL_WINRT_DEVICEFAMILY_UNKNOWN,
/** \brief Desktop family*/
/** Desktop family*/
SDL_WINRT_DEVICEFAMILY_DESKTOP,
/** \brief Mobile family (for example smartphone) */
/** Mobile family (for example smartphone) */
SDL_WINRT_DEVICEFAMILY_MOBILE,
/** \brief XBox family */
/** XBox family */
SDL_WINRT_DEVICEFAMILY_XBOX,
} SDL_WinRT_DeviceFamily;
@ -630,7 +617,9 @@ extern DECLSPEC void SDLCALL SDL_OnApplicationDidBecomeActive(void);
extern DECLSPEC void SDLCALL SDL_OnApplicationDidChangeStatusBarOrientation(void);
#endif
/* Functions used only by GDK */
/*
* Functions used only by GDK
*/
#ifdef __GDK__
typedef struct XTaskQueueObject *XTaskQueueHandle;
typedef struct XUser *XUserHandle;

387
include/SDL3/SDL_syswm.h
View File

@ -1,387 +0,0 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_syswm.h
*
* \brief Include file for SDL custom system window manager hooks.
*/
#ifndef SDL_syswm_h_
#define SDL_syswm_h_
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_platform_defines.h>
#include <SDL3/SDL_video.h>
/**
* \brief SDL_syswm.h
*
* Your application has access to a special type of event ::SDL_EVENT_SYSWM,
* which contains window-manager specific information and arrives whenever
* an unhandled window event occurs. This event is ignored by default, but
* you can enable it with SDL_SetEventEnabled().
*/
/**
* The available subsystems based on platform
*/
#ifndef SDL_DISABLE_SYSWM_PLATFORMS
#ifndef SDL_DISABLE_SYSWM_ANDROID
#ifdef __ANDROID__
#define SDL_ENABLE_SYSWM_ANDROID
#endif
#endif /* !SDL_DISABLE_SYSWM_ANDROID */
#ifndef SDL_DISABLE_SYSWM_COCOA
#ifdef __MACOS__
#define SDL_ENABLE_SYSWM_COCOA
#endif
#endif /* !SDL_DISABLE_SYSWM_COCOA */
#ifndef SDL_DISABLE_SYSWM_HAIKU
#ifdef __HAIKU__
#define SDL_ENABLE_SYSWM_HAIKU
#endif
#endif /* !SDL_DISABLE_SYSWM_HAIKU */
#ifndef SDL_DISABLE_SYSWM_KMSDRM
#if defined(__LINUX__) || defined(__FREEBSD__) || defined(__OPENBSD__)
#define SDL_ENABLE_SYSWM_KMSDRM
#endif
#endif /* !SDL_DISABLE_SYSWM_KMSDRM */
#ifndef SDL_DISABLE_SYSWM_RISCOS
#ifdef __RISCOS__
#define SDL_ENABLE_SYSWM_RISCOS
#endif
#endif /* !SDL_DISABLE_SYSWM_RISCOS */
#ifndef SDL_DISABLE_SYSWM_UIKIT
#if defined(__IOS__) || defined(__TVOS__)
#define SDL_ENABLE_SYSWM_UIKIT
#endif
#endif /* !SDL_DISABLE_SYSWM_UIKIT */
#ifndef SDL_DISABLE_SYSWM_VIVANTE
/* Not enabled by default */
#endif /* !SDL_DISABLE_SYSWM_VIVANTE */
#ifndef SDL_DISABLE_SYSWM_WAYLAND
#if defined(__LINUX__) || defined(__FREEBSD__)
#define SDL_ENABLE_SYSWM_WAYLAND
#endif
#endif /* !SDL_DISABLE_SYSWM_WAYLAND */
#ifndef SDL_DISABLE_SYSWM_WINDOWS
#if defined(__WIN32__) || defined(__GDK__)
#define SDL_ENABLE_SYSWM_WINDOWS
#endif
#endif /* !SDL_DISABLE_SYSWM_WINDOWS */
#ifndef SDL_DISABLE_SYSWM_WINRT
#ifdef __WINRT__
#define SDL_ENABLE_SYSWM_WINRT
#endif
#endif /* !SDL_DISABLE_SYSWM_WINRT */
#ifndef SDL_DISABLE_SYSWM_X11
#if defined(__unix__) && !defined(__WIN32__) && !defined(__ANDROID__) && !defined(__QNX__)
#define SDL_ENABLE_SYSWM_X11
#endif
#endif /* !SDL_DISABLE_SYSWM_X11 */
#endif /* !SDL_DISABLE_SYSWM_PLATFORMS */
/**
* Forward declaration of types used by subsystems
*/
#ifndef SDL_DISABLE_SYSWM_TYPES
#if defined(SDL_ENABLE_SYSWM_ANDROID) && !defined(SDL_DISABLE_SYSWM_ANDROID_TYPES)
typedef struct ANativeWindow ANativeWindow;
typedef void *EGLSurface;
#endif /* SDL_ENABLE_SYSWM_ANDROID */
#if defined(SDL_ENABLE_SYSWM_COCOA) && !defined(SDL_DISABLE_SYSWM_COCOA_TYPES)
#ifdef __OBJC__
@class NSWindow;
#else
typedef struct _NSWindow NSWindow;
#endif
#endif /* SDL_ENABLE_SYSWM_COCOA */
#if defined(SDL_ENABLE_SYSWM_KMSDRM) && !defined(SDL_DISABLE_SYSWM_KMSDRM_TYPES)
struct gbm_device;
#endif /* SDL_ENABLE_SYSWM_KMSDRM */
#if defined(SDL_ENABLE_SYSWM_UIKIT) && !defined(SDL_DISABLE_SYSWM_UIKIT_TYPES)
#ifdef __OBJC__
#include <UIKit/UIKit.h>
#else
typedef struct _UIWindow UIWindow;
typedef struct _UIViewController UIViewController;
#endif
typedef Uint32 GLuint;
#endif /* SDL_ENABLE_SYSWM_UIKIT */
#if defined(SDL_ENABLE_SYSWM_VIVANTE) && !defined(SDL_DISABLE_SYSWM_VIVANTE_TYPES)
#include <SDL3/SDL_egl.h>
#endif /* SDL_ENABLE_SYSWM_VIVANTE */
#if defined(SDL_ENABLE_SYSWM_WAYLAND) && !defined(SDL_DISABLE_SYSWM_WAYLAND_TYPES)
struct wl_display;
struct wl_egl_window;
struct wl_surface;
struct xdg_popup;
struct xdg_positioner;
struct xdg_surface;
struct xdg_toplevel;
#endif /* SDL_ENABLE_SYSWM_WAYLAND */
#if defined(SDL_ENABLE_SYSWM_WINDOWS) && !defined(SDL_DISABLE_SYSWM_WINDOWS_TYPES)
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#ifndef NOMINMAX /* don't define min() and max(). */
#define NOMINMAX
#endif
#include <windows.h>
#endif /* SDL_ENABLE_SYSWM_WINDOWS */
#if defined(SDL_ENABLE_SYSWM_WINRT) && !defined(SDL_DISABLE_SYSWM_WINRT_TYPES)
#include <Inspectable.h>
#endif /* SDL_ENABLE_SYSWM_WINRT */
#if defined(SDL_ENABLE_SYSWM_X11) && !defined(SDL_DISABLE_SYSWM_X11_TYPES)
#include <X11/Xlib.h>
#include <X11/Xatom.h>
#endif /* SDL_ENABLE_SYSWM_X11 */
#endif /* !SDL_DISABLE_SYSWM_TYPES */
#include <SDL3/SDL_begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {
#endif
/* This is the current version of structures in this file */
#define SDL_SYSWM_CURRENT_VERSION 1
#define SDL_SYSWM_INFO_SIZE_V1 (16 * (sizeof (void *) >= 8 ? sizeof (void *) : sizeof(Uint64)))
#define SDL_SYSWM_CURRENT_INFO_SIZE SDL_SYSWM_INFO_SIZE_V1
/* This is the tag associated with a Metal view so you can find it */
#define SDL_METALVIEW_TAG 255
/**
* These are the various supported windowing subsystems
*/
typedef enum
{
SDL_SYSWM_UNKNOWN,
SDL_SYSWM_ANDROID,
SDL_SYSWM_COCOA,
SDL_SYSWM_HAIKU,
SDL_SYSWM_KMSDRM,
SDL_SYSWM_RISCOS,
SDL_SYSWM_UIKIT,
SDL_SYSWM_VIVANTE,
SDL_SYSWM_WAYLAND,
SDL_SYSWM_WINDOWS,
SDL_SYSWM_WINRT,
SDL_SYSWM_X11
} SDL_SYSWM_TYPE;
/**
* The custom event structure.
*/
struct SDL_SysWMmsg
{
Uint32 version;
Uint32 subsystem; /**< SDL_SYSWM_TYPE */
Uint32 padding[(2 * (sizeof (void *) >= 8 ? sizeof (void *) : sizeof(Uint64)) - 2 * sizeof(Uint32)) / sizeof(Uint32)];
union
{
#ifdef SDL_ENABLE_SYSWM_WINDOWS
struct {
HWND hwnd; /**< The window for the message */
UINT msg; /**< The type of message */
WPARAM wParam; /**< WORD message parameter */
LPARAM lParam; /**< LONG message parameter */
} win;
#endif
#ifdef SDL_ENABLE_SYSWM_X11
struct {
XEvent event;
} x11;
#endif
/* Can't have an empty union */
int dummy;
} msg;
};
/**
* The custom window manager information structure.
*
* When this structure is returned, it holds information about which
* low level system it is using, and will be one of SDL_SYSWM_TYPE.
*/
struct SDL_SysWMinfo
{
Uint32 version;
Uint32 subsystem; /**< SDL_SYSWM_TYPE */
Uint32 padding[(2 * (sizeof (void *) >= 8 ? sizeof (void *) : sizeof(Uint64)) - 2 * sizeof(Uint32)) / sizeof(Uint32)];
union
{
#ifdef SDL_ENABLE_SYSWM_WINDOWS
struct
{
HWND window; /**< The window handle */
HDC hdc; /**< The window device context */
HINSTANCE hinstance; /**< The instance handle */
} win;
#endif
#ifdef SDL_ENABLE_SYSWM_WINRT
struct
{
IInspectable * window; /**< The WinRT CoreWindow */
} winrt;
#endif
#ifdef SDL_ENABLE_SYSWM_X11
struct
{
Display *display; /**< The X11 display */
int screen; /**< The X11 screen */
Window window; /**< The X11 window */
} x11;
#endif
#ifdef SDL_ENABLE_SYSWM_COCOA
struct
{
#if defined(__OBJC__) && defined(__has_feature)
#if __has_feature(objc_arc)
NSWindow __unsafe_unretained *window; /**< The Cocoa window */
#else
NSWindow *window; /**< The Cocoa window */
#endif
#else
NSWindow *window; /**< The Cocoa window */
#endif
} cocoa;
#endif
#ifdef SDL_ENABLE_SYSWM_UIKIT
struct
{
#if defined(__OBJC__) && defined(__has_feature)
#if __has_feature(objc_arc)
UIWindow __unsafe_unretained *window; /**< The UIKit window */
#else
UIWindow *window; /**< The UIKit window */
#endif
#else
UIWindow *window; /**< The UIKit window */
#endif
GLuint framebuffer; /**< The GL view's Framebuffer Object. It must be bound when rendering to the screen using GL. */
GLuint colorbuffer; /**< The GL view's color Renderbuffer Object. It must be bound when SDL_GL_SwapWindow is called. */
GLuint resolveFramebuffer; /**< The Framebuffer Object which holds the resolve color Renderbuffer, when MSAA is used. */
} uikit;
#endif
#ifdef SDL_ENABLE_SYSWM_WAYLAND
struct
{
struct wl_display *display; /**< Wayland display */
struct wl_surface *surface; /**< Wayland surface */
struct wl_egl_window *egl_window; /**< Wayland EGL window (native window) */
struct xdg_surface *xdg_surface; /**< Wayland xdg surface (window manager handle) */
struct xdg_toplevel *xdg_toplevel; /**< Wayland xdg toplevel role */
struct xdg_popup *xdg_popup; /**< Wayland xdg popup role */
struct xdg_positioner *xdg_positioner; /**< Wayland xdg positioner, for popup */
} wl;
#endif
#ifdef SDL_ENABLE_SYSWM_ANDROID
struct
{
ANativeWindow *window;
EGLSurface surface;
} android;
#endif
#ifdef SDL_ENABLE_SYSWM_VIVANTE
struct
{
EGLNativeDisplayType display;
EGLNativeWindowType window;
} vivante;
#endif
#ifdef SDL_ENABLE_SYSWM_KMSDRM
struct
{
int dev_index; /**< Device index (ex: the X in /dev/dri/cardX) */
int drm_fd; /**< DRM FD (unavailable on Vulkan windows) */
struct gbm_device *gbm_dev; /**< GBM device (unavailable on Vulkan windows) */
} kmsdrm;
#endif
/* Make sure this union has enough room for 14 pointers */
void *dummy_ptrs[14];
Uint64 dummy_ints[14];
} info;
};
SDL_COMPILE_TIME_ASSERT(SDL_SysWMinfo_size, sizeof(struct SDL_SysWMinfo) == SDL_SYSWM_CURRENT_INFO_SIZE);
typedef struct SDL_SysWMinfo SDL_SysWMinfo;
/**
* Get driver-specific information about a window.
*
* You must include SDL_syswm.h for the declaration of SDL_SysWMinfo.
*
* \param window the window about which information is being requested
* \param info an SDL_SysWMinfo structure filled in with window information
* \param version the version of info being requested, should be
* SDL_SYSWM_CURRENT_VERSION
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_GetWindowWMInfo(SDL_Window *window, SDL_SysWMinfo *info, Uint32 version);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif
#include <SDL3/SDL_close_code.h>
#endif /* SDL_syswm_h_ */

4
include/SDL3/SDL_test.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test.h
*
* \brief Include file for SDL test framework.
* Include file for SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/

20
include/SDL3/SDL_test_assert.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test_assert.h
*
* \brief Assertion functions of SDL test framework.
* Assertion functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
@ -43,17 +43,17 @@ extern "C" {
#endif
/**
* \brief Fails the assert.
* Fails the assert.
*/
#define ASSERT_FAIL 0
/**
* \brief Passes the assert.
* Passes the assert.
*/
#define ASSERT_PASS 1
/**
* \brief Assert that logs and break execution flow on failures.
* Assert that logs and break execution flow on failures.
*
* \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0).
* \param assertDescription Message to log with the assert describing it.
@ -61,7 +61,7 @@ extern "C" {
void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
* \brief Assert for test cases that logs but does not break execution flow on failures. Updates assertion counters.
* Assert for test cases that logs but does not break execution flow on failures. Updates assertion counters.
*
* \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0).
* \param assertDescription Message to log with the assert describing it.
@ -71,25 +71,25 @@ void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *as
int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
* \brief Explicitly pass without checking an assertion condition. Updates assertion counter.
* Explicitly pass without checking an assertion condition. Updates assertion counter.
*
* \param assertDescription Message to log with the assert describing it.
*/
void SDLTest_AssertPass(SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(1);
/**
* \brief Resets the assert summary counters to zero.
* Resets the assert summary counters to zero.
*/
void SDLTest_ResetAssertSummary(void);
/**
* \brief Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR.
* Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR.
*/
void SDLTest_LogAssertSummary(void);
/**
* \brief Converts the current assert summary state to a test result.
* Converts the current assert summary state to a test result.
*
* \returns TEST_RESULT_PASSED, TEST_RESULT_FAILED, or TEST_RESULT_NO_ASSERT
*/

36
include/SDL3/SDL_test_common.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test_common.h
*
* \brief Common functions of SDL test framework.
* Common functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
@ -139,7 +139,7 @@ extern "C" {
/* Function prototypes */
/**
* \brief Parse command line parameters and create common state.
* Parse command line parameters and create common state.
*
* \param argv Array of command line parameters
* \param flags Flags indicating which subsystem to initialize (i.e. SDL_INIT_VIDEO | SDL_INIT_AUDIO)
@ -149,14 +149,14 @@ extern "C" {
SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
/**
* \brief Free the common state object.
* Free the common state object.
*
* \param state The common state object to destroy
*/
void SDLTest_CommonDestroyState(SDLTest_CommonState *state);
/**
* \brief Process one common argument.
* Process one common argument.
*
* \param state The common state describing the test window to create.
* \param index The index of the argument to process in argv[].
@ -167,7 +167,7 @@ int SDLTest_CommonArg(SDLTest_CommonState *state, int index);
/**
* \brief Logs command line usage info.
* Logs command line usage info.
*
* This logs the appropriate command line options for the subsystems in use
* plus other common options, and then any application-specific options.
@ -181,7 +181,7 @@ int SDLTest_CommonArg(SDLTest_CommonState *state, int index);
void SDLTest_CommonLogUsage(SDLTest_CommonState *state, const char *argv0, const char **options);
/**
* \brief Open test window.
* Open test window.
*
* \param state The common state describing the test window to create.
*
@ -190,7 +190,7 @@ void SDLTest_CommonLogUsage(SDLTest_CommonState *state, const char *argv0, const
SDL_bool SDLTest_CommonInit(SDLTest_CommonState *state);
/**
* \brief Easy argument handling when test app doesn't need any custom args.
* Easy argument handling when test app doesn't need any custom args.
*
* \param state The common state describing the test window to create.
* \param argc argc, as supplied to SDL_main
@ -201,17 +201,29 @@ SDL_bool SDLTest_CommonInit(SDLTest_CommonState *state);
SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState *state, const int argc, char **argv);
/**
* \brief Common event handler for test windows.
* Common event handler for test windows if you use a standard SDL_main.
*
* This will free data from the event, like the string in a drop event!
*
* \param state The common state used to create test window.
* \param event The event to handle.
* \param done Flag indicating we are done.
*
*/
void SDLTest_CommonEvent(SDLTest_CommonState *state, SDL_Event *event, int *done);
/**
* \brief Close test window.
* Common event handler for test windows if you use SDL_AppEvent.
*
* This does _not_ free anything in `event`.
*
* \param state The common state used to create test window.
* \param event The event to handle.
* \returns Value suitable for returning from SDL_AppEvent().
*/
int SDLTest_CommonEventMainCallbacks(SDLTest_CommonState *state, const SDL_Event *event);
/**
* Close test window.
*
* \param state The common state used to create test window.
*
@ -219,7 +231,7 @@ void SDLTest_CommonEvent(SDLTest_CommonState *state, SDL_Event *event, int *done
void SDLTest_CommonQuit(SDLTest_CommonState *state);
/**
* \brief Draws various window information (position, size, etc.) to the renderer.
* Draws various window information (position, size, etc.) to the renderer.
*
* \param renderer The renderer to draw to.
* \param window The window whose information should be displayed.

27
include/SDL3/SDL_test_compare.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test_compare.h
*
* \brief Comparison function of SDL test framework.
* Comparison function of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
@ -45,7 +45,28 @@ extern "C" {
#endif
/**
* \brief Compares a surface and with reference image data for equality
* Retrieves a single pixel from a surface.
*
* This function prioritizes correctness over speed: it is suitable for
* unit tests, but is not intended for use in a game engine.
*
* Like SDL_GetRGBA, this uses the entire 0..255 range when converting
* color components from pixel formats with less than 8 bits per RGB
* component.
*
* \param surface The surface
* \param x Horizontal coordinate, 0 <= x < width
* \param y Vertical coordinate, 0 <= y < height
* \param r Pointer to location to store red channel, 0-255
* \param g Pointer to location to store green channel, 0-255
* \param b Pointer to location to store blue channel, 0-255
* \param a Pointer to location to store alpha channel, 0-255
* \returns 0 if the surface is valid and the coordinates are in-bounds
*/
int SDLTest_ReadSurfacePixel(SDL_Surface *surface, int x, int y, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
/**
* Compares a surface and with reference image data for equality
*
* \param surface Surface used in comparison
* \param referenceSurface Test Surface used in comparison

10
include/SDL3/SDL_test_crc32.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test_crc32.h
*
* \brief CRC32 functions of SDL test framework.
* CRC32 functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
@ -70,7 +70,7 @@ extern "C" {
/* ---------- Function Prototypes ------------- */
/**
* \brief Initialize the CRC context
* Initialize the CRC context
*
* Note: The function initializes the crc table required for all crc calculations.
*
@ -83,7 +83,7 @@ extern "C" {
/**
* \brief calculate a crc32 from a data block
* calculate a crc32 from a data block
*
* \param crcContext pointer to context variable
* \param inBuf input buffer to checksum
@ -102,7 +102,7 @@ int SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, C
/**
* \brief clean up CRC context
* clean up CRC context
*
* \param crcContext pointer to context variable
*

24
include/SDL3/SDL_test_font.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test_font.h
*
* \brief Font related functions of SDL test framework.
* Font related functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
@ -43,7 +43,7 @@ extern int FONT_CHARACTER_SIZE;
#define FONT_LINE_HEIGHT (FONT_CHARACTER_SIZE + 2)
/**
* \brief Draw a string in the currently set font.
* Draw a string in the currently set font.
*
* \param renderer The renderer to draw on.
* \param x The X coordinate of the upper left corner of the character.
@ -55,7 +55,7 @@ extern int FONT_CHARACTER_SIZE;
int SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c);
/**
* \brief Draw a UTF-8 string in the currently set font.
* Draw a UTF-8 string in the currently set font.
*
* The font currently only supports characters in the Basic Latin and Latin-1 Supplement sets.
*
@ -69,7 +69,7 @@ int SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c);
int SDLTest_DrawString(SDL_Renderer *renderer, float x, float y, const char *s);
/**
* \brief Data used for multi-line text output
* Data used for multi-line text output
*/
typedef struct SDLTest_TextWindow
{
@ -80,7 +80,7 @@ typedef struct SDLTest_TextWindow
} SDLTest_TextWindow;
/**
* \brief Create a multi-line text output window
* Create a multi-line text output window
*
* \param x The X coordinate of the upper left corner of the window.
* \param y The Y coordinate of the upper left corner of the window.
@ -94,7 +94,7 @@ typedef struct SDLTest_TextWindow
SDLTest_TextWindow *SDLTest_TextWindowCreate(float x, float y, float w, float h);
/**
* \brief Display a multi-line text output window
* Display a multi-line text output window
*
* This function should be called every frame to display the text
*
@ -106,7 +106,7 @@ SDLTest_TextWindow *SDLTest_TextWindowCreate(float x, float y, float w, float h)
void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *renderer);
/**
* \brief Add text to a multi-line text output window
* Add text to a multi-line text output window
*
* Adds UTF-8 text to the end of the current text. The newline character starts a
* new line of text. The backspace character deletes the last character or, if the
@ -121,7 +121,7 @@ void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *render
void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
/**
* \brief Add text to a multi-line text output window
* Add text to a multi-line text output window
*
* Adds UTF-8 text to the end of the current text. The newline character starts a
* new line of text. The backspace character deletes the last character or, if the
@ -136,7 +136,7 @@ void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_ST
void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char *text, size_t len);
/**
* \brief Clear the text in a multi-line text output window
* Clear the text in a multi-line text output window
*
* \param textwin The text output window
*
@ -145,7 +145,7 @@ void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char
void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin);
/**
* \brief Free the storage associated with a multi-line text output window
* Free the storage associated with a multi-line text output window
*
* \param textwin The text output window
*
@ -154,7 +154,7 @@ void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin);
void SDLTest_TextWindowDestroy(SDLTest_TextWindow *textwin);
/**
* \brief Cleanup textures used by font drawing functions.
* Cleanup textures used by font drawing functions.
*/
void SDLTest_CleanupTextDrawing(void);

4
include/SDL3/SDL_test_fuzzer.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test_fuzzer.h
*
* \brief Fuzzer functions of SDL test framework.
* Fuzzer functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/

8
include/SDL3/SDL_test_harness.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test_harness.h
*
* \brief Test suite related functions of SDL test framework.
* Test suite related functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
@ -99,7 +99,7 @@ typedef struct SDLTest_TestSuiteReference {
/**
* \brief Generates a random run seed string for the harness. The generated seed will contain alphanumeric characters (0-9A-Z).
* Generates a random run seed string for the harness. The generated seed will contain alphanumeric characters (0-9A-Z).
*
* Note: The returned string needs to be deallocated by the caller.
*
@ -110,7 +110,7 @@ typedef struct SDLTest_TestSuiteReference {
char *SDLTest_GenerateRunSeed(const int length);
/**
* \brief Execute a test suite using the given run seed and execution key.
* Execute a test suite using the given run seed and execution key.
*
* \param testSuites Suites containing the test case.
* \param userRunSeed Custom run seed provided by user, or NULL to autogenerate one.

8
include/SDL3/SDL_test_log.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test_log.h
*
* \brief Logging related functions of SDL test framework.
* Logging related functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
@ -43,14 +43,14 @@ extern "C" {
#endif
/**
* \brief Prints given message with a timestamp in the TEST category and INFO priority.
* Prints given message with a timestamp in the TEST category and INFO priority.
*
* \param fmt Message to be logged
*/
void SDLTest_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(1);
/**
* \brief Prints given message with a timestamp in the TEST category and the ERROR priority.
* Prints given message with a timestamp in the TEST category and the ERROR priority.
*
* \param fmt Message to be logged
*/

10
include/SDL3/SDL_test_md5.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test_md5.h
*
* \brief MD5 related functions of SDL test framework.
* MD5 related functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
@ -78,7 +78,7 @@ extern "C" {
/* ---------- Function Prototypes ------------- */
/**
* \brief initialize the context
* initialize the context
*
* \param mdContext pointer to context variable
*
@ -90,7 +90,7 @@ extern "C" {
/**
* \brief update digest from variable length data
* update digest from variable length data
*
* \param mdContext pointer to context variable
* \param inBuf pointer to data array/string
@ -106,7 +106,7 @@ extern "C" {
/**
* \brief complete digest computation
* complete digest computation
*
* \param mdContext pointer to context variable
*

10
include/SDL3/SDL_test_memory.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test_memory.h
*
* \brief Memory tracking related functions of SDL test framework.
* Memory tracking related functions of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
@ -38,21 +38,21 @@ extern "C" {
/**
* \brief Start tracking SDL memory allocations
* Start tracking SDL memory allocations
*
* \note This should be called before any other SDL functions for complete tracking coverage
*/
void SDLTest_TrackAllocations(void);
/**
* \brief Fill allocations with random data
* Fill allocations with random data
*
* \note This implicitly calls SDLTest_TrackAllocations()
*/
void SDLTest_RandFillAllocations();
/**
* \brief Print a log of any outstanding allocations
* Print a log of any outstanding allocations
*
* \note This can be called after SDL_Quit()
*/

10
include/SDL3/SDL_test_random.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_test_random.h
*
* \brief Random number generator related function of SDL test framework.
* Random number generator related function of SDL test framework.
*
* This code is a part of the SDL test library, not the main SDL library.
*/
@ -68,7 +68,7 @@ extern "C" {
/* --- Function prototypes */
/**
* \brief Initialize random number generator with two integers.
* Initialize random number generator with two integers.
*
* Note: The random sequence of numbers returned by ...Random() is the
* same for the same two integers and has a period of 2^31.
@ -81,7 +81,7 @@ extern "C" {
void SDLTest_RandomInit(SDLTest_RandomContext *rndContext, unsigned int xi, unsigned int ci);
/**
* \brief Initialize random number generator based on current system time.
* Initialize random number generator based on current system time.
*
* \param rndContext pointer to context structure
*
@ -90,7 +90,7 @@ extern "C" {
/**
* \brief Initialize random number generator based on current system time.
* Initialize random number generator based on current system time.
*
* Note: ...RandomInit() or ...RandomInitTime() must have been called
* before using this function.

4
include/SDL3/SDL_thread.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -25,7 +25,7 @@
/**
* \file SDL_thread.h
*
* \brief Header for the SDL thread management routines.
* Header for the SDL thread management routines.
*/
#include <SDL3/SDL_stdinc.h>

4
include/SDL3/SDL_timer.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -25,7 +25,7 @@
/**
* \file SDL_timer.h
*
* \brief Header for the SDL time management routines.
* Header for the SDL time management routines.
*/
#include <SDL3/SDL_stdinc.h>

44
include/SDL3/SDL_touch.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_touch.h
*
* \brief Include file for SDL touch event handling.
* Include file for SDL touch event handling.
*/
#ifndef SDL_touch_h_
@ -65,46 +65,36 @@ typedef struct SDL_Finger
/**
* Get the number of registered touch devices.
* Get a list of registered touch devices.
*
* On some platforms SDL first sees the touch device if it was actually used.
* Therefore SDL_GetNumTouchDevices() may return 0 although devices are
* available. After using all devices at least once the number will be
* correct.
* Therefore the returned list might be empty, although devices are available.
* After using all devices at least once the number will be correct.
*
* This was fixed for Android in SDL 2.0.1.
*
* \returns the number of registered touch devices.
* \param count a pointer filled in with the number of devices returned, can
* be NULL.
* \returns a 0 terminated array of touch device IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetTouchDevice
*/
extern DECLSPEC int SDLCALL SDL_GetNumTouchDevices(void);
extern DECLSPEC SDL_TouchID *SDLCALL SDL_GetTouchDevices(int *count);
/**
* Get the touch ID with the given index.
* Get the touch device name as reported from the driver.
*
* \param index the touch device index
* \returns the touch ID with the given index on success or 0 if the index is
* invalid; call SDL_GetError() for more information.
* You do not own the returned string, do not modify or free it.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetNumTouchDevices
*/
extern DECLSPEC SDL_TouchID SDLCALL SDL_GetTouchDevice(int index);
/**
* Get the touch device name as reported from the driver or NULL if the index
* is invalid.
*
* \param index the touch device index
* \returns touch device name
* \param touchID the touch device instance ID.
* \returns touch device name, or NULL on error; call SDL_GetError() for more
* details.
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC const char* SDLCALL SDL_GetTouchName(int index);
extern DECLSPEC const char* SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touchID);
/**
* Get the type of the given touch device.

4
include/SDL3/SDL_version.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_version.h
*
* \brief This header defines the current SDL version.
* This header defines the current SDL version.
*/
#ifndef SDL_version_h_

691
include/SDL3/SDL_video.h
View File

@ -1,6 +1,6 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
@ -22,7 +22,7 @@
/**
* \file SDL_video.h
*
* \brief Header file for SDL video functions.
* Header file for SDL video functions.
*/
#ifndef SDL_video_h_
@ -30,6 +30,7 @@
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_pixels.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_rect.h>
#include <SDL3/SDL_surface.h>
@ -44,7 +45,23 @@ typedef Uint32 SDL_DisplayID;
typedef Uint32 SDL_WindowID;
/**
* \brief System theme
* Global video properties
*
* - `SDL_PROPERTY_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER`: the pointer to
* the global `wl_display` object used by the Wayland video backend. Can be
* set before the video subsystem is initialized to import an external
* `wl_display` object from an application or toolkit for use in SDL, or
* read after initialization to export the `wl_display` used by the
* Wayland video backend. Setting this property after the video subsystem
* has been initialized has no effect, and reading it when the video
* subsystem is uninitialized will either return the user provided value,
* if one was set prior to initialization, or NULL. See
* docs/README-wayland.md for more information.
*/
#define SDL_PROPERTY_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER "video.wayland.wl_display"
/**
* System theme
*/
typedef enum
{
@ -54,7 +71,7 @@ typedef enum
} SDL_SystemTheme;
/**
* \brief The structure that defines a display mode
* The structure that defines a display mode
*
* \sa SDL_GetFullscreenDisplayModes()
* \sa SDL_GetDesktopDisplayMode()
@ -74,7 +91,7 @@ typedef struct
} SDL_DisplayMode;
/**
* \brief Display orientation
* Display orientation
*/
typedef enum
{
@ -86,77 +103,70 @@ typedef enum
} SDL_DisplayOrientation;
/**
* \brief The type used to identify a window
* The type used to identify a window
*
* \sa SDL_CreateWindow()
* \sa SDL_CreateWindowFrom()
* \sa SDL_CreateWindowWithPosition()
* \sa SDL_DestroyWindow()
* \sa SDL_FlashWindow()
* \sa SDL_GetWindowData()
* \sa SDL_GetWindowFlags()
* \sa SDL_GetWindowGrab()
* \sa SDL_GetWindowKeyboardGrab()
* \sa SDL_GetWindowMouseGrab()
* \sa SDL_GetWindowPosition()
* \sa SDL_GetWindowSize()
* \sa SDL_GetWindowTitle()
* \sa SDL_HideWindow()
* \sa SDL_MaximizeWindow()
* \sa SDL_MinimizeWindow()
* \sa SDL_RaiseWindow()
* \sa SDL_RestoreWindow()
* \sa SDL_SetWindowData()
* \sa SDL_SetWindowFullscreen()
* \sa SDL_SetWindowGrab()
* \sa SDL_SetWindowKeyboardGrab()
* \sa SDL_SetWindowMouseGrab()
* \sa SDL_SetWindowIcon()
* \sa SDL_SetWindowPosition()
* \sa SDL_SetWindowSize()
* \sa SDL_SetWindowBordered()
* \sa SDL_SetWindowResizable()
* \sa SDL_SetWindowTitle()
* \sa SDL_ShowWindow()
* \sa SDL_ShowWindowSystemMenu()
* \sa SDL_CreateWindow
* \sa SDL_CreateWindowWithProperties
* \sa SDL_DestroyWindow
* \sa SDL_FlashWindow
* \sa SDL_GetWindowFlags
* \sa SDL_GetWindowGrab
* \sa SDL_GetWindowKeyboardGrab
* \sa SDL_GetWindowMouseGrab
* \sa SDL_GetWindowPosition
* \sa SDL_GetWindowSize
* \sa SDL_GetWindowTitle
* \sa SDL_HideWindow
* \sa SDL_MaximizeWindow
* \sa SDL_MinimizeWindow
* \sa SDL_RaiseWindow
* \sa SDL_RestoreWindow
* \sa SDL_SetWindowFullscreen
* \sa SDL_SetWindowGrab
* \sa SDL_SetWindowKeyboardGrab
* \sa SDL_SetWindowMouseGrab
* \sa SDL_SetWindowIcon
* \sa SDL_SetWindowPosition
* \sa SDL_SetWindowSize
* \sa SDL_SetWindowBordered
* \sa SDL_SetWindowResizable
* \sa SDL_SetWindowTitle
* \sa SDL_ShowWindow
* \sa SDL_ShowWindowSystemMenu
*/
typedef struct SDL_Window SDL_Window;
/**
* \brief The flags on a window
* The flags on a window
*
* \sa SDL_GetWindowFlags()
* \sa SDL_GetWindowFlags
*/
typedef enum
{
SDL_WINDOW_FULLSCREEN = 0x00000001, /**< window is in fullscreen mode */
SDL_WINDOW_OPENGL = 0x00000002, /**< window usable with OpenGL context */
SDL_WINDOW_OCCLUDED = 0x00000004, /**< window is occluded */
SDL_WINDOW_HIDDEN = 0x00000008, /**< window is neither mapped onto the desktop nor shown in the taskbar/dock/window list; SDL_ShowWindow() is required for it to become visible */
SDL_WINDOW_BORDERLESS = 0x00000010, /**< no window decoration */
SDL_WINDOW_RESIZABLE = 0x00000020, /**< window can be resized */
SDL_WINDOW_MINIMIZED = 0x00000040, /**< window is minimized */
SDL_WINDOW_MAXIMIZED = 0x00000080, /**< window is maximized */
SDL_WINDOW_MOUSE_GRABBED = 0x00000100, /**< window has grabbed mouse input */
SDL_WINDOW_INPUT_FOCUS = 0x00000200, /**< window has input focus */
SDL_WINDOW_MOUSE_FOCUS = 0x00000400, /**< window has mouse focus */
SDL_WINDOW_FOREIGN = 0x00000800, /**< window not created by SDL */
SDL_WINDOW_HIGH_PIXEL_DENSITY = 0x00002000, /**< window uses high pixel density back buffer if possible */
SDL_WINDOW_MOUSE_CAPTURE = 0x00004000, /**< window has mouse captured (unrelated to MOUSE_GRABBED) */
SDL_WINDOW_ALWAYS_ON_TOP = 0x00008000, /**< window should always be above others */
SDL_WINDOW_UTILITY = 0x00020000, /**< window should be treated as a utility window, not showing in the task bar and window list */
SDL_WINDOW_TOOLTIP = 0x00040000, /**< window should be treated as a tooltip and must be created using SDL_CreatePopupWindow() */
SDL_WINDOW_POPUP_MENU = 0x00080000, /**< window should be treated as a popup menu and must be created using SDL_CreatePopupWindow() */
SDL_WINDOW_KEYBOARD_GRABBED = 0x00100000, /**< window has grabbed keyboard input */
SDL_WINDOW_VULKAN = 0x10000000, /**< window usable for Vulkan surface */
SDL_WINDOW_METAL = 0x20000000, /**< window usable for Metal view */
SDL_WINDOW_TRANSPARENT = 0x40000000, /**< window with transparent buffer */
SDL_WINDOW_NOT_FOCUSABLE = 0x80000000, /**< window should not be focusable */
} SDL_WindowFlags;
#define SDL_WINDOW_FULLSCREEN 0x00000001U /**< window is in fullscreen mode */
#define SDL_WINDOW_OPENGL 0x00000002U /**< window usable with OpenGL context */
#define SDL_WINDOW_OCCLUDED 0x00000004U /**< window is occluded */
#define SDL_WINDOW_HIDDEN 0x00000008U /**< window is neither mapped onto the desktop nor shown in the taskbar/dock/window list; SDL_ShowWindow() is required for it to become visible */
#define SDL_WINDOW_BORDERLESS 0x00000010U /**< no window decoration */
#define SDL_WINDOW_RESIZABLE 0x00000020U /**< window can be resized */
#define SDL_WINDOW_MINIMIZED 0x00000040U /**< window is minimized */
#define SDL_WINDOW_MAXIMIZED 0x00000080U /**< window is maximized */
#define SDL_WINDOW_MOUSE_GRABBED 0x00000100U /**< window has grabbed mouse input */
#define SDL_WINDOW_INPUT_FOCUS 0x00000200U /**< window has input focus */
#define SDL_WINDOW_MOUSE_FOCUS 0x00000400U /**< window has mouse focus */
#define SDL_WINDOW_EXTERNAL 0x00000800U /**< window not created by SDL */
#define SDL_WINDOW_HIGH_PIXEL_DENSITY 0x00002000U /**< window uses high pixel density back buffer if possible */
#define SDL_WINDOW_MOUSE_CAPTURE 0x00004000U /**< window has mouse captured (unrelated to MOUSE_GRABBED) */
#define SDL_WINDOW_ALWAYS_ON_TOP 0x00008000U /**< window should always be above others */
#define SDL_WINDOW_UTILITY 0x00020000U /**< window should be treated as a utility window, not showing in the task bar and window list */
#define SDL_WINDOW_TOOLTIP 0x00040000U /**< window should be treated as a tooltip */
#define SDL_WINDOW_POPUP_MENU 0x00080000U /**< window should be treated as a popup menu */
#define SDL_WINDOW_KEYBOARD_GRABBED 0x00100000U /**< window has grabbed keyboard input */
#define SDL_WINDOW_VULKAN 0x10000000U /**< window usable for Vulkan surface */
#define SDL_WINDOW_METAL 0x20000000U /**< window usable for Metal view */
#define SDL_WINDOW_TRANSPARENT 0x40000000U /**< window with transparent buffer */
#define SDL_WINDOW_NOT_FOCUSABLE 0x80000000U /**< window should not be focusable */
/**
* \brief Used to indicate that you don't care what the window position is.
* Used to indicate that you don't care what the window position is.
*/
#define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u
#define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X))
@ -165,7 +175,7 @@ typedef enum
(((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK)
/**
* \brief Used to indicate that the window position should be centered.
* Used to indicate that the window position should be centered.
*/
#define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u
#define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X))
@ -174,7 +184,7 @@ typedef enum
(((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK)
/**
* \brief Window flash operation
* Window flash operation
*/
typedef enum
{
@ -184,12 +194,12 @@ typedef enum
} SDL_FlashOperation;
/**
* \brief An opaque handle to an OpenGL context.
* An opaque handle to an OpenGL context.
*/
typedef void *SDL_GLContext;
/**
* \brief Opaque EGL types.
* Opaque EGL types.
*/
typedef void *SDL_EGLDisplay;
typedef void *SDL_EGLConfig;
@ -198,13 +208,13 @@ typedef intptr_t SDL_EGLAttrib;
typedef int SDL_EGLint;
/**
* \brief EGL attribute initialization callback types.
* EGL attribute initialization callback types.
*/
typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void);
typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void);
/**
* \brief OpenGL configuration attributes
* OpenGL configuration attributes
*/
typedef enum
{
@ -340,6 +350,20 @@ extern DECLSPEC SDL_DisplayID *SDLCALL SDL_GetDisplays(int *count);
*/
extern DECLSPEC SDL_DisplayID SDLCALL SDL_GetPrimaryDisplay(void);
/**
* Get the properties associated with a display.
*
* \param displayID the instance ID of the display to query
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_DisplayID displayID);
/**
* Get the name of a display in UTF-8 encoding.
*
@ -618,6 +642,16 @@ extern DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window);
* change the window size when the window is not fullscreen, use
* SDL_SetWindowSize().
*
* If the window is currently in the fullscreen state, this request is
* asynchronous on some windowing systems and the new mode dimensions may not
* be applied immediately upon the return of this function. If an immediate
* change is required, call SDL_SyncWindow() to block until the changes have
* taken effect.
*
* When the new mode takes effect, an SDL_EVENT_WINDOW_RESIZED and/or an
* SDL_EVENT_WINDOOW_PIXEL_SIZE_CHANGED event will be emitted with the new
* mode dimensions.
*
* \param window the window to affect
* \param mode a pointer to the display mode to use, which can be NULL for
* desktop mode, or one of the fullscreen modes returned by
@ -629,6 +663,7 @@ extern DECLSPEC float SDLCALL SDL_GetWindowDisplayScale(SDL_Window *window);
*
* \sa SDL_GetWindowFullscreenMode
* \sa SDL_SetWindowFullscreen
* \sa SDL_SyncWindow
*/
extern DECLSPEC int SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window, const SDL_DisplayMode *mode);
@ -700,11 +735,6 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window);
* window is created and should be queried again if you get an
* SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event.
*
* If the window is set fullscreen, the width and height parameters `w` and
* `h` will not be used. However, invalid size parameters (e.g. too large) may
* still fail. Window size is actually limited to 16384 x 16384 for all
* platforms at window creation.
*
* If the window is created with any of the SDL_WINDOW_OPENGL or
* SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function
* (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the
@ -730,79 +760,11 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowPixelFormat(SDL_Window *window);
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreatePopupWindow
* \sa SDL_CreateWindowFrom
* \sa SDL_CreateWindowWithPosition
* \sa SDL_CreateWindowWithProperties
* \sa SDL_DestroyWindow
*/
extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindow(const char *title, int w, int h, Uint32 flags);
/**
* Create a window with the specified position, dimensions, and flags.
*
* `flags` may be any of the following OR'd together:
*
* - `SDL_WINDOW_FULLSCREEN`: fullscreen window at desktop resolution
* - `SDL_WINDOW_OPENGL`: window usable with an OpenGL context
* - `SDL_WINDOW_VULKAN`: window usable with a Vulkan instance
* - `SDL_WINDOW_METAL`: window usable with a Metal instance
* - `SDL_WINDOW_HIDDEN`: window is not visible
* - `SDL_WINDOW_BORDERLESS`: no window decoration
* - `SDL_WINDOW_RESIZABLE`: window can be resized
* - `SDL_WINDOW_MINIMIZED`: window is minimized
* - `SDL_WINDOW_MAXIMIZED`: window is maximized
* - `SDL_WINDOW_MOUSE_GRABBED`: window has grabbed mouse focus
*
* The SDL_Window is implicitly shown if SDL_WINDOW_HIDDEN is not set.
*
* On Apple's macOS, you **must** set the NSHighResolutionCapable Info.plist
* property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
*
* The window pixel size may differ from its window coordinate size if the
* window is on a high pixel density display. Use SDL_GetWindowSize() to query
* the client area's size in window coordinates, and
* SDL_GetWindowSizeInPixels() or SDL_GetRenderOutputSize() to query the
* drawable size in pixels. Note that the drawable size can vary after the
* window is created and should be queried again if you get an
* SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED event.
*
* If the window is set fullscreen, the width and height parameters `w` and
* `h` will not be used. However, invalid size parameters (e.g. too large) may
* still fail. Window size is actually limited to 16384 x 16384 for all
* platforms at window creation.
*
* If the window is created with any of the SDL_WINDOW_OPENGL or
* SDL_WINDOW_VULKAN flags, then the corresponding LoadLibrary function
* (SDL_GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the
* corresponding UnloadLibrary function is called by SDL_DestroyWindow().
*
* If SDL_WINDOW_VULKAN is specified and there isn't a working Vulkan driver,
* SDL_CreateWindow() will fail because SDL_Vulkan_LoadLibrary() will fail.
*
* If SDL_WINDOW_METAL is specified on an OS that does not support Metal,
* SDL_CreateWindow() will fail.
*
* On non-Apple devices, SDL requires you to either not link to the Vulkan
* loader or link to a dynamic library version. This limitation may be removed
* in a future version of SDL.
*
* \param title the title of the window, in UTF-8 encoding
* \param x the x position of the window, or `SDL_WINDOWPOS_CENTERED`
* \param y the y position of the window, or `SDL_WINDOWPOS_CENTERED`
* \param w the width of the window
* \param h the height of the window
* \param flags 0, or one or more SDL_WindowFlags OR'd together
* \returns the window that was created or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreatePopupWindow
* \sa SDL_CreateWindow
* \sa SDL_CreateWindowFrom
* \sa SDL_DestroyWindow
*/
extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindowWithPosition(const char *title, int x, int y, int w, int h, Uint32 flags);
/**
* Create a child popup window of the specified parent window.
*
@ -812,9 +774,12 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindowWithPosition(const char *tit
* The topmost popup menu will implicitly gain the keyboard focus.
*
* The following flags are not relevant to popup window creation and will be
* ignored: - 'SDL_WINDOW_MINIMIZED' - 'SDL_WINDOW_MAXIMIZED' -
* 'SDL_WINDOW_FULLSCREEN' - 'SDL_WINDOW_BORDERLESS' -
* 'SDL_WINDOW_SKIP_TASKBAR'
* ignored:
*
* - 'SDL_WINDOW_MINIMIZED'
* - 'SDL_WINDOW_MAXIMIZED'
* - 'SDL_WINDOW_FULLSCREEN'
* - 'SDL_WINDOW_BORDERLESS'
*
* The parent parameter **must** be non-null and a valid window. The parent of
* a popup window can be either a regular, toplevel window, or another popup
@ -849,20 +814,105 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindowWithPosition(const char *tit
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateWindow
* \sa SDL_CreateWindowWithProperties
* \sa SDL_DestroyWindow
* \sa SDL_GetWindowParent
*/
extern DECLSPEC SDL_Window *SDLCALL SDL_CreatePopupWindow(SDL_Window *parent, int offset_x, int offset_y, int w, int h, Uint32 flags);
/**
* Create an SDL window from an existing native window.
* Create a window with the specified properties.
*
* In some cases (e.g. OpenGL) and on some platforms (e.g. Microsoft Windows)
* the hint `SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT` needs to be configured
* before using SDL_CreateWindowFrom().
* These are the supported properties:
*
* \param data a pointer to driver-dependent window creation data, typically
* your native window cast to a void*
* - `SDL_PROPERTY_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN`: true if the window
* should be always on top
* - `SDL_PROPERTY_WINDOW_CREATE_BORDERLESS_BOOLEAN`: true if the window has
* no window decoration
* - `SDL_PROPERTY_WINDOW_CREATE_FOCUSABLE_BOOLEAN`: true if the window should
* accept keyboard input (defaults true)
* - `SDL_PROPERTY_WINDOW_CREATE_FULLSCREEN_BOOLEAN`: true if the window
* should start in fullscreen mode at desktop resolution
* - `SDL_PROPERTY_WINDOW_CREATE_HEIGHT_NUMBER`: the height of the window
* - `SDL_PROPERTY_WINDOW_CREATE_HIDDEN_BOOLEAN`: true if the window should
* start hidden
* - `SDL_PROPERTY_WINDOW_CREATE_HIGH_PIXEL_DENSITY_BOOLEAN`: true if the
* window uses a high pixel density buffer if possible
* - `SDL_PROPERTY_WINDOW_CREATE_MAXIMIZED_BOOLEAN`: true if the window should
* start maximized
* - `SDL_PROPERTY_WINDOW_CREATE_MENU_BOOLEAN`: true if the window is a popup
* menu
* - `SDL_PROPERTY_WINDOW_CREATE_METAL_BOOLEAN`: true if the window will be
* used with Metal rendering
* - `SDL_PROPERTY_WINDOW_CREATE_MINIMIZED_BOOLEAN`: true if the window should
* start minimized
* - `SDL_PROPERTY_WINDOW_CREATE_MOUSE_GRABBED_BOOLEAN`: true if the window
* starts with grabbed mouse focus
* - `SDL_PROPERTY_WINDOW_CREATE_OPENGL_BOOLEAN`: true if the window will be
* used with OpenGL rendering
* - `SDL_PROPERTY_WINDOW_CREATE_PARENT_POINTER`: an SDL_Window that will be
* the parent of this window, required for windows with the "toolip" and
* "menu" properties
* - `SDL_PROPERTY_WINDOW_CREATE_RESIZABLE_BOOLEAN`: true if the window should
* be resizable
* - `SDL_PROPERTY_WINDOW_CREATE_TITLE_STRING`: the title of the window, in
* UTF-8 encoding
* - `SDL_PROPERTY_WINDOW_CREATE_TRANSPARENT_BOOLEAN`: true if the window show
* transparent in the areas with alpha of 0
* - `SDL_PROPERTY_WINDOW_CREATE_TOOLTIP_BOOLEAN`: true if the window is a
* tooltip
* - `SDL_PROPERTY_WINDOW_CREATE_UTILITY_BOOLEAN`: true if the window is a
* utility window, not showing in the task bar and window list
* - `SDL_PROPERTY_WINDOW_CREATE_VULKAN_BOOLEAN`: true if the window will be
* used with Vulkan rendering
* - `SDL_PROPERTY_WINDOW_CREATE_WIDTH_NUMBER`: the width of the window
* - `SDL_PROPERTY_WINDOW_CREATE_X_NUMBER`: the x position of the window, or
* `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is
* relative to the parent for windows with the "parent" property set.
* - `SDL_PROPERTY_WINDOW_CREATE_Y_NUMBER`: the y position of the window, or
* `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is
* relative to the parent for windows with the "parent" property set.
*
* These are additional supported properties on macOS:
*
* - `SDL_PROPERTY_WINDOW_CREATE_COCOA_WINDOW_POINTER`: the
* `(__unsafe_unretained)` NSWindow associated with the window, if you want
* to wrap an existing window.
* - `SDL_PROPERTY_WINDOW_CREATE_COCOA_VIEW_POINTER`: the
* `(__unsafe_unretained)` NSView associated with the window, defaults to
* `[window contentView]`
*
* These are additional supported properties on Wayland:
*
* - `SDL_PROPERTY_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN` - true
* if the application wants to use the Wayland surface for a custom role and
* does not want it attached to an XDG toplevel window. See
* docs/README-wayland.md for more information on using custom surfaces.
* - `SDL_PROPERTY_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN - true if
* the application wants an associated `wl_egl_window` object to be created,
* even if the window does not have the OpenGL property or flag set.
* - `SDL_PROPERTY_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER` - the wl_surface
* associated with the window, if you want to wrap an existing window. See
* docs/README-wayland.md for more information.
*
* These are additional supported properties on Windows:
*
* - `SDL_PROPERTY_WINDOW_CREATE_WIN32_HWND_POINTER`: the HWND associated with
* the window, if you want to wrap an existing window.
* - `SDL_PROPERTY_WINDOW_CREATE_WIN32_PIXEL_FORMAT_HWND_POINTER`: optional,
* another window to share pixel format with, useful for OpenGL windows
*
* These are additional supported properties with X11:
*
* - `SDL_PROPERTY_WINDOW_CREATE_X11_WINDOW_NUMBER`: the X11 Window associated
* with the window, if you want to wrap an existing window.
*
* The window is implicitly shown if the "hidden" property is not set.
*
* Windows with the "tooltip" and "menu" properties are popup windows and have
* the behaviors and guidelines outlined in `SDL_CreatePopupWindow()`.
*
* \param props the properties to use
* \returns the window that was created or NULL on failure; call
* SDL_GetError() for more information.
*
@ -871,7 +921,39 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreatePopupWindow(SDL_Window *parent, in
* \sa SDL_CreateWindow
* \sa SDL_DestroyWindow
*/
extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindowFrom(const void *data);
extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindowWithProperties(SDL_PropertiesID props);
#define SDL_PROPERTY_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN "always-on-top"
#define SDL_PROPERTY_WINDOW_CREATE_BORDERLESS_BOOLEAN "borderless"
#define SDL_PROPERTY_WINDOW_CREATE_FOCUSABLE_BOOLEAN "focusable"
#define SDL_PROPERTY_WINDOW_CREATE_FULLSCREEN_BOOLEAN "fullscreen"
#define SDL_PROPERTY_WINDOW_CREATE_HEIGHT_NUMBER "height"
#define SDL_PROPERTY_WINDOW_CREATE_HIDDEN_BOOLEAN "hidden"
#define SDL_PROPERTY_WINDOW_CREATE_HIGH_PIXEL_DENSITY_BOOLEAN "high-pixel-density"
#define SDL_PROPERTY_WINDOW_CREATE_MAXIMIZED_BOOLEAN "maximized"
#define SDL_PROPERTY_WINDOW_CREATE_MENU_BOOLEAN "menu"
#define SDL_PROPERTY_WINDOW_CREATE_METAL_BOOLEAN "metal"
#define SDL_PROPERTY_WINDOW_CREATE_MINIMIZED_BOOLEAN "minimized"
#define SDL_PROPERTY_WINDOW_CREATE_MOUSE_GRABBED_BOOLEAN "mouse-grabbed"
#define SDL_PROPERTY_WINDOW_CREATE_OPENGL_BOOLEAN "opengl"
#define SDL_PROPERTY_WINDOW_CREATE_PARENT_POINTER "parent"
#define SDL_PROPERTY_WINDOW_CREATE_RESIZABLE_BOOLEAN "resizable"
#define SDL_PROPERTY_WINDOW_CREATE_TITLE_STRING "title"
#define SDL_PROPERTY_WINDOW_CREATE_TRANSPARENT_BOOLEAN "transparent"
#define SDL_PROPERTY_WINDOW_CREATE_TOOLTIP_BOOLEAN "tooltip"
#define SDL_PROPERTY_WINDOW_CREATE_UTILITY_BOOLEAN "utility"
#define SDL_PROPERTY_WINDOW_CREATE_VULKAN_BOOLEAN "vulkan"
#define SDL_PROPERTY_WINDOW_CREATE_WIDTH_NUMBER "width"
#define SDL_PROPERTY_WINDOW_CREATE_X_NUMBER "x"
#define SDL_PROPERTY_WINDOW_CREATE_Y_NUMBER "y"
#define SDL_PROPERTY_WINDOW_CREATE_COCOA_WINDOW_POINTER "cocoa.window"
#define SDL_PROPERTY_WINDOW_CREATE_COCOA_VIEW_POINTER "cocoa.view"
#define SDL_PROPERTY_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN "wayland.surface_role_custom"
#define SDL_PROPERTY_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN "wayland.create_egl_window"
#define SDL_PROPERTY_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER "wayland.wl_surface"
#define SDL_PROPERTY_WINDOW_CREATE_WIN32_HWND_POINTER "win32.hwnd"
#define SDL_PROPERTY_WINDOW_CREATE_WIN32_PIXEL_FORMAT_HWND_POINTER "win32.pixel_format_hwnd"
#define SDL_PROPERTY_WINDOW_CREATE_X11_WINDOW_NUMBER "x11.window"
/**
* Get the numeric ID of a window.
@ -918,6 +1000,132 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowFromID(SDL_WindowID id);
*/
extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
/**
* Get the properties associated with a window.
*
* The following read-only properties are provided by SDL:
*
* On Android:
*
* - `SDL_PROPERTY_WINDOW_ANDROID_WINDOW_POINTER`: the ANativeWindow
* associated with the window
* - `SDL_PROPERTY_WINDOW_ANDROID_SURFACE_POINTER`: the EGLSurface associated
* with the window
*
* On iOS:
*
* - `SDL_PROPERTY_WINDOW_UIKIT_WINDOW_POINTER`: the `(__unsafe_unretained)`
* UIWindow associated with the window
* - `SDL_PROPERTY_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER`: the NSInteger tag
* assocated with metal views on the window
*
* On KMS/DRM:
*
* - `SDL_PROPERTY_WINDOW_KMSDRM_DEVICE_INDEX_NUMBER`: the device index
* associated with the window (e.g. the X in /dev/dri/cardX)
* - `SDL_PROPERTY_WINDOW_KMSDRM_DRM_FD_NUMBER`: the DRM FD associated with
* the window
* - `SDL_PROPERTY_WINDOW_KMSDRM_GBM_DEVICE_POINTER`: the GBM device
* associated with the window
*
* On macOS:
*
* - `SDL_PROPERTY_WINDOW_COCOA_WINDOW_POINTER`: the `(__unsafe_unretained)`
* NSWindow associated with the window
* - `SDL_PROPERTY_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER`: the NSInteger tag
* assocated with metal views on the window
*
* On Vivante:
*
* - `SDL_PROPERTY_WINDOW_VIVANTE_DISPLAY_POINTER`: the EGLNativeDisplayType
* associated with the window
* - `SDL_PROPERTY_WINDOW_VIVANTE_WINDOW_POINTER`: the EGLNativeWindowType
* associated with the window
* - `SDL_PROPERTY_WINDOW_VIVANTE_SURFACE_POINTER`: the EGLSurface associated
* with the window
*
* On UWP:
*
* - `SDL_PROPERTY_WINDOW_WINRT_WINDOW_POINTER`: the IInspectable CoreWindow
* associated with the window
*
* On Windows:
*
* - `SDL_PROPERTY_WINDOW_WIN32_HWND_POINTER`: the HWND associated with the
* window
* - `SDL_PROPERTY_WINDOW_WIN32_HDC_POINTER`: the HDC associated with the
* window
* - `SDL_PROPERTY_WINDOW_WIN32_INSTANCE_POINTER`: the HINSTANCE associated
* with the window
*
* On Wayland:
*
* Note: The `xdg_*` window objects do not internally persist across window
* show/hide calls. They will be null if the window is hidden and must be
* queried each time it is shown.
*
* - `SDL_PROPERTY_WINDOW_WAYLAND_DISPLAY_POINTER`: the wl_display associated
* with the window
* - `SDL_PROPERTY_WINDOW_WAYLAND_SURFACE_POINTER`: the wl_surface associated
* with the window
* - `SDL_PROPERTY_WINDOW_WAYLAND_EGL_WINDOW_POINTER`: the wl_egl_window
* associated with the window
* - `SDL_PROPERTY_WINDOW_WAYLAND_XDG_SURFACE_POINTER`: the xdg_surface
* associated with the window
* - `SDL_PROPERTY_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER`: the xdg_toplevel role
* associated with the window
* - `SDL_PROPERTY_WINDOW_WAYLAND_XDG_POPUP_POINTER`: the xdg_popup role
* associated with the window
* - `SDL_PROPERTY_WINDOW_WAYLAND_XDG_POSITIONER_POINTER`: the xdg_positioner
* associated with the window, in popup mode
*
* On X11:
*
* - `SDL_PROPERTY_WINDOW_X11_DISPLAY_POINTER`: the X11 Display associated
* with the window
* - `SDL_PROPERTY_WINDOW_X11_SCREEN_NUMBER`: the screen number associated
* with the window
* - `SDL_PROPERTY_WINDOW_X11_WINDOW_NUMBER`: the X11 Window associated with
* the window
*
* \param window the window to query
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetProperty
* \sa SDL_SetProperty
*/
extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetWindowProperties(SDL_Window *window);
#define SDL_PROPERTY_WINDOW_ANDROID_WINDOW_POINTER "SDL.window.android.window"
#define SDL_PROPERTY_WINDOW_ANDROID_SURFACE_POINTER "SDL.window.android.surface"
#define SDL_PROPERTY_WINDOW_UIKIT_WINDOW_POINTER "SDL.window.uikit.window"
#define SDL_PROPERTY_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER "SDL.window.uikit.metal_view_tag"
#define SDL_PROPERTY_WINDOW_KMSDRM_DEVICE_INDEX_NUMBER "SDL.window.kmsdrm.dev_index"
#define SDL_PROPERTY_WINDOW_KMSDRM_DRM_FD_NUMBER "SDL.window.kmsdrm.drm_fd"
#define SDL_PROPERTY_WINDOW_KMSDRM_GBM_DEVICE_POINTER "SDL.window.kmsdrm.gbm_dev"
#define SDL_PROPERTY_WINDOW_COCOA_WINDOW_POINTER "SDL.window.cocoa.window"
#define SDL_PROPERTY_WINDOW_COCOA_METAL_VIEW_TAG_NUMBER "SDL.window.cocoa.metal_view_tag"
#define SDL_PROPERTY_WINDOW_VIVANTE_DISPLAY_POINTER "SDL.window.vivante.display"
#define SDL_PROPERTY_WINDOW_VIVANTE_WINDOW_POINTER "SDL.window.vivante.window"
#define SDL_PROPERTY_WINDOW_VIVANTE_SURFACE_POINTER "SDL.window.vivante.surface"
#define SDL_PROPERTY_WINDOW_WINRT_WINDOW_POINTER "SDL.window.winrt.window"
#define SDL_PROPERTY_WINDOW_WIN32_HWND_POINTER "SDL.window.win32.hwnd"
#define SDL_PROPERTY_WINDOW_WIN32_HDC_POINTER "SDL.window.win32.hdc"
#define SDL_PROPERTY_WINDOW_WIN32_INSTANCE_POINTER "SDL.window.win32.instance"
#define SDL_PROPERTY_WINDOW_WAYLAND_DISPLAY_POINTER "SDL.window.wayland.display"
#define SDL_PROPERTY_WINDOW_WAYLAND_SURFACE_POINTER "SDL.window.wayland.surface"
#define SDL_PROPERTY_WINDOW_WAYLAND_EGL_WINDOW_POINTER "SDL.window.wayland.egl_window"
#define SDL_PROPERTY_WINDOW_WAYLAND_XDG_SURFACE_POINTER "SDL.window.wayland.xdg_surface"
#define SDL_PROPERTY_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER "SDL.window.wayland.xdg_toplevel"
#define SDL_PROPERTY_WINDOW_WAYLAND_XDG_POPUP_POINTER "SDL.window.wayland.xdg_popup"
#define SDL_PROPERTY_WINDOW_WAYLAND_XDG_POSITIONER_POINTER "SDL.window.wayland.xdg_positioner"
#define SDL_PROPERTY_WINDOW_X11_DISPLAY_POINTER "SDL.window.x11.display"
#define SDL_PROPERTY_WINDOW_X11_SCREEN_NUMBER "SDL.window.x11.screen"
#define SDL_PROPERTY_WINDOW_X11_WINDOW_NUMBER "SDL.window.x11.window"
/**
* Get the window flags.
*
@ -978,36 +1186,29 @@ extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_Window *window);
extern DECLSPEC int SDLCALL SDL_SetWindowIcon(SDL_Window *window, SDL_Surface *icon);
/**
* Associate an arbitrary named pointer with a window.
* Request that the window's position be set.
*
* `name` is case-sensitive.
* If, at the time of this request, the window is in a fixed-size state such
* as maximized, this request may be deferred until the window returns to a
* resizable state.
*
* \param window the window to associate with the pointer
* \param name the name of the pointer
* \param userdata the associated pointer
* \returns the previous value associated with `name`.
* This can be used to reposition fullscreen-desktop windows onto a different
* display, however, exclusive fullscreen windows are locked to a specific
* display and can only be repositioned programmatically via
* SDL_SetWindowFullscreenMode().
*
* \since This function is available since SDL 3.0.0.
* On some windowing systems this request is asynchronous and the new
* coordinates may not have have been applied immediately upon the return of
* this function. If an immediate change is required, call SDL_SyncWindow() to
* block until the changes have taken effect.
*
* \sa SDL_GetWindowData
*/
extern DECLSPEC void *SDLCALL SDL_SetWindowData(SDL_Window *window, const char *name, void *userdata);
/**
* Retrieve the data pointer associated with a window.
*
* \param window the window to query
* \param name the name of the pointer
* \returns the value associated with `name`.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_SetWindowData
*/
extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window *window, const char *name);
/**
* Set the position of a window.
* When the window position changes, an SDL_EVENT_WINDOW_MOVED event will be
* emitted with the window's new coordinates. Note that the new coordinates
* may not match the exact coordinates requested, as some windowing systems
* can restrict the position of the window in certain scenarios (e.g.
* constraining the position so the window is always within desktop bounds).
* Additionally, as this is just a request, it can be denied by the windowing
* system.
*
* \param window the window to reposition
* \param x the x coordinate of the window, or `SDL_WINDOWPOS_CENTERED` or
@ -1020,12 +1221,16 @@ extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window *window, const char *
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetWindowPosition
* \sa SDL_SyncWindow
*/
extern DECLSPEC int SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int y);
/**
* Get the position of a window.
*
* This is the current position of the window as last reported by the
* windowing system.
*
* If you do not need the value for one of the positions a NULL may be passed
* in the `x` or `y` parameter.
*
@ -1042,10 +1247,29 @@ extern DECLSPEC int SDLCALL SDL_SetWindowPosition(SDL_Window *window, int x, int
extern DECLSPEC int SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, int *y);
/**
* Set the size of a window's client area.
* Request that the size of a window's client area be set.
*
* This only affects the size of the window when not in fullscreen mode. To
* change the fullscreen mode of a window, use SDL_SetWindowFullscreenMode()
* NULL can safely be passed as the `w` or `h` parameter if the width or
* height value is not desired.
*
* If, at the time of this request, the window in a fixed-size state, such as
* maximized or fullscreen, the request will be deferred until the window
* exits this state and becomes resizable again.
*
* To change the fullscreen mode of a window, use
* SDL_SetWindowFullscreenMode()
*
* On some windowing systems, this request is asynchronous and the new window
* size may not have have been applied immediately upon the return of this
* function. If an immediate change is required, call SDL_SyncWindow() to
* block until the changes have taken effect.
*
* When the window size changes, an SDL_EVENT_WINDOW_RESIZED event will be
* emitted with the new window dimensions. Note that the new dimensions may
* not match the exact size requested, as some windowing systems can restrict
* the window size in certain scenarios (e.g. constraining the size of the
* content area to remain within the usable desktop bounds). Additionally, as
* this is just a request, it can be denied by the windowing system.
*
* \param window the window to change
* \param w the width of the window, must be > 0
@ -1057,6 +1281,7 @@ extern DECLSPEC int SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, in
*
* \sa SDL_GetWindowSize
* \sa SDL_SetWindowFullscreenMode
* \sa SDL_SyncWindow
*/
extern DECLSPEC int SDLCALL SDL_SetWindowSize(SDL_Window *window, int w, int h);
@ -1300,7 +1525,24 @@ extern DECLSPEC int SDLCALL SDL_HideWindow(SDL_Window *window);
extern DECLSPEC int SDLCALL SDL_RaiseWindow(SDL_Window *window);
/**
* Make a window as large as possible.
* Request that the window be made as large as possible.
*
* Non-resizable windows can't be maximized. The window must have the
* SDL_WINDOW_RESIZABLE flag set, or this will have no effect.
*
* On some windowing systems this request is asynchronous and the new window
* state may not have have been applied immediately upon the return of this
* function. If an immediate change is required, call SDL_SyncWindow() to
* block until the changes have taken effect.
*
* When the window state changes, an SDL_EVENT_WINDOW_MAXIMIZED event will be
* emitted. Note that, as this is just a request, the windowing system can
* deny the state change.
*
* When maximizing a window, whether the constraints set via
* SDL_SetWindowMaximumSize() are honored depends on the policy of the window
* manager. Win32 and macOS enforce the constraints when maximizing, while X11
* and Wayland window managers may vary.
*
* \param window the window to maximize
* \returns 0 on success or a negative error code on failure; call
@ -1310,11 +1552,21 @@ extern DECLSPEC int SDLCALL SDL_RaiseWindow(SDL_Window *window);
*
* \sa SDL_MinimizeWindow
* \sa SDL_RestoreWindow
* \sa SDL_SyncWindow
*/
extern DECLSPEC int SDLCALL SDL_MaximizeWindow(SDL_Window *window);
/**
* Minimize a window to an iconic representation.
* Request that the window be minimized to an iconic representation.
*
* On some windowing systems this request is asynchronous and the new window
* state may not have have been applied immediately upon the return of this
* function. If an immediate change is required, call SDL_SyncWindow() to
* block until the changes have taken effect.
*
* When the window state changes, an SDL_EVENT_WINDOW_MINIMIZED event will be
* emitted. Note that, as this is just a request, the windowing system can
* deny the state change.
*
* \param window the window to minimize
* \returns 0 on success or a negative error code on failure; call
@ -1324,11 +1576,22 @@ extern DECLSPEC int SDLCALL SDL_MaximizeWindow(SDL_Window *window);
*
* \sa SDL_MaximizeWindow
* \sa SDL_RestoreWindow
* \sa SDL_SyncWindow
*/
extern DECLSPEC int SDLCALL SDL_MinimizeWindow(SDL_Window *window);
/**
* Restore the size and position of a minimized or maximized window.
* Request that the size and position of a minimized or maximized window be
* restored.
*
* On some windowing systems this request is asynchronous and the new window
* state may not have have been applied immediately upon the return of this
* function. If an immediate change is required, call SDL_SyncWindow() to
* block until the changes have taken effect.
*
* When the window state changes, an SDL_EVENT_WINDOW_RESTORED event will be
* emitted. Note that, as this is just a request, the windowing system can
* deny the state change.
*
* \param window the window to restore
* \returns 0 on success or a negative error code on failure; call
@ -1338,15 +1601,25 @@ extern DECLSPEC int SDLCALL SDL_MinimizeWindow(SDL_Window *window);
*
* \sa SDL_MaximizeWindow
* \sa SDL_MinimizeWindow
* \sa SDL_SyncWindow
*/
extern DECLSPEC int SDLCALL SDL_RestoreWindow(SDL_Window *window);
/**
* Set a window's fullscreen state.
* Request that the window's fullscreen state be changed.
*
* By default a window in fullscreen state uses fullscreen desktop mode, but a
* specific display mode can be set using SDL_SetWindowFullscreenMode().
*
* On some windowing systems this request is asynchronous and the new
* fullscreen state may not have have been applied immediately upon the return
* of this function. If an immediate change is required, call SDL_SyncWindow()
* to block until the changes have taken effect.
*
* When the window state changes, an SDL_EVENT_WINDOW_ENTER_FULLSCREEN or
* SDL_EVENT_WINDOW_LEAVE_FULLSCREEN event will be emitted. Note that, as this
* is just a request, it can be denied by the windowing system.
*
* \param window the window to change
* \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed mode
* \returns 0 on success or a negative error code on failure; call
@ -1356,9 +1629,39 @@ extern DECLSPEC int SDLCALL SDL_RestoreWindow(SDL_Window *window);
*
* \sa SDL_GetWindowFullscreenMode
* \sa SDL_SetWindowFullscreenMode
* \sa SDL_SyncWindow
*/
extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_Window *window, SDL_bool fullscreen);
/**
* Block until any pending window state is finalized.
*
* On asynchronous windowing systems, this acts as a synchronization barrier
* for pending window state. It will attempt to wait until any pending window
* state has been applied and is guaranteed to return within finite time. Note
* that for how long it can potentially block depends on the underlying window
* system, as window state changes may involve somewhat lengthy animations
* that must complete before the window is in its final requested state.
*
* On windowing systems where changes are immediate, this does nothing.
*
* \param window the window for which to wait for the pending state to be
* applied
* \returns 0 on success, a positive value if the operation timed out before
* the window was in the requested state, or a negative error code on
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_SetWindowSize
* \sa SDL_SetWindowPosition
* \sa SDL_SetWindowFullscreen
* \sa SDL_MinimizeWindow
* \sa SDL_MaximizeWindow
* \sa SDL_RestoreWindow
*/
extern DECLSPEC int SDLCALL SDL_SyncWindow(SDL_Window *window);
/**
* Return whether the window has a surface associated with it.
*
@ -1426,6 +1729,11 @@ extern DECLSPEC int SDLCALL SDL_UpdateWindowSurface(SDL_Window *window);
*
* This function is equivalent to the SDL 1.2 API SDL_UpdateRects().
*
* Note that this function will update _at least_ the rectangles specified,
* but this is only intended as an optimization; in practice, this might
* update more of the screen (or all of the screen!), depending on what method
* SDL uses to send pixels to the system.
*
* \param window the window to update
* \param rects an array of SDL_Rect structures representing areas of the
* surface to copy, in pixels
@ -1811,8 +2119,9 @@ extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOperati
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreatePopupWindow
* \sa SDL_CreateWindow
* \sa SDL_CreateWindowFrom
* \sa SDL_CreateWindowWithProperties
*/
extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_Window *window);

377
include/SDL3/SDL_video_capture.h Normal file
View File

@ -0,0 +1,377 @@
/*
Simple DirectMedia Layer
Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
*/
/**
* \file SDL_video_capture.h
*
* Video Capture for the SDL library.
*/
#ifndef SDL_video_capture_h_
#define SDL_video_capture_h_
#include "SDL3/SDL_video.h"
#include <SDL3/SDL_begin_code.h>
/* Set up for C function definitions, even when using C++ */
#ifdef __cplusplus
extern "C" {
#endif
/**
* This is a unique ID for a video capture device for the time it is connected to the system,
* and is never reused for the lifetime of the application. If the device is
* disconnected and reconnected, it will get a new ID.
*
* The ID value starts at 1 and increments from there. The value 0 is an invalid ID.
*
* \sa SDL_GetVideoCaptureDevices
*/
typedef Uint32 SDL_VideoCaptureDeviceID;
/**
* The structure used to identify an SDL video capture device
*/
struct SDL_VideoCaptureDevice;
typedef struct SDL_VideoCaptureDevice SDL_VideoCaptureDevice;
#define SDL_VIDEO_CAPTURE_ALLOW_ANY_CHANGE 1
/**
* SDL_VideoCaptureSpec structure
*
* Only those field can be 'desired' when configuring the device:
* - format
* - width
* - height
*
* \sa SDL_GetVideoCaptureFormat
* \sa SDL_GetVideoCaptureFrameSize
*
*/
typedef struct SDL_VideoCaptureSpec
{
Uint32 format; /**< Frame SDL_PixelFormatEnum format */
int width; /**< Frame width */
int height; /**< Frame height */
} SDL_VideoCaptureSpec;
/**
* SDL Video Capture Status
*
* Change states but calling the function in this order:
*
* SDL_OpenVideoCapture()
* SDL_SetVideoCaptureSpec() -> Init
* SDL_StartVideoCapture() -> Playing
* SDL_StopVideoCapture() -> Stopped
* SDL_CloseVideoCapture()
*
*/
typedef enum
{
SDL_VIDEO_CAPTURE_FAIL = -1, /**< Failed */
SDL_VIDEO_CAPTURE_INIT = 0, /**< Init, spec hasn't been set */
SDL_VIDEO_CAPTURE_STOPPED, /**< Stopped */
SDL_VIDEO_CAPTURE_PLAYING /**< Playing */
} SDL_VideoCaptureStatus;
/**
* SDL Video Capture Status
*/
typedef struct SDL_VideoCaptureFrame
{
Uint64 timestampNS; /**< Frame timestamp in nanoseconds when read from the driver */
int num_planes; /**< Number of planes */
Uint8 *data[3]; /**< Pointer to data of i-th plane */
int pitch[3]; /**< Pitch of i-th plane */
void *internal; /**< Private field */
} SDL_VideoCaptureFrame;
/**
* Get a list of currently connected video capture devices.
*
* \param count a pointer filled in with the number of video capture devices
* \returns a 0 terminated array of video capture instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_OpenVideoCapture
*/
extern DECLSPEC SDL_VideoCaptureDeviceID *SDLCALL SDL_GetVideoCaptureDevices(int *count);
/**
* Open a Video Capture device
*
* \param instance_id the video capture device instance ID
* \returns device, or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetVideoCaptureDeviceName
* \sa SDL_GetVideoCaptureDevices
* \sa SDL_OpenVideoCaptureWithSpec
*/
extern DECLSPEC SDL_VideoCaptureDevice *SDLCALL SDL_OpenVideoCapture(SDL_VideoCaptureDeviceID instance_id);
/**
* Set specification
*
* \param device opened video capture device
* \param desired desired video capture spec
* \param obtained obtained video capture spec
* \param allowed_changes allow changes or not
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_OpenVideoCapture
* \sa SDL_OpenVideoCaptureWithSpec
* \sa SDL_GetVideoCaptureSpec
*/
extern DECLSPEC int SDLCALL SDL_SetVideoCaptureSpec(SDL_VideoCaptureDevice *device,
const SDL_VideoCaptureSpec *desired,
SDL_VideoCaptureSpec *obtained,
int allowed_changes);
/**
* Open a Video Capture device and set specification
*
* \param instance_id the video capture device instance ID
* \param desired desired video capture spec
* \param obtained obtained video capture spec
* \param allowed_changes allow changes or not
* \returns device, or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_OpenVideoCapture
* \sa SDL_SetVideoCaptureSpec
* \sa SDL_GetVideoCaptureSpec
*/
extern DECLSPEC SDL_VideoCaptureDevice *SDLCALL SDL_OpenVideoCaptureWithSpec(SDL_VideoCaptureDeviceID instance_id,
const SDL_VideoCaptureSpec *desired,
SDL_VideoCaptureSpec *obtained,
int allowed_changes);
/**
* Get device name
*
* \param instance_id the video capture device instance ID
* \returns device name, shouldn't be freed
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetVideoCaptureDevices
*/
extern DECLSPEC const char * SDLCALL SDL_GetVideoCaptureDeviceName(SDL_VideoCaptureDeviceID instance_id);
/**
* Get the obtained video capture spec
*
* \param device opened video capture device
* \param spec The SDL_VideoCaptureSpec to be initialized by this function.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_SetVideoCaptureSpec
* \sa SDL_OpenVideoCaptureWithSpec
*/
extern DECLSPEC int SDLCALL SDL_GetVideoCaptureSpec(SDL_VideoCaptureDevice *device, SDL_VideoCaptureSpec *spec);
/**
* Get frame format of video capture device.
*
* The value can be used to fill SDL_VideoCaptureSpec structure.
*
* \param device opened video capture device
* \param index format between 0 and num -1
* \param format pointer output format (SDL_PixelFormatEnum)
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetNumVideoCaptureFormats
*/
extern DECLSPEC int SDLCALL SDL_GetVideoCaptureFormat(SDL_VideoCaptureDevice *device,
int index,
Uint32 *format);
/**
* Number of available formats for the device
*
* \param device opened video capture device
* \returns number of formats or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetVideoCaptureFormat
* \sa SDL_SetVideoCaptureSpec
*/
extern DECLSPEC int SDLCALL SDL_GetNumVideoCaptureFormats(SDL_VideoCaptureDevice *device);
/**
* Get frame sizes of the device and the specified input format.
*
* The value can be used to fill SDL_VideoCaptureSpec structure.
*
* \param device opened video capture device
* \param format a format that can be used by the device (SDL_PixelFormatEnum)
* \param index framesize between 0 and num -1
* \param width output width
* \param height output height
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetNumVideoCaptureFrameSizes
*/
extern DECLSPEC int SDLCALL SDL_GetVideoCaptureFrameSize(SDL_VideoCaptureDevice *device, Uint32 format, int index, int *width, int *height);
/**
* Number of different framesizes available for the device and pixel format.
*
* \param device opened video capture device
* \param format frame pixel format (SDL_PixelFormatEnum)
* \returns number of framesizes or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetVideoCaptureFrameSize
* \sa SDL_SetVideoCaptureSpec
*/
extern DECLSPEC int SDLCALL SDL_GetNumVideoCaptureFrameSizes(SDL_VideoCaptureDevice *device, Uint32 format);
/**
* Get video capture status
*
* \param device opened video capture device
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_VideoCaptureStatus
*/
extern DECLSPEC SDL_VideoCaptureStatus SDLCALL SDL_GetVideoCaptureStatus(SDL_VideoCaptureDevice *device);
/**
* Start video capture
*
* \param device opened video capture device
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_StopVideoCapture
*/
extern DECLSPEC int SDLCALL SDL_StartVideoCapture(SDL_VideoCaptureDevice *device);
/**
* Acquire a frame.
*
* The frame is a memory pointer to the image data, whose size and format are
* given by the the obtained spec.
*
* Non blocking API. If there is a frame available, frame->num_planes is non
* 0. If frame->num_planes is 0 and returned code is 0, there is no frame at
* that time.
*
* After used, the frame should be released with SDL_ReleaseVideoCaptureFrame
*
* \param device opened video capture device
* \param frame pointer to get the frame
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_ReleaseVideoCaptureFrame
*/
extern DECLSPEC int SDLCALL SDL_AcquireVideoCaptureFrame(SDL_VideoCaptureDevice *device, SDL_VideoCaptureFrame *frame);
/**
* Release a frame.
*
* Let the back-end re-use the internal buffer for video capture.
*
* All acquired frames should be released before closing the device.
*
* \param device opened video capture device
* \param frame frame pointer.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_AcquireVideoCaptureFrame
*/
extern DECLSPEC int SDLCALL SDL_ReleaseVideoCaptureFrame(SDL_VideoCaptureDevice *device, SDL_VideoCaptureFrame *frame);
/**
* Stop Video Capture
*
* \param device opened video capture device
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_StartVideoCapture
*/
extern DECLSPEC int SDLCALL SDL_StopVideoCapture(SDL_VideoCaptureDevice *device);
/**
* Use this function to shut down video_capture processing and close the
* video_capture device.
*
* \param device opened video capture device
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_OpenVideoCaptureWithSpec
* \sa SDL_OpenVideoCapture
*/
extern DECLSPEC void SDLCALL SDL_CloseVideoCapture(SDL_VideoCaptureDevice *device);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}
#endif
#include <SDL3/SDL_close_code.h>
#endif /* SDL_video_capture_h_ */

38
include/SDL3/SDL_vulkan.h
View File

@ -22,7 +22,7 @@
/**
* \file SDL_vulkan.h
*
* \brief Header file for functions to creating Vulkan surfaces on SDL windows.
* Header file for functions to creating Vulkan surfaces on SDL windows.
*/
#ifndef SDL_vulkan_h_
@ -51,6 +51,7 @@ extern "C" {
VK_DEFINE_HANDLE(VkInstance)
VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR)
struct VkAllocationCallbacks;
#endif /* !NO_SDL_VULKAN_TYPEDEFS */
@ -135,33 +136,28 @@ extern DECLSPEC SDL_FunctionPointer SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(
extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
/**
* Get the names of the Vulkan instance extensions needed to create a surface
* with SDL_Vulkan_CreateSurface.
* Get the Vulkan instance extensions needed for vkCreateInstance.
*
* This should be called after either calling SDL_Vulkan_LoadLibrary() or
* creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
*
* If `pNames` is NULL, then the number of required Vulkan instance extensions
* is returned in `pCount`. Otherwise, `pCount` must point to a variable set
* to the number of elements in the `pNames` array, and on return the variable
* is overwritten with the number of names actually written to `pNames`. If
* `pCount` is less than the number of required extensions, at most `pCount`
* structures will be written. If `pCount` is smaller than the number of
* required extensions, SDL_FALSE will be returned instead of SDL_TRUE, to
* indicate that not all the required extensions were returned.
* On return, the variable pointed to by `pCount` will be set to the number of
* elements returned, suitable for using with
* VkInstanceCreateInfo::enabledExtensionCount, and the returned array can be
* used with VkInstanceCreateInfo::ppEnabledExtensionNames, for calling
* Vulkan's vkCreateInstance API.
*
* \param pCount A pointer to an unsigned int corresponding to the number of
* extensions to be returned
* \param pNames NULL or a pointer to an array to be filled with required
* Vulkan instance extensions
* \returns SDL_TRUE on success, SDL_FALSE on error.
* You should not free the returned array; it is owned by SDL.
*
* \param pCount A pointer to Uint32 that will be filled with the number of
* extensions returned.
* \returns An array of extension name strings on success, NULL on error.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_Vulkan_CreateSurface
*/
extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(unsigned int *pCount,
const char **pNames);
extern DECLSPEC char const* const* SDLCALL SDL_Vulkan_GetInstanceExtensions(Uint32 *pCount);
/**
* Create a Vulkan rendering surface for a window.
@ -170,8 +166,13 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(unsigned int *
* `instance` must have been created with extensions returned by
* SDL_Vulkan_GetInstanceExtensions() enabled.
*
* If `allocator` is NULL, Vulkan will use the system default allocator. This
* argument is passed directly to Vulkan and isn't used by SDL itself.
*
* \param window The window to which to attach the Vulkan surface
* \param instance The Vulkan instance handle
* \param allocator A VkAllocationCallbacks struct, which lets the app set the
* allocator that creates the surface. Can be NULL.
* \param surface A pointer to a VkSurfaceKHR handle to output the newly
* created surface
* \returns SDL_TRUE on success, SDL_FALSE on error.
@ -182,6 +183,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(unsigned int *
*/
extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window,
VkInstance instance,
const struct VkAllocationCallbacks *allocator,
VkSurfaceKHR* surface);
/* @} *//* Vulkan support functions */