eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-06-04 02:47:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Sync SDL3 wiki -> header

Browse source
This commit is contained in:
SDL Wiki Bot 2024-07-19 19:23:24 +00:00
parent a340de6196
commit 975457cfb6
30 changed files with 426 additions and 250 deletions
Download patch file Download diff file Expand all files Collapse all files

59
docs/README-strings.md Normal file
View file

@ -0,0 +1,59 @@
# String policies in SDL3.
## Encoding.
Unless otherwise specified, all strings in SDL, across all platforms, are
UTF-8 encoded and can represent the full range of [Unicode](https://unicode.org).
## The SDL Get String Rule.
Did you see 'SDL_GetStringRule' in the wiki or headers? Here are the details
that aren't worth copying across dozens of functions' documentation.
tl;dr: If an SDL function returns a `const char *` string, do not modify or
free it, and if you need to save it, make a copy right away.
In several cases, SDL wants to return a string to the app, and the question
in any library that does this is: _who owns this thing?_
The answer in almost all cases, is that SDL does, but not for long.
The pointer is only guaranteed to be valid until the next time the event
queue is updated, or SDL_Quit is called.
The reason for this is memory safety.
There are several strings that SDL provides that could be freed at
any moment. For example, an app calls SDL_GetAudioDeviceName(), which returns
a string that is part of the internal audio device structure. But, while this
function is returning, the user yanks the USB audio device out of the
computer, and SDL decides to deallocate the structure...and the string!
Now the app is holding a pointer that didn't live long enough to be useful,
and could crash if accessed.
To avoid this, instead of calling SDL_free on a string as soon as it's done
with it, SDL adds the pointer to a list. This list is freed at specific
points: when the event queue is run (for ongoing cleanup) and when SDL_Quit
is called (to catch things that are just hanging around). This allows the
app to use a string without worrying about it becoming bogus in the middle
of a printf() call. If the app needs it for longer, it should copy it.
When does "the event queue run"? There are several points:
- If the app calls SDL_PumpEvents() _from any thread_.
- SDL_PumpEvents is also called by several other APIs internally:
SDL_PollEvent(), SDL_PeepEvents(), SDL_WaitEvent(),
SDL_WaitEventTimeout(), and maybe others.
- If you are using [the main callbacks](main-functions#main-callbacks-in-sdl3),
the event queue can run immediately after any of the callback functions
return.
Note that these are just guaranteed minimum lifespans; any given string
might live much longer--some might even be static memory that is _never_
deallocated--but this rule promises that the app has a safe window.
Note that none of this applies if the return value is `char *` instead of
`const char *`. Please see the specific function's documentation for how
to handle those pointers.

68
include/SDL3/SDL_audio.h
View file

@ -400,7 +400,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
* "coreaudio" or "wasapi". These never have Unicode characters, and are not
* meant to be proper names.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param index the index of the audio driver; the value ranges from 0 to
* SDL_GetNumAudioDrivers() - 1.
@ -423,7 +424,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index);
* "coreaudio" or "wasapi". These never have Unicode characters, and are not
* meant to be proper names.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the name of the current audio driver or NULL if no driver has been
* initialized.
@ -448,11 +450,13 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void);
* If this function returns NULL, to signify an error, `*count` will be set to
* zero.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of devices returned, may be NULL.
* \returns a 0 terminated array of device instance IDs or NULL on error; call SDL_GetError() for more
* information.
* \param count a pointer filled in with the number of devices returned, may
* be NULL.
* \returns a 0 terminated array of device instance IDs or NULL on error; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -477,11 +481,13 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevice
* If this function returns NULL, to signify an error, `*count` will be set to
* zero.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of devices returned, may be NULL.
* \returns a 0 terminated array of device instance IDs, or NULL on failure; call SDL_GetError() for more
* information.
* \param count a pointer filled in with the number of devices returned, may
* be NULL.
* \returns a 0 terminated array of device instance IDs, or NULL on failure;
* call SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -495,7 +501,8 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevic
/**
* Get the human-readable name of a specific audio device.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param devid the instance ID of the device to query.
* \returns the name of the audio device, or NULL on failure; call
@ -555,7 +562,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid
* Audio devices usually have no remapping applied. This is represented by
* returning NULL, and does not signify an error.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param devid the instance ID of the device to query.
* \param count On output, set to number of channels in the map. Can be NULL.
@ -634,8 +642,8 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDe
* default device.
* \param spec the requested device configuration. Can be NULL to use
* reasonable defaults.
* \returns the device ID on success or 0 on failure; call SDL_GetError() for more
* information.
* \returns the device ID on success or 0 on failure; call SDL_GetError() for
* more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -739,8 +747,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev
* this function will always return -1.0f when used on physical devices.
*
* \param devid the audio device to query.
* \returns the gain of the device or -1.0f on failure; call
* SDL_GetError() for more information.
* \returns the gain of the device or -1.0f on failure; call SDL_GetError()
* for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -831,7 +839,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
* \param streams an array of audio streams to unbind.
* \param num_streams number streams listed in the `streams` array.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -851,8 +859,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SD
*
* \param devid an audio device to bind a stream to.
* \param stream an audio stream to bind to a device.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more
* information.
* \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.
*
@ -992,7 +1000,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream
* \param dst_spec the new format of the audio output; if NULL, it is not
* changed.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@ -1059,8 +1067,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream
* Audio streams default to a gain of 1.0f (no change in output).
*
* \param stream the SDL_AudioStream to query.
* \returns the gain of the stream or -1.0f on failure; call
* SDL_GetError() for more information.
* \returns the gain of the stream or -1.0f on failure; call SDL_GetError()
* for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@ -1105,7 +1113,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream,
* Audio streams default to no remapping applied. This is represented by
* returning NULL, and does not signify an error.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param stream the SDL_AudioStream to query.
* \param count On output, set to number of channels in the map. Can be NULL.
@ -1130,7 +1139,8 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_Au
* Audio streams default to no remapping applied. This is represented by
* returning NULL, and does not signify an error.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param stream the SDL_AudioStream to query.
* \param count On output, set to number of channels in the map. Can be NULL.
@ -1289,8 +1299,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream,
* \param stream the stream the audio is being requested from.
* \param buf a buffer to fill with audio data.
* \param len the maximum number of bytes to fill.
* \returns the number of bytes read from the stream or a negative error code on failure; call
* SDL_GetError() for more information.
* \returns the number of bytes read from the stream or a negative error code
* on failure; call SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, but if the
* stream has a callback set, the caller might need to manage
@ -1572,7 +1582,8 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream
* \param userdata an opaque pointer provided to the callback for its own
* personal use.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. This only fails if `stream` is NULL.
* SDL_GetError() for more information. This only fails if `stream`
* is NULL.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -1621,7 +1632,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *s
* \param userdata an opaque pointer provided to the callback for its own
* personal use.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. This only fails if `stream` is NULL.
* SDL_GetError() for more information. This only fails if `stream`
* is NULL.
*
* \threadsafety It is safe to call this function from any thread.
*

44
include/SDL3/SDL_camera.h
View file

@ -134,7 +134,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
* "coremedia" or "android". These never have Unicode characters, and are not
* meant to be proper names.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param index the index of the camera driver; the value ranges from 0 to
* SDL_GetNumCameraDrivers() - 1.
@ -156,7 +157,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index);
* "coremedia" or "android". These never have Unicode characters, and are not
* meant to be proper names.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the name of the current camera driver or NULL if no driver has
* been initialized.
@ -170,12 +172,13 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void);
/**
* Get a list of currently connected camera devices.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of cameras returned, may be
* NULL.
* \returns a 0 terminated array of camera instance IDs or NULL on failure; call SDL_GetError() for more
* information.
* \param count a pointer filled in with the number of cameras returned, may
* be NULL.
* \returns a 0 terminated array of camera instance IDs or NULL on failure;
* call SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -201,18 +204,20 @@ extern SDL_DECLSPEC const SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
* If `count` is not NULL, it will be filled with the number of elements in
* the returned array.
*
* Note that it's legal for a camera to supply an empty list. This is what will happen on
* Emscripten builds, since that platform won't tell _anything_ about
* available cameras until you've opened one, and won't even tell if there
* _is_ a camera until the user has given you permission to check through a
* scary warning popup.
* Note that it's legal for a camera to supply an empty list. This is what
* will happen on Emscripten builds, since that platform won't tell _anything_
* about available cameras until you've opened one, and won't even tell if
* there _is_ a camera until the user has given you permission to check
* through a scary warning popup.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param devid the camera device instance ID to query.
* \param count a pointer filled in with the number of elements in the list, may be NULL.
* \returns a NULL terminated array of pointers to SDL_CameraSpec or NULL on failure; call
* SDL_GetError() for more information.
* \param count a pointer filled in with the number of elements in the list,
* may be NULL.
* \returns a NULL terminated array of pointers to SDL_CameraSpec or NULL on
* failure; call SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -226,7 +231,8 @@ extern SDL_DECLSPEC const SDL_CameraSpec * const * SDLCALL SDL_GetCameraSupporte
/**
* Get the human-readable device name for a camera.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the camera device instance ID.
* \returns a human-readable device name or NULL on failure; call
@ -293,8 +299,8 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI
* \param instance_id the camera device instance ID.
* \param spec the desired format for data the device will provide. Can be
* NULL.
* \returns an SDL_Camera object or NULL on failure; call SDL_GetError() for more
* information.
* \returns an SDL_Camera object or NULL on failure; call SDL_GetError() for
* more information.
*
* \threadsafety It is safe to call this function from any thread.
*

9
include/SDL3/SDL_clipboard.h
View file

@ -62,7 +62,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
* This functions returns empty string if there was not enough memory left for
* a copy of the clipboard's content.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the clipboard text on success or an empty string on failure; call
* SDL_GetError() for more information.
@ -106,7 +107,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text);
* This functions returns empty string if there was not enough memory left for
* a copy of the primary selection's content.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the primary selection text on success or an empty string on
* failure; call SDL_GetError() for more information.
@ -221,7 +223,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearClipboardData(void);
* \returns the retrieved data buffer or NULL on failure; call SDL_GetError()
* for more information.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed
* later, and can be claimed with SDL_ClaimTemporaryMemory().
*
* \since This function is available since SDL 3.0.0.
*

5
include/SDL3/SDL_error.h
View file

@ -96,8 +96,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_OutOfMemory(void);
* Error strings are set per-thread, so an error set in a different thread
* will not interfere with the current thread's operation.
*
* The returned value is a thread-local string which will remain valid until the current thread's error string is changed. The caller
* should make a copy if the value is needed after the next SDL API call.
* The returned value is a thread-local string which will remain valid until
* the current thread's error string is changed. The caller should make a copy
* if the value is needed after the next SDL API call.
*
* \returns a message with information about the specific error that occurred,
* or an empty string if there hasn't been an error message set since

52
include/SDL3/SDL_events.h
View file

@ -350,7 +350,8 @@ typedef struct SDL_KeyboardEvent
* will be inserted into the editing text. The length is the number of UTF-8
* characters that will be replaced by new typing.
*
* The text string is temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* The text string is temporary memory which will be automatically freed
* later, and can be claimed with SDL_ClaimTemporaryMemory().
*
* \since This struct is available since SDL 3.0.0.
*/
@ -368,7 +369,8 @@ typedef struct SDL_TextEditingEvent
/**
* Keyboard IME candidates event structure (event.edit_candidates.*)
*
* The candidates are temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* The candidates are temporary memory which will be automatically freed
* later, and can be claimed with SDL_ClaimTemporaryMemory().
*
* \since This struct is available since SDL 3.0.0.
*/
@ -387,7 +389,8 @@ typedef struct SDL_TextEditingCandidatesEvent
/**
* Keyboard text input event structure (event.text.*)
*
* The text string is temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* The text string is temporary memory which will be automatically freed
* later, and can be claimed with SDL_ClaimTemporaryMemory().
*
* This event will never be delivered unless text input is enabled by calling
* SDL_StartTextInput(). Text input is disabled by default!
@ -784,7 +787,9 @@ typedef struct SDL_PenButtonEvent
* An event used to drop text or request a file open by the system
* (event.drop.*)
*
* The source and data strings are temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* The source and data strings are temporary memory which will be
* automatically freed later, and can be claimed with
* SDL_ClaimTemporaryMemory().
*
* \since This struct is available since SDL 3.0.0.
*/
@ -1409,7 +1414,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
/**
* Allocate temporary memory.
*
* You can use this to allocate memory that will be automatically freed later, after event processing is complete.
* You can use this to allocate memory that will be automatically freed later,
* after event processing is complete.
*
* \param size the amount of memory to allocate.
* \returns a pointer to the memory allocated or NULL on failure; call
@ -1427,13 +1433,20 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AllocateTemporaryMemory(size_t size);
/**
* Claim ownership of temporary memory.
*
* This function changes ownership of temporary memory allocated for events and functions that
* return temporary memory. If this function succeeds, the memory will no longer be automatically freed by SDL, it must be freed using SDL_free() by the application.
* This function changes ownership of temporary memory allocated for events
* and functions that return temporary memory. If this function succeeds, the
* memory will no longer be automatically freed by SDL, it must be freed using
* SDL_free() by the application.
*
* If the memory isn't temporary, or it was allocated on a different thread, or if it is associated with an event currently in the event queue, this will return NULL, and the application does not have ownership of the memory.
* If the memory isn't temporary, or it was allocated on a different thread,
* or if it is associated with an event currently in the event queue, this
* will return NULL, and the application does not have ownership of the
* memory.
*
* \param mem a pointer allocated with SDL_AllocateTemporaryMemory().
* \returns a pointer to the memory now owned by the application, which must be freed using SDL_free(), or NULL if the memory is not temporary or was allocated on a different thread.
* \returns a pointer to the memory now owned by the application, which must
* be freed using SDL_free(), or NULL if the memory is not temporary
* or was allocated on a different thread.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -1447,17 +1460,22 @@ extern SDL_DECLSPEC void * SDLCALL SDL_ClaimTemporaryMemory(const void *mem);
/**
* Free temporary memory.
*
* This function frees temporary memory allocated for events and functions that
* return temporary memory. This memory is local to the thread that creates
* it and is automatically freed for the main thread when processing events.
* For other threads you may call this function periodically to
* free any temporary memory created by that thread.
* This function frees temporary memory allocated for events and functions
* that return temporary memory. This memory is local to the thread that
* creates it and is automatically freed for the main thread when processing
* events. For other threads you may call this function periodically to free
* any temporary memory created by that thread.
*
* You can free a specific pointer, to provide more fine grained control over memory management, or you can pass NULL to free all pending temporary allocations.
* You can free a specific pointer, to provide more fine grained control over
* memory management, or you can pass NULL to free all pending temporary
* allocations.
*
* All temporary memory is freed on the main thread in SDL_Quit() and for other threads when they call SDL_CleanupTLS(), which is automatically called at cleanup time for threads created using SDL_CreateThread().
* All temporary memory is freed on the main thread in SDL_Quit() and for
* other threads when they call SDL_CleanupTLS(), which is automatically
* called at cleanup time for threads created using SDL_CreateThread().
*
* \param mem a pointer allocated with SDL_AllocateTemporaryMemory(), or NULL to free all pending temporary allocations.
* \param mem a pointer allocated with SDL_AllocateTemporaryMemory(), or NULL
* to free all pending temporary allocations.
*
* \threadsafety It is safe to call this function from any thread.
*

12
include/SDL3/SDL_filesystem.h
View file

@ -68,7 +68,8 @@ extern "C" {
* The returned path is guaranteed to end with a path separator ('\\' on
* Windows, '/' on most other platforms).
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns an absolute path in UTF-8 encoding to the application data
* directory. NULL will be returned on error or when the platform
@ -123,7 +124,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void);
* The returned path is guaranteed to end with a path separator ('\\' on
* Windows, '/' on most other platforms).
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param org the name of your organization.
* \param app the name of your application.
@ -223,7 +225,8 @@ typedef enum SDL_Folder
* The returned path is guaranteed to end with a path separator ('\\' on
* Windows, '/' on most other platforms).
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* If NULL is returned, the error may be obtained with SDL_GetError().
*
@ -354,7 +357,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *
* convenience, but if `count` is non-NULL, on return it will contain the
* number of items in the array, not counting the NULL terminator.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param path the path of the directory to enumerate.
* \param pattern the pattern that files in the directory must match. Can be

61
include/SDL3/SDL_gamepad.h
View file

@ -282,9 +282,9 @@ typedef struct SDL_GamepadBinding
* existing gamepad.
*
* The mapping string has the format "GUID,name,mapping", where GUID is the
* string value from SDL_GUIDToString(), name is the human readable
* string for the device and mappings are gamepad mappings to joystick ones.
* Under Windows there is a reserved GUID of "xinput" that covers all XInput
* string value from SDL_GUIDToString(), name is the human readable string for
* the device and mappings are gamepad mappings to joystick ones. Under
* Windows there is a reserved GUID of "xinput" that covers all XInput
* devices. The mapping format for joystick is:
*
* - `bX`: a joystick button, index X
@ -389,7 +389,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReloadGamepadMappings(void);
/**
* Get the current gamepad mappings.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of mappings returned, can
* be NULL.
@ -403,7 +404,8 @@ extern SDL_DECLSPEC const char * const * SDLCALL SDL_GetGamepadMappings(int *cou
/**
* Get the gamepad mapping string for a given GUID.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param guid a structure containing the GUID for which a mapping is desired.
* \returns a mapping string or NULL on failure; call SDL_GetError() for more
@ -419,7 +421,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID g
/**
* Get the current mapping of a gamepad.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* Details about mappings are discussed with SDL_AddGamepadMapping().
*
@ -468,11 +471,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void);
/**
* Get a list of currently connected gamepads.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of gamepads returned, may be NULL.
* \returns a 0 terminated array of joystick instance IDs or NULL on failure; call SDL_GetError() for
* more information.
* \param count a pointer filled in with the number of gamepads returned, may
* be NULL.
* \returns a 0 terminated array of joystick instance IDs or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -500,7 +505,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id);
*
* This can be called before any gamepads are opened.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the joystick instance ID.
* \returns the name of the selected gamepad. If no name can be found, this
@ -518,7 +524,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID
*
* This can be called before any gamepads are opened.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the joystick instance ID.
* \returns the path of the selected gamepad. If no path can be found, this
@ -651,7 +658,8 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys
*
* This can be called before any gamepads are opened.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the joystick instance ID.
* \returns the mapping string. Returns NULL if no mapping is available.
@ -750,7 +758,8 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad
/**
* Get the implementation-dependent name for an opened gamepad.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad().
@ -766,7 +775,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad
/**
* Get the implementation-dependent path for an opened gamepad.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad().
@ -893,7 +903,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *ga
*
* Returns the serial number of the gamepad, or NULL if it is not available.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param gamepad the gamepad object to query.
* \returns the serial number, or NULL if unavailable.
@ -972,7 +983,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
* SDL to crash.
*
* \param gamepad the gamepad object that you want to get a joystick from.
* \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError() for more information.
* \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -1053,7 +1065,8 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c
/**
* Convert from an SDL_GamepadType enum to a string.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param type an enum value for a given SDL_GamepadType.
* \returns a string for the given type, or NULL if an invalid type is
@ -1091,7 +1104,8 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c
/**
* Convert from an SDL_GamepadAxis enum to a string.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param axis an enum value for a given SDL_GamepadAxis.
* \returns a string for the given axis, or NULL if an invalid axis is
@ -1166,7 +1180,8 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con
/**
* Convert from an SDL_GamepadButton enum to a string.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param button an enum value for a given SDL_GamepadButton.
* \returns a string for the given button, or NULL if an invalid button is
@ -1454,7 +1469,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad);
* Return the sfSymbolsName for a given button on a gamepad on Apple
* platforms.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param gamepad the gamepad to query.
* \param button a button on the gamepad.
@ -1469,7 +1485,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButt
/**
* Return the sfSymbolsName for a given axis on a gamepad on Apple platforms.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param gamepad the gamepad to query.
* \param axis an axis on the gamepad.

3
include/SDL3/SDL_guid.h
View file

@ -66,7 +66,8 @@ typedef struct SDL_GUID {
/**
* Get an ASCII string representation for a given SDL_GUID.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param guid the SDL_GUID you wish to convert to string.
* \returns the string representation of the GUID or NULL on failure; call

13
include/SDL3/SDL_haptic.h
View file

@ -931,12 +931,13 @@ typedef Uint32 SDL_HapticID;
/**
* Get a list of currently connected haptic devices.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of haptic devices
* returned, may be NULL.
* \returns a 0 terminated array of haptic device instance IDs or NULL on failure; call SDL_GetError() for
* more information.
* \returns a 0 terminated array of haptic device instance IDs or NULL on
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -949,7 +950,8 @@ extern SDL_DECLSPEC const SDL_HapticID * SDLCALL SDL_GetHaptics(int *count);
*
* This can be called before any haptic devices are opened.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the haptic device instance ID.
* \returns the name of the selected haptic device. If no name can be found,
@ -1014,7 +1016,8 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic);
/**
* Get the implementation dependent name of a haptic device.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param haptic the SDL_Haptic obtained from SDL_OpenJoystick().
* \returns the name of the selected haptic device. If no name can be found,

32
include/SDL3/SDL_hidapi.h
View file

@ -263,8 +263,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *d
* \param serial_number the Serial Number of the device to open (Optionally
* NULL).
* \returns a pointer to a SDL_hid_device object on success or NULL on
* failure; call
* SDL_GetError() for more information.
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -278,8 +277,7 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_
*
* \param path the path name of the device to open.
* \returns a pointer to a SDL_hid_device object on success or NULL on
* failure; call
* SDL_GetError() for more information.
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -326,9 +324,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigne
* number.
* \param milliseconds timeout in milliseconds or -1 for blocking wait.
* \returns the actual number of bytes read and -1 on on failure; call
* SDL_GetError() for more information. If no packet was
* available to be read within the timeout period, this function
* returns 0.
* SDL_GetError() for more information. If no packet was available to
* be read within the timeout period, this function returns 0.
*
* \since This function is available since SDL 3.0.0.
*/
@ -347,9 +344,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsign
* reports, make sure to read an extra byte for the report
* number.
* \returns the actual number of bytes read and -1 on failure; call
* SDL_GetError() for more information. If no packet was
* available to be read and the handle is in non-blocking mode, this
* function returns 0.
* SDL_GetError() for more information. If no packet was available to
* be read and the handle is in non-blocking mode, this function
* returns 0.
*
* \since This function is available since SDL 3.0.0.
*/
@ -393,7 +390,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int
* \param length the length in bytes of the data to send, including the report
* number.
* \returns the actual number of bytes written and -1 on failure; call
* SDL_GetError() for more information.
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -415,8 +412,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev,
* \param length the number of bytes to read, including an extra byte for the
* report ID. The buffer can be longer than the actual report.
* \returns the number of bytes read plus one for the report ID (which is
* still in the first byte), or -1 on on failure; call
* SDL_GetError() for more information.
* still in the first byte), or -1 on on failure; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -438,8 +435,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev,
* \param length the number of bytes to read, including an extra byte for the
* report ID. The buffer can be longer than the actual report.
* \returns the number of bytes read plus one for the report ID (which is
* still in the first byte), or -1 on on failure; call
* SDL_GetError() for more information.
* still in the first byte), or -1 on on failure; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -514,9 +511,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev,
*
* \param dev a device handle returned from SDL_hid_open().
* \returns a pointer to the SDL_hid_device_info for this hid_device or NULL
* on failure; call SDL_GetError() for more information.
* This struct is valid until the device is closed with
* SDL_hid_close().
* on failure; call SDL_GetError() for more information. This struct
* is valid until the device is closed with SDL_hid_close().
*
* \since This function is available since SDL 3.0.0.
*/

