mirrors/SDL
0
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2024-11-23 02:43:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

Don't automatically free temporary memory, let the application call SDL_FreeTemporaryMemory() when it's ready.

Browse Source 
Also mark up all functions that return temporary memory with SDL_DECLSPEC_TEMP, to help people implementing language bindings.

Fixes https://github.com/libsdl-org/SDL/issues/10378
This commit is contained in:
Sam Lantinga 2024-07-26 06:05:57 -07:00
parent 2f38a4bf5e
commit 5e513ecc7f
31 changed files with 124 additions and 402 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
build-scripts/wikiheaders.pl
View File

@ -936,7 +936,7 @@ while (my $d = readdir(DH)) {
my $paramsstr = undef;
if (!$is_forced_inline && $decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\s+(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(\*?)\s*SDLCALL\s+(.*?)\s*\((.*?)\);/) {
if (!$is_forced_inline && $decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\w*\s+(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(\*?)\s*SDLCALL\s+(.*?)\s*\((.*?)\);/) {
$sym = $8;
$rettype = "$3$4$5$6";
$paramsstr = $9;
@ -1000,15 +1000,21 @@ while (my $d = readdir(DH)) {
}
if (!$is_forced_inline) { # don't do with forced-inline because we don't want the implementation inserted in the wiki.
my $shrink_length = 0;
$decl = ''; # rebuild this with the line breaks, since it looks better for syntax highlighting.
foreach (@decllines) {
if ($decl eq '') {
my $temp;
$decl = $_;
$decl =~ s/\Aextern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\s+(.*?)\s+(\*?)SDLCALL\s+/$3$4 /;
$temp = $decl;
$temp =~ s/\Aextern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\w*\s+(.*?)\s+(\*?)SDLCALL\s+/$3$4 /;
$shrink_length = length($decl) - length($temp);
$decl = $temp;
} else {
my $trimmed = $_;
# !!! FIXME: trim space for SDL_DEPRECATED if it was used, too.
$trimmed =~ s/\A\s{28}//; # 28 for shrinking to match the removed "extern SDL_DECLSPEC SDLCALL "
$trimmed =~ s/\A\s{$shrink_length}//; # shrink to match the removed "extern SDL_DECLSPEC SDLCALL "
$decl .= $trimmed;
}
$decl .= "\n";

1
docs/doxyfile
View File

@ -1298,6 +1298,7 @@ INCLUDE_FILE_PATTERNS =
PREDEFINED = DOXYGEN_SHOULD_IGNORE_THIS=1 \
SDL_DECLSPEC= \
SDL_DECLSPEC_TEMP= \
SDLCALL= \
_WIN32=1

40
include/SDL3/SDL_audio.h
View File

@ -400,9 +400,6 @@ 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().
*
* \param index the index of the audio driver; the value ranges from 0 to
* SDL_GetNumAudioDrivers() - 1.
* \returns the name of the audio driver at the requested index, or NULL if an
@ -414,7 +411,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
*
* \sa SDL_GetNumAudioDrivers
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetAudioDriver(int index);
/* @} */
/**
@ -424,9 +421,6 @@ 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().
*
* \returns the name of the current audio driver or NULL if no driver has been
* initialized.
*
@ -434,7 +428,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index);
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetCurrentAudioDriver(void);
/**
* Get a list of currently-connected audio playback devices.
@ -450,9 +444,6 @@ 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().
*
* \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
@ -465,7 +456,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void);
* \sa SDL_OpenAudioDevice
* \sa SDL_GetAudioRecordingDevices
*/
extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int *count);
extern SDL_DECLSPEC_TEMP const SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int *count);
/**
* Get a list of currently-connected audio recording devices.
@ -481,9 +472,6 @@ 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().
*
* \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;
@ -496,14 +484,11 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevice
* \sa SDL_OpenAudioDevice
* \sa SDL_GetAudioPlaybackDevices
*/
extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int *count);
extern SDL_DECLSPEC_TEMP const SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int *count);
/**
* 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().
*
* \param devid the instance ID of the device to query.
* \returns the name of the audio device, or NULL on failure; call
* SDL_GetError() for more information.
@ -516,7 +501,7 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevic
* \sa SDL_GetAudioRecordingDevices
* \sa SDL_GetDefaultAudioInfo
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);
/**
* Get the current audio format of a specific audio device.
@ -562,9 +547,6 @@ 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().
*
* \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.
* \returns an array of the current channel mapping, with as many elements as
@ -576,7 +558,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid
*
* \sa SDL_SetAudioStreamInputChannelMap
*/
extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID devid, int *count);
extern SDL_DECLSPEC_TEMP const int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID devid, int *count);
/**
* Open a specific audio device.
@ -1113,9 +1095,6 @@ 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().
*
* \param stream the SDL_AudioStream to query.
* \param count On output, set to number of channels in the map. Can be NULL.
* \returns an array of the current channel mapping, with as many elements as
@ -1128,7 +1107,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream,
*
* \sa SDL_SetAudioStreamInputChannelMap
*/
extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStream *stream, int *count);
extern SDL_DECLSPEC_TEMP const int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStream *stream, int *count);
/**
* Get the current output channel map of an audio stream.
@ -1139,9 +1118,6 @@ 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().
*
* \param stream the SDL_AudioStream to query.
* \param count On output, set to number of channels in the map. Can be NULL.
* \returns an array of the current channel mapping, with as many elements as
@ -1154,7 +1130,7 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_Au
*
* \sa SDL_SetAudioStreamInputChannelMap
*/
extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioStream *stream, int *count);
extern SDL_DECLSPEC_TEMP const int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioStream *stream, int *count);
/**
* Set the current input channel map of an audio stream.

2
include/SDL3/SDL_begin_code.h
View File

@ -67,6 +67,8 @@
# endif
# endif
#endif
/* This is used to mark functions that return temporary memory */
#define SDL_DECLSPEC_TEMP SDL_DECLSPEC
/* By default SDL uses the C calling convention */
#ifndef SDLCALL