3
include/SDL3/SDL_hints.h
View file

@ -3883,7 +3883,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void);
/**
* Get the value of a hint.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param name the hint to query.
* \returns the string value of a hint or NULL if the hint isn't set.

25
include/SDL3/SDL_iostream.h
View file

@ -224,8 +224,8 @@ typedef struct SDL_IOStream SDL_IOStream;
* \param file a UTF-8 string representing the filename to open.
* \param mode an ASCII string representing the mode to be used for opening
* the file.
* \returns a pointer to the SDL_IOStream structure that is created or NULL
* on failure; call SDL_GetError() for more information.
* \returns a pointer to the SDL_IOStream structure that is created or NULL on
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -258,8 +258,8 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons
*
* \param mem a pointer to a buffer to feed an SDL_IOStream stream.
* \param size the buffer size, in bytes.
* \returns a pointer to a new SDL_IOStream structure or NULL on failure;
* call SDL_GetError() for more information.
* \returns a pointer to a new SDL_IOStream structure or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -291,8 +291,8 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size)
*
* \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream.
* \param size the buffer size, in bytes.
* \returns a pointer to a new SDL_IOStream structure or NULL on failure;
* call SDL_GetError() for more information.
* \returns a pointer to a new SDL_IOStream structure or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -319,8 +319,8 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, s
* - `SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER`: memory will be allocated in
* multiples of this size, defaulting to 1024.
*
* \returns a pointer to a new SDL_IOStream structure or NULL on failure;
* call SDL_GetError() for more information.
* \returns a pointer to a new SDL_IOStream structure or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -488,7 +488,8 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context);
* \param context a pointer to an SDL_IOStream structure.
* \param ptr a pointer to a buffer to read data into.
* \param size the number of bytes to read from the data source.
* \returns the number of bytes read, or 0 on end of file or other failure; call SDL_GetError() for more information.
* \returns the number of bytes read, or 0 on end of file or other failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -576,7 +577,8 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN
* \param datasize if not NULL, will store the number of bytes read.
* \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error.
* \returns the data or NULL on failure; call SDL_GetError() for more information.
* \returns the data or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*
@ -595,7 +597,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *da
*
* \param file the path to read all available data from.
* \param datasize if not NULL, will store the number of bytes read.
* \returns the data or NULL on failure; call SDL_GetError() for more information.
* \returns the data or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*

53
include/SDL3/SDL_joystick.h
View file

@ -37,9 +37,9 @@
* controller. For XInput controllers this returns the XInput user index. Many
* joysticks will not be able to supply this information.
*
* SDL_GUID is used as a stable 128-bit identifier for a joystick
* device that does not change over time. It identifies class of the device (a
* X360 wired controller for example). This identifier is platform dependent.
* SDL_GUID is used as a stable 128-bit identifier for a joystick device that
* does not change over time. It identifies class of the device (a X360 wired
* controller for example). This identifier is platform dependent.
*
* In order to use these functions, SDL_Init() must have been called with the
* SDL_INIT_JOYSTICK flag. This causes SDL to scan the system for joysticks,
@ -201,11 +201,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void);
/**
* Get a list of currently connected joysticks.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of joysticks returned, may be NULL.
* \returns a 0 terminated array of joystick instance IDs or NULL on failure; call SDL_GetError() for
* more information.
* \param count a pointer filled in with the number of joysticks returned, may
* be NULL.
* \returns a 0 terminated array of joystick instance IDs or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -219,7 +221,8 @@ extern SDL_DECLSPEC const SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count);
*
* This can be called before any joysticks are opened.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the joystick instance ID.
* \returns the name of the selected joystick. If no name can be found, this
@ -237,7 +240,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID
*
* This can be called before any joysticks are opened.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the joystick instance ID.
* \returns the path of the selected joystick. If no path can be found, this
@ -356,8 +360,8 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_Joysti
* for use.
*
* \param instance_id the joystick instance ID.
* \returns a joystick identifier or NULL on failure; call
* SDL_GetError() for more information.
* \returns a joystick identifier or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -462,8 +466,8 @@ typedef struct SDL_VirtualJoystickDesc
* Attach a new virtual joystick.
*
* \param desc joystick description.
* \returns the joystick instance ID, or 0 on failure; call
* SDL_GetError() for more information.
* \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -658,7 +662,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst
/**
* Get the implementation dependent name of a joystick.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the name of the selected joystick. If no name can be found, this
@ -673,7 +678,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joyst
/**
* Get the implementation dependent path of a joystick.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the path of the selected joystick. If no path can be found, this
@ -792,7 +798,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *
*
* Returns the serial number of the joystick, or NULL if it is not available.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the serial number of the selected joystick, or NULL if
@ -814,20 +821,6 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joy
*/
extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *joystick);
/**
* Convert a GUID string into a SDL_GUID structure.
*
* Performs no error checking. If this function is given a string containing
* an invalid GUID, the function will silently succeed, but the GUID generated
* will not be useful.
*
* \param pchGUID string containing an ASCII representation of a GUID.
* \returns a SDL_GUID structure.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GUIDToString
*/
extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GUIDFromString(const char *pchGUID);
/**

19
include/SDL3/SDL_keyboard.h
View file

@ -73,11 +73,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void);
* power buttons, etc. You should wait for input from a device before you
* consider it actively in use.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of keyboards returned, may be NULL.
* \returns a 0 terminated array of keyboards instance IDs or NULL on failure; call SDL_GetError() for
* more information.
* \param count a pointer filled in with the number of keyboards returned, may
* be NULL.
* \returns a 0 terminated array of keyboards instance IDs or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -91,7 +93,8 @@ extern SDL_DECLSPEC const SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count);
*
* This function returns "" if the keyboard doesn't have a name.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the keyboard instance ID.
* \returns the name of the selected keyboard or NULL on failure; call
@ -281,7 +284,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const
/**
* Get a human-readable name for a scancode.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* **Warning**: The returned name is by design not stable across platforms,
* e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
@ -327,7 +331,8 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam
*
* If the key doesn't have a name, this function returns an empty string ("").
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param key the desired SDL_Keycode to query.
* \returns a UTF-8 encoded string of the key name.

7
include/SDL3/SDL_loadso.h
View file

@ -56,7 +56,8 @@ extern "C" {
* Dynamically load a shared object.
*
* \param sofile a system-dependent name of the object file.
* \returns an opaque pointer to the object handle or NULL on failure; call SDL_GetError() for more information.
* \returns an opaque pointer to the object handle or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -82,8 +83,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_LoadObject(const char *sofile);
*
* \param handle a valid shared object handle returned by SDL_LoadObject().
* \param name the name of the function to look up.
* \returns a pointer to the function or NULL on failure; call
* SDL_GetError() for more information.
* \returns a pointer to the function or NULL on failure; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 3.0.0.
*

7
include/SDL3/SDL_locale.h
View file

@ -94,12 +94,13 @@ typedef struct SDL_Locale
* if possible, and you can call this function again to get an updated copy of
* preferred locales.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of locales returned, may
* be NULL.
* \returns a NULL terminated array of locale pointers, or NULL on failure; call SDL_GetError() for more
* information.
* \returns a NULL terminated array of locale pointers, or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/

16
include/SDL3/SDL_mouse.h
View file

@ -135,11 +135,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void);
* You should wait for input from a device before you consider it actively in
* use.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of mice returned, may be NULL.
* \returns a 0 terminated array of mouse instance IDs or NULL on failure; call SDL_GetError() for more
* information.
* \param count a pointer filled in with the number of mice returned, may be
* NULL.
* \returns a 0 terminated array of mouse instance IDs or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -153,7 +155,8 @@ extern SDL_DECLSPEC const SDL_MouseID * SDLCALL SDL_GetMice(int *count);
*
* This function returns "" if the mouse doesn't have a name.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the mouse instance ID.
* \returns the name of the selected mouse, or NULL on failure; call
@ -483,7 +486,8 @@ extern SDL_DECLSPEC SDL_Cursor * SDLCALL SDL_GetCursor(void);
* You do not have to call SDL_DestroyCursor() on the return value, but it is
* safe to do so.
*
* \returns the default cursor on success or NULL on failuree; call SDL_GetError() for more information.
* \returns the default cursor on success or NULL on failuree; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/

3
include/SDL3/SDL_pen.h
View file

@ -224,7 +224,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
/**
* Retrieves a human-readable description for a SDL_PenID.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the pen to query.
* \returns a string that contains the name of the pen, intended for human

3
include/SDL3/SDL_properties.h
View file

@ -378,7 +378,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props
/**
* Get a string property from a group of properties.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param props the properties to query.
* \param name the name of the property to query.

17
include/SDL3/SDL_render.h
View file

@ -154,7 +154,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
* "direct3d12" or "metal". These never have Unicode characters, and are not
* meant to be proper names.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param index the index of the rendering driver; the value ranges from 0 to
* SDL_GetNumRenderDrivers() - 1.
@ -324,10 +325,12 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *rende
/**
* Get the name of a renderer.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param renderer the rendering context.
* \returns the name of the selected renderer, or NULL on failure; call SDL_GetError() for more information.
* \returns the name of the selected renderer, or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -1768,7 +1771,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SD
* \param rect a pointer to the destination rectangle, or NULL to outline the
* entire rendering target.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -1800,7 +1803,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SD
* \param rect a pointer to the destination rectangle, or NULL for the entire
* rendering target.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -1835,7 +1838,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, cons
* \param dstrect a pointer to the destination rectangle, or NULL for the
* entire rendering target.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -1886,7 +1889,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer,
* order.
* \param num_indices number of indices.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*

25
include/SDL3/SDL_sensor.h
View file

@ -146,9 +146,10 @@ typedef enum SDL_SensorType
/**
* Get a list of currently connected sensors.
*
* \param count a pointer filled in with the number of sensors returned, may be NULL.
* \returns a 0 terminated array of sensor instance IDs or NULL on failure; call SDL_GetError() for more
* information.
* \param count a pointer filled in with the number of sensors returned, may
* be NULL.
* \returns a 0 terminated array of sensor instance IDs or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -159,7 +160,8 @@ extern SDL_DECLSPEC const SDL_SensorID * SDLCALL SDL_GetSensors(int *count);
*
* This can be called before any sensors are opened.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the sensor instance ID.
* \returns the sensor name, or NULL if `instance_id` is not valid.
@ -198,7 +200,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID i
* Open a sensor for use.
*
* \param instance_id the sensor instance ID.
* \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for more information.
* \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -208,7 +211,8 @@ extern SDL_DECLSPEC SDL_Sensor * SDLCALL SDL_OpenSensor(SDL_SensorID instance_id
* Return the SDL_Sensor associated with an instance ID.
*
* \param instance_id the sensor instance ID.
* \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for more information.
* \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -228,10 +232,12 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor
/**
* Get the implementation dependent name of a sensor.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param sensor the SDL_Sensor object.
* \returns the sensor name or NULL on failure; call SDL_GetError() for more information.
* \returns the sensor name or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -262,7 +268,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor)
* Get the instance ID of a sensor.
*
* \param sensor the SDL_Sensor object to inspect.
* \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for more information.
* \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*/

11
include/SDL3/SDL_storage.h
View file

@ -227,8 +227,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage);
* \param storage a storage container to query.
* \param path the relative path of the file to query.
* \param length a pointer to be filled with the file's length.
* \returns 0 if the file could be queried or a negative error code on failure; call
* SDL_GetError() for more information.
* \returns 0 if the file could be queried or a negative error code on
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -263,8 +263,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const
* \param path the relative path of the file to write.
* \param source a client-provided buffer to write from.
* \param length the length of the source buffer.
* \returns 0 if the file was written or a negative error code on failure; call
* SDL_GetError() for more information.
* \returns 0 if the file was written or a negative error code on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -383,7 +383,8 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto
* convenience, but if `count` is non-NULL, on return it will contain the
* number of items in the array, not counting the NULL terminator.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param storage a storage container.
* \param path the path of the directory to enumerate.

8
include/SDL3/SDL_surface.h
View file

@ -355,8 +355,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
* \param src the data stream for the surface.
* \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error.
* \returns a pointer to a new SDL_Surface structure or NULL on failure;
* call SDL_GetError() for more information.
* \returns a pointer to a new SDL_Surface structure or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -373,8 +373,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_
* will result in a memory leak.
*
* \param file the BMP file to load.
* \returns a pointer to a new SDL_Surface structure or NULL on failure;
* call SDL_GetError() for more information.
* \returns a pointer to a new SDL_Surface structure or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*