25
include/SDL3/SDL_camera.h
View File

@ -134,9 +134,6 @@ 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().
*
* \param index the index of the camera driver; the value ranges from 0 to
* SDL_GetNumCameraDrivers() - 1.
* \returns the name of the camera driver at the requested index, or NULL if
@ -148,7 +145,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
*
* \sa SDL_GetNumCameraDrivers
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetCameraDriver(int index);
/**
* Get the name of the current camera driver.
@ -157,9 +154,6 @@ 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().
*
* \returns the name of the current camera driver or NULL if no driver has
* been initialized.
*
@ -167,14 +161,11 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index);
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void);
extern SDL_DECLSPEC_TEMP 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().
*
* \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;
@ -186,7 +177,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void);
*
* \sa SDL_OpenCamera
*/
extern SDL_DECLSPEC const SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
extern SDL_DECLSPEC_TEMP const SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
/**
* Get the list of native formats/sizes a camera supports.
@ -210,9 +201,6 @@ extern SDL_DECLSPEC const SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
* 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().
*
* \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.
@ -226,14 +214,11 @@ extern SDL_DECLSPEC const SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
* \sa SDL_GetCameras
* \sa SDL_OpenCamera
*/
extern SDL_DECLSPEC const SDL_CameraSpec * const * SDLCALL SDL_GetCameraSupportedFormats(SDL_CameraID devid, int *count);
extern SDL_DECLSPEC_TEMP const SDL_CameraSpec * const * SDLCALL SDL_GetCameraSupportedFormats(SDL_CameraID devid, int *count);
/**
* 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().
*
* \param instance_id the camera device instance ID.
* \returns a human-readable device name or NULL on failure; call
* SDL_GetError() for more information.
@ -244,7 +229,7 @@ extern SDL_DECLSPEC const SDL_CameraSpec * const * SDLCALL SDL_GetCameraSupporte
*
* \sa SDL_GetCameras
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance_id);
/**
* Get the position of the camera in relation to the system.

15
include/SDL3/SDL_clipboard.h
View File

@ -62,9 +62,6 @@ 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().
*
* \returns the clipboard text on success or an empty string on failure; call
* SDL_GetError() for more information.
*
@ -73,7 +70,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
* \sa SDL_HasClipboardText
* \sa SDL_SetClipboardText
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetClipboardText(void);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetClipboardText(void);
/**
* Query whether the clipboard exists and contains a non-empty text string.
@ -107,9 +104,6 @@ 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().
*
* \returns the primary selection text on success or an empty string on
* failure; call SDL_GetError() for more information.
*
@ -118,7 +112,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text);
* \sa SDL_HasPrimarySelectionText
* \sa SDL_SetPrimarySelectionText
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetPrimarySelectionText(void);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetPrimarySelectionText(void);
/**
* Query whether the primary selection exists and contains a non-empty text
@ -223,15 +217,12 @@ 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().
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_HasClipboardData
* \sa SDL_SetClipboardData
*/
extern SDL_DECLSPEC const void * SDLCALL SDL_GetClipboardData(const char *mime_type, size_t *size);
extern SDL_DECLSPEC_TEMP const void * SDLCALL SDL_GetClipboardData(const char *mime_type, size_t *size);
/**
* Query whether there is data in the clipboard for the provided mime type.

46
include/SDL3/SDL_events.h
View File

@ -352,8 +352,7 @@ 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 freed in SDL_FreeTemporaryMemory() and can be claimed with SDL_ClaimTemporaryMemory().
*
* \since This struct is available since SDL 3.0.0.
*/
@ -371,8 +370,7 @@ 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 a single allocation of temporary memory which will be freed in SDL_FreeTemporaryMemory() and can be claimed with SDL_ClaimTemporaryMemory().
*
* \since This struct is available since SDL 3.0.0.
*/
@ -391,8 +389,7 @@ 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 freed in SDL_FreeTemporaryMemory() 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!
@ -789,9 +786,7 @@ 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 freed in SDL_FreeTemporaryMemory() and can be claimed with SDL_ClaimTemporaryMemory().
*
* \since This struct is available since SDL 3.0.0.
*/
@ -856,6 +851,8 @@ typedef struct SDL_QuitEvent
* the programmer; the only requirement is that '''type''' is a value obtained
* from SDL_RegisterEvents().
*
* If the data pointers are temporary memory, they will be automatically transfered to the thread that pulls the event from the queue, or freed if the event is flushed.
*
* \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_UserEvent
@ -1416,8 +1413,7 @@ 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 from the temporary memory pool for the current thread.
*
* \param size the amount of memory to allocate.
* \returns a pointer to the memory allocated or NULL on failure; call
@ -1428,24 +1424,18 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_ClaimTemporaryMemory
* \sa SDL_FreeTemporaryMemory
*/
extern SDL_DECLSPEC void * SDLCALL SDL_AllocateTemporaryMemory(size_t size);
/**
* Claim ownership of temporary memory.
*
* Some functions return temporary memory which SDL will automatically clean
* up. If you want to hold onto it past the current event being handled or
* beyond the current function scope, you can call this function to get a
* pointer that you own, and can free using SDL_free() when you're done.
*
* If the memory isn't temporary, this will return NULL, and you don't have
* ownership of the memory.
* This function removes memory from the temporary memory pool for the current thread and gives ownership to the application. The application should use SDL_free() to free it when it is done using it.
*
* \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 is not owned by this thread.
* be freed using SDL_free(), or NULL if the memory is not in the temporary memory pool for the current thread.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -1456,6 +1446,22 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AllocateTemporaryMemory(size_t size);
*/
extern SDL_DECLSPEC void * SDLCALL SDL_ClaimTemporaryMemory(const void *mem);
/**
* Free temporary memory for the current thread.
*
* This function frees all temporary memory for the current thread. If you would like to hold onto a specific pointer beyond this call, you should call SDL_ClaimTemporaryMemory() to move it out of the temporary memory pool.
*
* This function is automatically called in SDL_Quit() on the main thread and in SDL_CleanupTLS() when other threads complete.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_AllocateTemporaryMemory
* \sa SDL_ClaimTemporaryMemory
*/
extern SDL_DECLSPEC void SDLCALL SDL_FreeTemporaryMemory(void);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus
}