24
include/SDL3/SDL_system.h
View file

@ -162,7 +162,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback,
*
* \param threadID the Unix thread ID to change priority of.
* \param priority the new, Unix-specific, priority value.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
* \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.
*/
@ -280,7 +281,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled);
* rationale being that the SDL headers can avoid including jni.h.
*
* \returns a pointer to Java native interface object (JNIEnv) to which the
* current thread is attached, or NULL on failure; call SDL_GetError() for more information.
* current thread is attached, or NULL on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -304,7 +306,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void);
* https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
*
* \returns the jobject representing the instance of the Activity class of the
* Android application, or NULL on failure; call SDL_GetError() for more information.
* Android application, or NULL on failure; call SDL_GetError() for
* more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -407,7 +410,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void);
*
* https://developer.android.com/reference/android/content/Context#getFilesDir()
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the path used for internal storage or NULL on failure; call
* SDL_GetError() for more information.
@ -448,7 +452,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void);
*
* https://developer.android.com/reference/android/content/Context#getExternalFilesDir()
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the path used for external storage for this application on success
* or NULL on failure; call SDL_GetError() for more information.
@ -471,7 +476,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void)
*
* https://developer.android.com/reference/android/content/Context#getCacheDir()
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the path used for caches for this application on success or NULL
* on failure; call SDL_GetError() for more information.
@ -625,7 +631,8 @@ typedef enum SDL_WinRT_DeviceFamily
*
* https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param pathType the type of path to retrieve, one of SDL_WinRT_Path.
* \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if
@ -813,7 +820,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle *outTaskQue
*
* \param outUserHandle a pointer to be filled in with the default user
* handle.
* \returns 0 if success or a negative error code on failure; call SDL_GetError() for more information.
* \returns 0 if success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/

7
include/SDL3/SDL_thread.h
View file

@ -330,7 +330,8 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(S
/**
* Get the thread name as it was specified in SDL_CreateThread().
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param thread the thread to query.
* \returns a pointer to a UTF-8 string that names the specified thread, or
@ -520,7 +521,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetTLS(SDL_TLSID *id, const void *value, SDL
/**
* Cleanup all TLS data for this thread.
*
* If you are creating your threads outside of SDL and then calling SDL functions, you should call this function before your thread exits, to properly clean up SDL memory.
* If you are creating your threads outside of SDL and then calling SDL
* functions, you should call this function before your thread exits, to
* properly clean up SDL memory.
*
* \threadsafety It is safe to call this function from any thread.
*

22
include/SDL3/SDL_time.h
View file

@ -95,7 +95,8 @@ typedef enum SDL_TimeFormat
* format, may be NULL.
* \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time
* format, may be NULL.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
* \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.
*/
@ -106,7 +107,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat
* Jan 1, 1970 in Universal Coordinated Time (UTC).
*
* \param ticks the SDL_Time to hold the returned tick count.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
* \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.
*/
@ -121,7 +123,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentTime(SDL_Time *ticks);
* \param localTime the resulting SDL_DateTime will be expressed in local time
* if true, otherwise it will be in Universal Coordinated
* Time (UTC).
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
* \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.
*/
@ -135,7 +138,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime
*
* \param dt the source SDL_DateTime.
* \param ticks the resulting SDL_Time.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
* \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.
*/
@ -177,7 +181,8 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U
*
* \param year the year.
* \param month the month [1-12].
* \returns the number of days in the requested month or a negative error code on failure; call SDL_GetError() for more information.
* \returns the number of days in the requested month or a negative error code
* on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -189,7 +194,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month);
* \param year the year component of the date.
* \param month the month component of the date.
* \param day the day component of the date.
* \returns the day of year [0-365] if the date is valid or a negative error code on failure; call SDL_GetError() for more information.
* \returns the day of year [0-365] if the date is valid or a negative error
* code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -201,7 +207,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day);
* \param year the year component of the date.
* \param month the month component of the date.
* \param day the day component of the date.
* \returns a value between 0 and 6 (0 being Sunday) if the date is valid or a negative error code on failure; call SDL_GetError() for more information.
* \returns a value between 0 and 6 (0 being Sunday) if the date is valid or a
* negative error code on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*/