20
include/SDL3/SDL_filesystem.h
View File

@ -68,9 +68,6 @@ 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().
*
* \returns an absolute path in UTF-8 encoding to the application data
* directory. NULL will be returned on error or when the platform
* doesn't implement this functionality, call SDL_GetError() for more
@ -80,7 +77,7 @@ extern "C" {
*
* \sa SDL_GetPrefPath
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetBasePath(void);
/**
* Get the user-and-app-specific path where files can be written.
@ -124,9 +121,6 @@ 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().
*
* \param org the name of your organization.
* \param app the name of your application.
* \returns a UTF-8 string of the user directory in platform-dependent
@ -137,7 +131,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void);
*
* \sa SDL_GetBasePath
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetPrefPath(const char *org, const char *app);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetPrefPath(const char *org, const char *app);
/**
* The type of the OS-provided default folder for a specific purpose.
@ -225,9 +219,6 @@ 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().
*
* If NULL is returned, the error may be obtained with SDL_GetError().
*
* \param folder the type of folder to find.
@ -236,7 +227,7 @@ typedef enum SDL_Folder
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetUserFolder(SDL_Folder folder);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetUserFolder(SDL_Folder folder);
/* Abstract filesystem interface */
@ -369,9 +360,6 @@ 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().
*
* \param path the path of the directory to enumerate.
* \param pattern the pattern that files in the directory must match. Can be
* NULL.
@ -385,7 +373,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * const * SDLCALL SDL_GlobDirectory(const char *path, const char *pattern, SDL_GlobFlags flags, int *count);
extern SDL_DECLSPEC_TEMP const char * const * SDLCALL SDL_GlobDirectory(const char *path, const char *pattern, SDL_GlobFlags flags, int *count);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus

80
include/SDL3/SDL_gamepad.h
View File

@ -389,9 +389,6 @@ 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().
*
* \param count a pointer filled in with the number of mappings returned, can
* be NULL.
* \returns an array of the mapping strings, NULL-terminated, or NULL on
@ -399,14 +396,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReloadGamepadMappings(void);
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * const * SDLCALL SDL_GetGamepadMappings(int *count);
extern SDL_DECLSPEC_TEMP const char * const * SDLCALL SDL_GetGamepadMappings(int *count);
/**
* 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().
*
* \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
* information.
@ -416,14 +410,11 @@ extern SDL_DECLSPEC const char * const * SDLCALL SDL_GetGamepadMappings(int *cou
* \sa SDL_GetJoystickGUIDForID
* \sa SDL_GetJoystickGUID
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID guid);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID guid);
/**
* Get the current mapping of a gamepad.
*
* 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().
*
* \param gamepad the gamepad you want to get the current mapping for.
@ -437,7 +428,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID g
* \sa SDL_GetGamepadMappingForGUID
* \sa SDL_SetGamepadMapping
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadMapping(SDL_Gamepad *gamepad);
/**
* Set the current mapping of a joystick or gamepad.
@ -471,9 +462,6 @@ 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().
*
* \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;
@ -484,7 +472,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void);
* \sa SDL_HasGamepad
* \sa SDL_OpenGamepad
*/
extern SDL_DECLSPEC const SDL_JoystickID * SDLCALL SDL_GetGamepads(int *count);
extern SDL_DECLSPEC_TEMP const SDL_JoystickID * SDLCALL SDL_GetGamepads(int *count);
/**
* Check if the given joystick is supported by the gamepad interface.
@ -505,9 +493,6 @@ 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().
*
* \param instance_id the joystick instance ID.
* \returns the name of the selected gamepad. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information.
@ -517,16 +502,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id);
* \sa SDL_GetGamepadName
* \sa SDL_GetGamepads
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID instance_id);
/**
* Get the implementation dependent path of a gamepad.
*
* 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().
*
* \param instance_id the joystick instance ID.
* \returns the path of the selected gamepad. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information.
@ -536,7 +518,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID
* \sa SDL_GetGamepadPath
* \sa SDL_GetGamepads
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPathForID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadPathForID(SDL_JoystickID instance_id);
/**
* Get the player index of a gamepad.
@ -657,9 +639,6 @@ 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().
*
* \param instance_id the joystick instance ID.
* \returns the mapping string. Returns NULL if no mapping is available.
*
@ -668,7 +647,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys
* \sa SDL_GetGamepads
* \sa SDL_GetGamepadMapping
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadMappingForID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadMappingForID(SDL_JoystickID instance_id);
/**
* Open a gamepad for use.
@ -757,9 +736,6 @@ 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().
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad().
* \returns the implementation dependent name for the gamepad, or NULL if
@ -769,14 +745,11 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad
*
* \sa SDL_GetGamepadNameForID
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad);
extern SDL_DECLSPEC_TEMP 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().
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad().
* \returns the implementation dependent path for the gamepad, or NULL if
@ -786,7 +759,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad
*
* \sa SDL_GetGamepadPathForID
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadPath(SDL_Gamepad *gamepad);
/**
* Get the type of an opened gamepad.
@ -902,15 +875,12 @@ 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().
*
* \param gamepad the gamepad object to query.
* \returns the serial number, or NULL if unavailable.
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadSerial(SDL_Gamepad *gamepad);
/**
* Get the Steam Input handle of an opened gamepad, if available.
@ -1022,9 +992,6 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void);
/**
* Get the SDL joystick layer bindings for a gamepad.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param gamepad a gamepad.
* \param count a pointer filled in with the number of bindings returned.
* \returns a NULL terminated array of pointers to bindings or NULL on
@ -1032,7 +999,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void);
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const SDL_GamepadBinding * const * SDLCALL SDL_GetGamepadBindings(SDL_Gamepad *gamepad, int *count);
extern SDL_DECLSPEC_TEMP const SDL_GamepadBinding * const * SDLCALL SDL_GetGamepadBindings(SDL_Gamepad *gamepad, int *count);
/**
* Manually pump gamepad updates if not using the loop.
@ -1066,9 +1033,6 @@ 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().
*
* \param type an enum value for a given SDL_GamepadType.
* \returns a string for the given type, or NULL if an invalid type is
* specified. The string returned is of the format used by
@ -1078,7 +1042,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c
*
* \sa SDL_GetGamepadTypeFromString
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForType(SDL_GamepadType type);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadStringForType(SDL_GamepadType type);
/**
* Convert a string into SDL_GamepadAxis enum.
@ -1105,9 +1069,6 @@ 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().
*
* \param axis an enum value for a given SDL_GamepadAxis.
* \returns a string for the given axis, or NULL if an invalid axis is
* specified. The string returned is of the format used by
@ -1117,7 +1078,7 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c
*
* \sa SDL_GetGamepadAxisFromString
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_GamepadAxis axis);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadStringForAxis(SDL_GamepadAxis axis);
/**
* Query whether a gamepad has a given axis.
@ -1181,9 +1142,6 @@ 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().
*
* \param button an enum value for a given SDL_GamepadButton.
* \returns a string for the given button, or NULL if an invalid button is
* specified. The string returned is of the format used by
@ -1193,7 +1151,7 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con
*
* \sa SDL_GetGamepadButtonFromString
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadStringForButton(SDL_GamepadButton button);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadStringForButton(SDL_GamepadButton button);
/**
* Query whether a gamepad has a given button.
@ -1470,9 +1428,6 @@ 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().
*
* \param gamepad the gamepad to query.
* \param button a button on the gamepad.
* \returns the sfSymbolsName or NULL if the name can't be found.
@ -1481,14 +1436,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad);
*
* \sa SDL_GetGamepadAppleSFSymbolsNameForAxis
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButton(SDL_Gamepad *gamepad, SDL_GamepadButton button);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButton(SDL_Gamepad *gamepad, SDL_GamepadButton button);
/**
* 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().
*
* \param gamepad the gamepad to query.
* \param axis an axis on the gamepad.
* \returns the sfSymbolsName or NULL if the name can't be found.
@ -1497,7 +1449,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButt
*
* \sa SDL_GetGamepadAppleSFSymbolsNameForButton
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForAxis(SDL_Gamepad *gamepad, SDL_GamepadAxis axis);
/* Ends C function definitions when using C++ */

5
include/SDL3/SDL_guid.h
View File

@ -66,9 +66,6 @@ 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().
*
* \param guid the SDL_GUID you wish to convert to string.
* \returns the string representation of the GUID or NULL on failure; call
* SDL_GetError() for more information.
@ -77,7 +74,7 @@ typedef struct SDL_GUID {
*
* \sa SDL_StringToGUID
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GUIDToString(SDL_GUID guid);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GUIDToString(SDL_GUID guid);
/**
* Convert a GUID string into a SDL_GUID structure.

15
include/SDL3/SDL_haptic.h
View File

@ -931,9 +931,6 @@ 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().
*
* \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
@ -943,16 +940,13 @@ typedef Uint32 SDL_HapticID;
*
* \sa SDL_OpenHaptic
*/
extern SDL_DECLSPEC const SDL_HapticID * SDLCALL SDL_GetHaptics(int *count);
extern SDL_DECLSPEC_TEMP const SDL_HapticID * SDLCALL SDL_GetHaptics(int *count);
/**
* Get the implementation dependent name of a haptic device.
*
* 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().
*
* \param instance_id the haptic device instance ID.
* \returns the name of the selected haptic device. If no name can be found,
* this function returns NULL; call SDL_GetError() for more
@ -963,7 +957,7 @@ extern SDL_DECLSPEC const SDL_HapticID * SDLCALL SDL_GetHaptics(int *count);
* \sa SDL_GetHapticName
* \sa SDL_OpenHaptic
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticNameForID(SDL_HapticID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetHapticNameForID(SDL_HapticID instance_id);
/**
* Open a haptic device for use.
@ -1016,9 +1010,6 @@ 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().
*
* \param haptic the SDL_Haptic obtained from SDL_OpenJoystick().
* \returns the name of the selected haptic device. If no name can be found,
* this function returns NULL; call SDL_GetError() for more
@ -1028,7 +1019,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic);
*
* \sa SDL_GetHapticNameForID
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetHapticName(SDL_Haptic *haptic);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetHapticName(SDL_Haptic *haptic);
/**
* Query whether or not the current mouse has haptic capabilities.

5
include/SDL3/SDL_hints.h
View File

@ -3872,9 +3872,6 @@ 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().
*
* \param name the hint to query.
* \returns the string value of a hint or NULL if the hint isn't set.
*
@ -3883,7 +3880,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void);
* \sa SDL_SetHint
* \sa SDL_SetHintWithPriority
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetHint(const char *name);
/**
* Get the boolean value of a hint variable.

30
include/SDL3/SDL_joystick.h
View File

@ -201,9 +201,6 @@ 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().
*
* \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;
@ -214,16 +211,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void);
* \sa SDL_HasJoystick
* \sa SDL_OpenJoystick
*/
extern SDL_DECLSPEC const SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count);
extern SDL_DECLSPEC_TEMP const SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count);
/**
* Get the implementation dependent name of a joystick.
*
* 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().
*
* \param instance_id the joystick instance ID.
* \returns the name of the selected joystick. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information.
@ -233,16 +227,13 @@ extern SDL_DECLSPEC const SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count);
* \sa SDL_GetJoystickName
* \sa SDL_GetJoysticks
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID instance_id);
/**
* Get the implementation dependent path of a joystick.
*
* 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().
*
* \param instance_id the joystick instance ID.
* \returns the path of the selected joystick. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information.
@ -252,7 +243,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID
* \sa SDL_GetJoystickPath
* \sa SDL_GetJoysticks
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPathForID(SDL_JoystickID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetJoystickPathForID(SDL_JoystickID instance_id);
/**
* Get the player index of a joystick.
@ -662,9 +653,6 @@ 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().
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the name of the selected joystick. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information.
@ -673,14 +661,11 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst
*
* \sa SDL_GetJoystickNameForID
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joystick);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joystick);
/**
* 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().
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the path of the selected joystick. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information.
@ -689,7 +674,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joyst
*
* \sa SDL_GetJoystickPathForID
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPath(SDL_Joystick *joystick);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetJoystickPath(SDL_Joystick *joystick);
/**
* Get the player index of an opened joystick.
@ -798,16 +783,13 @@ 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().
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the serial number of the selected joystick, or NULL if
* unavailable.
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick);
/**
* Get the type of an opened joystick.

20
include/SDL3/SDL_keyboard.h
View File

@ -73,9 +73,6 @@ 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().
*
* \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;
@ -86,16 +83,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void);
* \sa SDL_GetKeyboardNameForID
* \sa SDL_HasKeyboard
*/
extern SDL_DECLSPEC const SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count);
extern SDL_DECLSPEC_TEMP const SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count);
/**
* Get the name of a keyboard.
*
* 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().
*
* \param instance_id the keyboard instance ID.
* \returns the name of the selected keyboard or NULL on failure; call
* SDL_GetError() for more information.
@ -104,7 +98,7 @@ extern SDL_DECLSPEC const SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count);
*
* \sa SDL_GetKeyboards
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetKeyboardNameForID(SDL_KeyboardID instance_id);
/**
* Query the window which currently has keyboard focus.
@ -284,9 +278,6 @@ 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().
*
* **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
* Windows" under Microsoft Windows, and some scancodes like
@ -306,7 +297,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const
* \sa SDL_GetScancodeFromName
* \sa SDL_SetScancodeName
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetScancodeName(SDL_Scancode scancode);
/**
* Get a scancode from a human-readable name.
@ -331,9 +322,6 @@ 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().
*
* \param key the desired SDL_Keycode to query.
* \returns a UTF-8 encoded string of the key name.
*
@ -343,7 +331,7 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam
* \sa SDL_GetKeyFromScancode
* \sa SDL_GetScancodeFromKey
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetKeyName(SDL_Keycode key);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetKeyName(SDL_Keycode key);
/**
* Get a key code from a human-readable name.

5
include/SDL3/SDL_locale.h
View File

@ -89,9 +89,6 @@ 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().
*
* \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;
@ -99,7 +96,7 @@ typedef struct SDL_Locale
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const SDL_Locale * const * SDLCALL SDL_GetPreferredLocales(int *count);
extern SDL_DECLSPEC_TEMP const SDL_Locale * const * SDLCALL SDL_GetPreferredLocales(int *count);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus

10
include/SDL3/SDL_mouse.h
View File

@ -135,9 +135,6 @@ 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().
*
* \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;
@ -148,16 +145,13 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void);
* \sa SDL_GetMouseNameForID
* \sa SDL_HasMouse
*/
extern SDL_DECLSPEC const SDL_MouseID * SDLCALL SDL_GetMice(int *count);
extern SDL_DECLSPEC_TEMP const SDL_MouseID * SDLCALL SDL_GetMice(int *count);
/**
* Get the name of a mouse.
*
* 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().
*
* \param instance_id the mouse instance ID.
* \returns the name of the selected mouse, or NULL on failure; call
* SDL_GetError() for more information.
@ -166,7 +160,7 @@ extern SDL_DECLSPEC const SDL_MouseID * SDLCALL SDL_GetMice(int *count);
*
* \sa SDL_GetMice
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetMouseNameForID(SDL_MouseID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetMouseNameForID(SDL_MouseID instance_id);
/**
* Get the window which currently has mouse focus.

5
include/SDL3/SDL_pen.h
View File

@ -224,9 +224,6 @@ 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().
*
* \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
@ -238,7 +235,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetPenName(SDL_PenID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetPenName(SDL_PenID instance_id);
/**
* Pen capabilities, as reported by SDL_GetPenCapabilities()

5
include/SDL3/SDL_properties.h
View File

@ -378,9 +378,6 @@ 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().
*
* \param props the properties to query.
* \param name the name of the property to query.
* \param default_value the default value of the property.
@ -395,7 +392,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props
* \sa SDL_HasProperty
* \sa SDL_SetStringProperty
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value);
/**
* Get a number property from a group of properties.

10
include/SDL3/SDL_render.h
View File

@ -154,9 +154,6 @@ 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().
*
* \param index the index of the rendering driver; the value ranges from 0 to
* SDL_GetNumRenderDrivers() - 1.
* \returns the name of the rendering driver at the requested index, or NULL
@ -166,7 +163,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
*
* \sa SDL_GetNumRenderDrivers
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetRenderDriver(int index);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetRenderDriver(int index);
/**
* Create a window and default renderer.
@ -325,9 +322,6 @@ 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().
*
* \param renderer the rendering context.
* \returns the name of the selected renderer, or NULL on failure; call
* SDL_GetError() for more information.
@ -337,7 +331,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *rende
* \sa SDL_CreateRenderer
* \sa SDL_CreateRendererWithProperties
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetRendererName(SDL_Renderer *renderer);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetRendererName(SDL_Renderer *renderer);
/**
* Get the properties associated with a renderer.

10
include/SDL3/SDL_sensor.h
View File

@ -160,15 +160,12 @@ 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().
*
* \param instance_id the sensor instance ID.
* \returns the sensor name, or NULL if `instance_id` is not valid.
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetSensorNameForID(SDL_SensorID instance_id);
/**
* Get the type of a sensor.
@ -232,16 +229,13 @@ 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().
*
* \param sensor the SDL_Sensor object.
* \returns the sensor name or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetSensorName(SDL_Sensor *sensor);
/**
* Get the type of a sensor.

5
include/SDL3/SDL_storage.h
View File

@ -401,9 +401,6 @@ 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().
*
* \param storage a storage container.
* \param path the path of the directory to enumerate.
* \param pattern the pattern that files in the directory must match. Can be
@ -420,7 +417,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * const * SDLCALL SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count);
extern SDL_DECLSPEC_TEMP const char * const * SDLCALL SDL_GlobStorageDirectory(SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus

20
include/SDL3/SDL_system.h
View File

@ -411,9 +411,6 @@ 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().
*
* \returns the path used for internal storage or NULL on failure; call
* SDL_GetError() for more information.
*
@ -421,7 +418,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void);
*
* \sa SDL_GetAndroidExternalStorageState
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidInternalStoragePath(void);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetAndroidInternalStoragePath(void);
/**
* Get the current state of external storage for this Android application.
@ -453,9 +450,6 @@ 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().
*
* \returns the path used for external storage for this application on success
* or NULL on failure; call SDL_GetError() for more information.
*
@ -463,7 +457,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void);
*
* \sa SDL_GetAndroidExternalStorageState
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetAndroidExternalStoragePath(void);
/**
* Get the path used for caching data for this Android application.
@ -477,15 +471,12 @@ 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().
*
* \returns the path used for caches for this application on success or NULL
* on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetAndroidCachePath(void);
typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, SDL_bool granted);
@ -632,9 +623,6 @@ 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().
*
* \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
* the path is not available for any reason; call SDL_GetError() for
@ -642,7 +630,7 @@ typedef enum SDL_WinRT_DeviceFamily
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetWinRTFSPath(SDL_WinRT_Path pathType);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetWinRTFSPath(SDL_WinRT_Path pathType);
/**
* Detects the device family of WinRT platform at runtime.

5
include/SDL3/SDL_thread.h
View File

@ -330,16 +330,13 @@ 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().
*
* \param thread the thread to query.
* \returns a pointer to a UTF-8 string that names the specified thread, or
* NULL if it doesn't have a name.
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread);
/**
* Get the thread identifier for the current thread.

15
include/SDL3/SDL_touch.h
View File

@ -83,9 +83,6 @@ 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().
*
* \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
@ -93,21 +90,18 @@ typedef struct SDL_Finger
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count);
extern SDL_DECLSPEC_TEMP 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().
*
* \param touchID the touch device instance ID.
* \returns touch device name, or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touchID);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetTouchDeviceName(SDL_TouchID touchID);
/**
* Get the type of the given touch device.
@ -122,9 +116,6 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch
/**
* Get a list of active fingers for a given touch device.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param touchID the ID of a touch device.
* \param count a pointer filled in with the number of fingers returned, can
* be NULL.
@ -133,7 +124,7 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const SDL_Finger * const * SDLCALL SDL_GetTouchFingers(SDL_TouchID touchID, int *count);
extern SDL_DECLSPEC_TEMP const SDL_Finger * const * SDLCALL SDL_GetTouchFingers(SDL_TouchID touchID, int *count);
/* Ends C function definitions when using C++ */
#ifdef __cplusplus