14
include/SDL3/SDL_touch.h
View file

@ -83,12 +83,13 @@ typedef struct SDL_Finger
* Therefore the returned list might be empty, although devices are available.
* After using all devices at least once the number will be correct.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of devices returned, may
* be NULL.
* \returns a 0 terminated array of touch device IDs or NULL on failure; call SDL_GetError() for more
* information.
* \returns a 0 terminated array of touch device IDs or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -97,11 +98,12 @@ extern SDL_DECLSPEC const SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count);
/**
* Get the touch device name as reported from the driver.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param touchID the touch device instance ID.
* \returns touch device name, or NULL on failure; call SDL_GetError() for more
* information.
* \returns touch device name, or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*/

45
include/SDL3/SDL_video.h
View file

@ -349,7 +349,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
* "x11" or "windows". These never have Unicode characters, and are not meant
* to be proper names.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param index the index of a video driver.
* \returns the name of the video driver with the given **index**.
@ -367,7 +368,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index);
* "x11" or "windows". These never have Unicode characters, and are not meant
* to be proper names.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the name of the current video driver or NULL if no driver has been
* initialized.
@ -391,12 +393,13 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
/**
* Get a list of currently connected displays.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of displays returned, may
* be NULL.
* \returns a 0 terminated array of display instance IDs or NULL on failure; call SDL_GetError() for more
* information.
* \returns a 0 terminated array of display instance IDs or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -446,7 +449,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa
/**
* Get the name of a display in UTF-8 encoding.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param displayID the instance ID of the display to query.
* \returns the name of a display or NULL on failure; call SDL_GetError() for
@ -555,12 +559,14 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ
* - refresh rate -> highest to lowest
* - pixel density -> lowest to highest
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param displayID the instance ID of the display to query.
* \param count a pointer filled in with the number of display modes returned, may be NULL.
* \returns a NULL terminated array of display mode pointers or NULL on failure; call SDL_GetError() for
* more information.
* \param count a pointer filled in with the number of display modes returned,
* may be NULL.
* \returns a NULL terminated array of display mode pointers or NULL on
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -767,7 +773,8 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode(
/**
* Get the raw ICC profile data for the screen the window is currently on.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param window the window to query.
* \param size the size of the ICC profile.
@ -793,11 +800,13 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window
/**
* Get a list of valid windows.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of windows returned, may
* be NULL.
* \returns a NULL terminated array of SDL_Window pointers or NULL on failure; call SDL_GetError() for more information.
* \returns a NULL terminated array of SDL_Window pointers or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -1306,7 +1315,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowTitle(SDL_Window *window, const cha
/**
* Get the title of a window.
*
* This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory().
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param window the window to query.
* \returns the title of the window in UTF-8 format or "" if there is no
@ -2175,7 +2185,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window);
*
* \param modal_window the window that should be set modal.
* \param parent_window the parent window for the modal window.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
* \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.
*/
@ -2584,8 +2595,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value)
* SDL_GLContext is opaque to the application.
*
* \param window the window to associate with the context.
* \returns the OpenGL context associated with `window` or NULL on failure; call
* SDL_GetError() for more information.
* \returns the OpenGL context associated with `window` or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*

9
include/SDL3/SDL_vulkan.h
View file

@ -119,7 +119,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
* `vkGetInstanceProcAddr =
* (PFN_vkGetInstanceProcAddr)SDL_Vulkan_GetVkGetInstanceProcAddr();`
*
* \returns the function pointer for `vkGetInstanceProcAddr` or NULL on failure; call SDL_GetError() for more information.
* \returns the function pointer for `vkGetInstanceProcAddr` or NULL on
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -149,7 +150,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
* You should not free the returned array; it is owned by SDL.
*
* \param count a pointer filled in with the number of extensions returned.
* \returns an array of extension name strings on success, NULL on failure; call SDL_GetError() for more information.
* \returns an array of extension name strings on success, NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -173,7 +175,8 @@ extern SDL_DECLSPEC char const * const * SDLCALL SDL_Vulkan_GetInstanceExtension
* allocator that creates the surface. Can be NULL.
* \param surface a pointer to a VkSurfaceKHR handle to output the newly
* created surface.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
* \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.
*