60
include/SDL3/SDL_video.h
View File

@ -349,9 +349,6 @@ 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().
*
* \param index the index of a video driver.
* \returns the name of the video driver with the given **index**.
*
@ -359,7 +356,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
*
* \sa SDL_GetNumVideoDrivers
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetVideoDriver(int index);
/**
* Get the name of the currently initialized video driver.
@ -368,9 +365,6 @@ 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().
*
* \returns the name of the current video driver or NULL if no driver has been
* initialized.
*
@ -379,7 +373,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index);
* \sa SDL_GetNumVideoDrivers
* \sa SDL_GetVideoDriver
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentVideoDriver(void);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetCurrentVideoDriver(void);
/**
* Get the current system theme.
@ -393,9 +387,6 @@ 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().
*
* \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;
@ -403,7 +394,7 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count);
extern SDL_DECLSPEC_TEMP const SDL_DisplayID * SDLCALL SDL_GetDisplays(int *count);
/**
* Return the primary display.
@ -449,9 +440,6 @@ 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().
*
* \param displayID the instance ID of the display to query.
* \returns the name of a display or NULL on failure; call SDL_GetError() for
* more information.
@ -460,7 +448,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa
*
* \sa SDL_GetDisplays
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displayID);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetDisplayName(SDL_DisplayID displayID);
/**
* Get the desktop area represented by a display.
@ -559,9 +547,6 @@ 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().
*
* \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.
@ -572,7 +557,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ
*
* \sa SDL_GetDisplays
*/
extern SDL_DECLSPEC const SDL_DisplayMode * const * SDLCALL SDL_GetFullscreenDisplayModes(SDL_DisplayID displayID, int *count);
extern SDL_DECLSPEC_TEMP const SDL_DisplayMode * const * SDLCALL SDL_GetFullscreenDisplayModes(SDL_DisplayID displayID, int *count);
/**
* Get the closest match to the requested display mode.
@ -584,9 +569,6 @@ extern SDL_DECLSPEC const SDL_DisplayMode * const * SDLCALL SDL_GetFullscreenDis
* and finally checking the refresh rate. If all the available modes are too
* small, then NULL is returned.
*
* 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 w the width in pixels of the desired display mode.
* \param h the height in pixels of the desired display mode.
@ -603,7 +585,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode * const * SDLCALL SDL_GetFullscreenDis
* \sa SDL_GetDisplays
* \sa SDL_GetFullscreenDisplayModes
*/
extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, SDL_bool include_high_density_modes);
extern SDL_DECLSPEC_TEMP const SDL_DisplayMode * SDLCALL SDL_GetClosestFullscreenDisplayMode(SDL_DisplayID displayID, int w, int h, float refresh_rate, SDL_bool include_high_density_modes);
/**
* Get information about the desktop's display mode.
@ -613,9 +595,6 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetClosestFullscreenDisp
* function will return the previous native display mode, and not the current
* display mode.
*
* 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 a pointer to the desktop display mode or NULL on failure; call
* SDL_GetError() for more information.
@ -625,7 +604,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetClosestFullscreenDisp
* \sa SDL_GetCurrentDisplayMode
* \sa SDL_GetDisplays
*/
extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SDL_DisplayID displayID);
extern SDL_DECLSPEC_TEMP const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SDL_DisplayID displayID);
/**
* Get information about the current display mode.
@ -635,9 +614,6 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SD
* function will return the current display mode, and not the previous native
* display mode.
*
* 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 a pointer to the desktop display mode or NULL on failure; call
* SDL_GetError() for more information.
@ -647,7 +623,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SD
* \sa SDL_GetDesktopDisplayMode
* \sa SDL_GetDisplays
*/
extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetCurrentDisplayMode(SDL_DisplayID displayID);
extern SDL_DECLSPEC_TEMP const SDL_DisplayMode * SDLCALL SDL_GetCurrentDisplayMode(SDL_DisplayID displayID);
/**
* Get the display containing a point.
@ -768,9 +744,6 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window,
/**
* Query the display mode to use when a window is visible at fullscreen.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param window the window to query.
* \returns a pointer to the exclusive fullscreen mode to use or NULL for
* borderless fullscreen desktop mode.
@ -780,14 +753,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window,
* \sa SDL_SetWindowFullscreenMode
* \sa SDL_SetWindowFullscreen
*/
extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode(SDL_Window *window);
extern SDL_DECLSPEC_TEMP const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode(SDL_Window *window);
/**
* 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().
*
* \param window the window to query.
* \param size the size of the ICC profile.
* \returns the raw ICC profile data on success or NULL on failure; call
@ -795,7 +765,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode(
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size);
extern SDL_DECLSPEC_TEMP const void * SDLCALL SDL_GetWindowICCProfile(SDL_Window *window, size_t *size);
/**
* Get the pixel format associated with the window.
@ -812,9 +782,6 @@ 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().
*
* \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;
@ -822,7 +789,7 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC SDL_Window * const * SDLCALL SDL_GetWindows(int *count);
extern SDL_DECLSPEC_TEMP SDL_Window * const * SDLCALL SDL_GetWindows(int *count);
/**
* Create a window with the specified dimensions and flags.
@ -1347,9 +1314,6 @@ 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().
*
* \param window the window to query.
* \returns the title of the window in UTF-8 format or "" if there is no
* title.
@ -1358,7 +1322,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowTitle(SDL_Window *window, const cha
*
* \sa SDL_SetWindowTitle
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetWindowTitle(SDL_Window *window);
/**
* Set the icon for a window.

1
src/dynapi/SDL_dynapi.sym
View File

@ -130,6 +130,7 @@ SDL3_0.0.0 {
SDL_FlushEvent;
SDL_FlushEvents;
SDL_FlushRenderer;
SDL_FreeTemporaryMemory;
SDL_GDKSuspendComplete;
SDL_GL_CreateContext;
SDL_GL_DestroyContext;

1
src/dynapi/SDL_dynapi_overrides.h
View File

@ -155,6 +155,7 @@
#define SDL_FlushEvent SDL_FlushEvent_REAL
#define SDL_FlushEvents SDL_FlushEvents_REAL
#define SDL_FlushRenderer SDL_FlushRenderer_REAL
#define SDL_FreeTemporaryMemory SDL_FreeTemporaryMemory_REAL
#define SDL_GDKSuspendComplete SDL_GDKSuspendComplete_REAL
#define SDL_GL_CreateContext SDL_GL_CreateContext_REAL
#define SDL_GL_DestroyContext SDL_GL_DestroyContext_REAL

1
src/dynapi/SDL_dynapi_procs.h
View File

@ -175,6 +175,7 @@ SDL_DYNAPI_PROC(int,SDL_FlushAudioStream,(SDL_AudioStream *a),(a),return)
SDL_DYNAPI_PROC(void,SDL_FlushEvent,(Uint32 a),(a),)
SDL_DYNAPI_PROC(void,SDL_FlushEvents,(Uint32 a, Uint32 b),(a,b),)
SDL_DYNAPI_PROC(int,SDL_FlushRenderer,(SDL_Renderer *a),(a),return)
SDL_DYNAPI_PROC(void,SDL_FreeTemporaryMemory,(void),(),)
SDL_DYNAPI_PROC(void,SDL_GDKSuspendComplete,(void),(),)
SDL_DYNAPI_PROC(SDL_GLContext,SDL_GL_CreateContext,(SDL_Window *a),(a),return)
SDL_DYNAPI_PROC(int,SDL_GL_DestroyContext,(SDL_GLContext a),(a),return)

1
src/dynapi/gendynapi.py
View File

@ -197,6 +197,7 @@ def main():
func_ret = func_ret.replace('extern', ' ')
func_ret = func_ret.replace('SDLCALL', ' ')
func_ret = func_ret.replace('SDL_DECLSPEC', ' ')
func_ret = func_ret.replace('SDL_DECLSPEC_TEMP', ' ')
# Remove trailing spaces in front of '*'
tmp = ""
while func_ret != tmp:

28
src/events/SDL_events.c
View File

@ -79,7 +79,6 @@ static Uint32 SDL_userevents = SDL_EVENT_USER;
typedef struct SDL_TemporaryMemory
{
void *memory;
Uint64 timestamp;
struct SDL_TemporaryMemory *prev;
struct SDL_TemporaryMemory *next;
} SDL_TemporaryMemory;
@ -111,7 +110,6 @@ static struct
SDL_EventEntry *free;
} SDL_EventQ = { NULL, SDL_FALSE, { 0 }, 0, NULL, NULL, NULL };
static void SDL_FreeTemporaryMemory(void);
static void SDL_CleanupTemporaryMemory(void *data)
{
@ -268,23 +266,6 @@ static void SDL_TransferTemporaryMemoryFromEvent(SDL_EventEntry *event)
event->memory = NULL;
}
static void SDL_CollectTemporaryMemory(SDL_TemporaryMemoryState *state, Uint64 now)
{
// Temporary memory will age out and be collected after 1 second
const int TEMPORARY_MEMORY_COLLECT_TIME_MS = 1000;
while (state->head) {
SDL_TemporaryMemory *entry = state->head;
if ((now - entry->timestamp) < TEMPORARY_MEMORY_COLLECT_TIME_MS) {
break;
}
SDL_UnlinkTemporaryMemoryEntry(state, entry);
SDL_FreeTemporaryMemoryEntry(state, entry, SDL_TRUE);
}
}
void *SDL_FreeLater(void *memory)
{
SDL_TemporaryMemoryState *state;
@ -301,16 +282,12 @@ void *SDL_FreeLater(void *memory)
return memory; // this is now a leak, but you probably have bigger problems if malloc failed.
}
Uint64 now = SDL_GetTicks();
SDL_CollectTemporaryMemory(state, now);
SDL_TemporaryMemory *entry = (SDL_TemporaryMemory *)SDL_malloc(sizeof(*entry));
if (!entry) {
return memory; // this is now a leak, but you probably have bigger problems if malloc failed. We could probably pool up and reuse entries, though.
}
entry->memory = memory;
entry->timestamp = now;
SDL_LinkTemporaryMemoryEntry(state, entry);
@ -885,8 +862,6 @@ void SDL_StopEventLoop(void)
SDL_EventQ.free = NULL;
SDL_AtomicSet(&SDL_sentinel_pending, 0);
SDL_FreeTemporaryMemory();
/* Clear disabled event state */
for (i = 0; i < SDL_arraysize(SDL_disabled_events); ++i) {
SDL_free(SDL_disabled_events[i]);
@ -1183,9 +1158,6 @@ void SDL_FlushEvents(Uint32 minType, Uint32 maxType)
/* Run the system dependent event loops */
static void SDL_PumpEventsInternal(SDL_bool push_sentinel)
{
/* Free old event memory */
SDL_FreeTemporaryMemory();
/* Release any keys held down from last frame */
SDL_ReleaseAutoReleaseKeys();

26
test/testautomation_events.c
View File

@ -233,32 +233,6 @@ static int events_temporaryMemory(void *arg)
SDL_free(claimed);
}
{
/* Create event memory and queue it */
mem = SDL_AllocateTemporaryMemory(1);
SDLTest_AssertCheck(mem != NULL, "SDL_AllocateTemporaryMemory()");
*(char *)mem = '3';
SDL_zero(event);
event.type = SDL_EVENT_USER;
event.user.data1 = mem;
SDL_PushEvent(&event);
/* Get the event and verify the memory is valid */
found = SDL_FALSE;
while (SDL_PollEvent(&event)) {
if (event.type == SDL_EVENT_USER && event.user.data1 == mem) {
found = SDL_TRUE;
}
}
SDLTest_AssertCheck(found, "SDL_PollEvent() returned queued event");
/* Verify that pumping the event loop frees event memory */
SDL_PumpEvents();
claimed = SDL_ClaimTemporaryMemory(mem);
SDLTest_AssertCheck(claimed == NULL, "SDL_ClaimTemporaryMemory() can't claim memory after pumping the event loop");
}
return TEST_COMPLETED;
}