eden-emu/SDL
20
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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
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; 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; $sym = $8;
$rettype = "$3$4$5$6"; $rettype = "$3$4$5$6";
$paramsstr = $9; $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. 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. $decl = ''; # rebuild this with the line breaks, since it looks better for syntax highlighting.
foreach (@decllines) { foreach (@decllines) {
if ($decl eq '') { if ($decl eq '') {
my $temp;
$decl = $_; $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 { } else {
my $trimmed = $_; my $trimmed = $_;
# !!! FIXME: trim space for SDL_DEPRECATED if it was used, too. $trimmed =~ s/\A\s{$shrink_length}//; # shrink to match the removed "extern SDL_DECLSPEC SDLCALL "
$trimmed =~ s/\A\s{28}//; # 28 for shrinking to match the removed "extern SDL_DECLSPEC SDLCALL "
$decl .= $trimmed; $decl .= $trimmed;
} }
$decl .= "\n"; $decl .= "\n";

1
docs/doxyfile
View file

@ -1298,6 +1298,7 @@ INCLUDE_FILE_PATTERNS =
PREDEFINED = DOXYGEN_SHOULD_IGNORE_THIS=1 \ PREDEFINED = DOXYGEN_SHOULD_IGNORE_THIS=1 \
SDL_DECLSPEC= \ SDL_DECLSPEC= \
SDL_DECLSPEC_TEMP= \
SDLCALL= \ SDLCALL= \
_WIN32=1 _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 * "coreaudio" or "wasapi". These never have Unicode characters, and are not
* meant to be proper names. * 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 * \param index the index of the audio driver; the value ranges from 0 to
* SDL_GetNumAudioDrivers() - 1. * SDL_GetNumAudioDrivers() - 1.
* \returns the name of the audio driver at the requested index, or NULL if an * \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 * \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 * "coreaudio" or "wasapi". These never have Unicode characters, and are not
* meant to be proper names. * 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 * \returns the name of the current audio driver or NULL if no driver has been
* initialized. * 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. * \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. * 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 * If this function returns NULL, to signify an error, `*count` will be set to
* zero. * 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 * \param count a pointer filled in with the number of devices returned, may
* be NULL. * be NULL.
* \returns a 0 terminated array of device instance IDs or NULL on error; call * \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_OpenAudioDevice
* \sa SDL_GetAudioRecordingDevices * \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. * 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 * If this function returns NULL, to signify an error, `*count` will be set to
* zero. * 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 * \param count a pointer filled in with the number of devices returned, may
* be NULL. * be NULL.
* \returns a 0 terminated array of device instance IDs, or NULL on failure; * \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_OpenAudioDevice
* \sa SDL_GetAudioPlaybackDevices * \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. * 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. * \param devid the instance ID of the device to query.
* \returns the name of the audio device, or NULL on failure; call * \returns the name of the audio device, or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@ -516,7 +501,7 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevic
* \sa SDL_GetAudioRecordingDevices * \sa SDL_GetAudioRecordingDevices
* \sa SDL_GetDefaultAudioInfo * \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. * 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 * Audio devices usually have no remapping applied. This is represented by
* returning NULL, and does not signify an error. * 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 devid the instance ID of the device to query.
* \param count On output, set to number of channels in the map. Can be NULL. * \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 * \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 * \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. * 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 * Audio streams default to no remapping applied. This is represented by
* returning NULL, and does not signify an error. * 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 stream the SDL_AudioStream to query.
* \param count On output, set to number of channels in the map. Can be NULL. * \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 * \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 * \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. * 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 * Audio streams default to no remapping applied. This is represented by
* returning NULL, and does not signify an error. * 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 stream the SDL_AudioStream to query.
* \param count On output, set to number of channels in the map. Can be NULL. * \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 * \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 * \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. * 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 # 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 */ /* By default SDL uses the C calling convention */
#ifndef SDLCALL #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 * "coremedia" or "android". These never have Unicode characters, and are not
* meant to be proper names. * 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 * \param index the index of the camera driver; the value ranges from 0 to
* SDL_GetNumCameraDrivers() - 1. * SDL_GetNumCameraDrivers() - 1.
* \returns the name of the camera driver at the requested index, or NULL if * \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 * \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. * 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 * "coremedia" or "android". These never have Unicode characters, and are not
* meant to be proper names. * 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 * \returns the name of the current camera driver or NULL if no driver has
* been initialized. * 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. * \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. * 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 * \param count a pointer filled in with the number of cameras returned, may
* be NULL. * be NULL.
* \returns a 0 terminated array of camera instance IDs or NULL on failure; * \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 * \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. * 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 * there _is_ a camera until the user has given you permission to check
* through a scary warning popup. * 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 devid the camera device instance ID to query.
* \param count a pointer filled in with the number of elements in the list, * \param count a pointer filled in with the number of elements in the list,
* may be NULL. * may be NULL.
@ -226,14 +214,11 @@ extern SDL_DECLSPEC const SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
* \sa SDL_GetCameras * \sa SDL_GetCameras
* \sa SDL_OpenCamera * \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. * 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. * \param instance_id the camera device instance ID.
* \returns a human-readable device name or NULL on failure; call * \returns a human-readable device name or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@ -244,7 +229,7 @@ extern SDL_DECLSPEC const SDL_CameraSpec * const * SDLCALL SDL_GetCameraSupporte
* *
* \sa SDL_GetCameras * \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. * 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 * This functions returns empty string if there was not enough memory left for
* a copy of the clipboard's content. * 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 * \returns the clipboard text on success or an empty string on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@ -73,7 +70,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
* \sa SDL_HasClipboardText * \sa SDL_HasClipboardText
* \sa SDL_SetClipboardText * \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. * 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 * This functions returns empty string if there was not enough memory left for
* a copy of the primary selection's content. * 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 * \returns the primary selection text on success or an empty string on
* failure; call SDL_GetError() for more information. * 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_HasPrimarySelectionText
* \sa SDL_SetPrimarySelectionText * \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 * 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() * \returns the retrieved data buffer or NULL on failure; call SDL_GetError()
* for more information. * 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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_HasClipboardData * \sa SDL_HasClipboardData
* \sa SDL_SetClipboardData * \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. * 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 * will be inserted into the editing text. The length is the number of UTF-8
* characters that will be replaced by new typing. * characters that will be replaced by new typing.
* *
* The text string is temporary memory which will be automatically freed * The text string is temporary memory which will be freed in SDL_FreeTemporaryMemory() and can be claimed with SDL_ClaimTemporaryMemory().
* later, and can be claimed with SDL_ClaimTemporaryMemory().
* *
* \since This struct is available since SDL 3.0.0. * \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.*) * Keyboard IME candidates event structure (event.edit_candidates.*)
* *
* The candidates are temporary memory which will be automatically freed * The candidates are a single allocation of temporary memory which will be freed in SDL_FreeTemporaryMemory() and can be claimed with SDL_ClaimTemporaryMemory().
* later, and can be claimed with SDL_ClaimTemporaryMemory().
* *
* \since This struct is available since SDL 3.0.0. * \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.*) * Keyboard text input event structure (event.text.*)
* *
* The text string is temporary memory which will be automatically freed * The text string is temporary memory which will be freed in SDL_FreeTemporaryMemory() and can be claimed with SDL_ClaimTemporaryMemory().
* later, and can be claimed with SDL_ClaimTemporaryMemory().
* *
* This event will never be delivered unless text input is enabled by calling * This event will never be delivered unless text input is enabled by calling
* SDL_StartTextInput(). Text input is disabled by default! * 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 * An event used to drop text or request a file open by the system
* (event.drop.*) * (event.drop.*)
* *
* The source and data strings are temporary memory which will be * The source and data strings are temporary memory which will be freed in SDL_FreeTemporaryMemory() and can be claimed with SDL_ClaimTemporaryMemory().
* automatically freed later, and can be claimed with
* SDL_ClaimTemporaryMemory().
* *
* \since This struct is available since SDL 3.0.0. * \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 * the programmer; the only requirement is that '''type''' is a value obtained
* from SDL_RegisterEvents(). * 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. * \since This struct is available since SDL 3.0.0.
*/ */
typedef struct SDL_UserEvent typedef struct SDL_UserEvent
@ -1416,8 +1413,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
/** /**
* Allocate temporary memory. * Allocate temporary memory.
* *
* You can use this to allocate memory that will be automatically freed later, * You can use this to allocate memory from the temporary memory pool for the current thread.
* after event processing is complete.
* *
* \param size the amount of memory to allocate. * \param size the amount of memory to allocate.
* \returns a pointer to the memory allocated or NULL on failure; call * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_ClaimTemporaryMemory * \sa SDL_ClaimTemporaryMemory
* \sa SDL_FreeTemporaryMemory
*/ */
extern SDL_DECLSPEC void * SDLCALL SDL_AllocateTemporaryMemory(size_t size); extern SDL_DECLSPEC void * SDLCALL SDL_AllocateTemporaryMemory(size_t size);
/** /**
* Claim ownership of temporary memory. * Claim ownership of temporary memory.
* *
* Some functions return temporary memory which SDL will automatically clean * 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.
* 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.
* *
* \param mem a pointer allocated with SDL_AllocateTemporaryMemory(). * \param mem a pointer allocated with SDL_AllocateTemporaryMemory().
* \returns a pointer to the memory now owned by the application, which must * \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 * be freed using SDL_free(), or NULL if the memory is not in the temporary memory pool for the current thread.
* or is not owned by this thread.
* *
* \threadsafety It is safe to call this function from any 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); 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++ */ /* Ends C function definitions when using C++ */
#ifdef __cplusplus #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 * The returned path is guaranteed to end with a path separator ('\\' on
* Windows, '/' on most other platforms). * 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 * \returns an absolute path in UTF-8 encoding to the application data
* directory. NULL will be returned on error or when the platform * directory. NULL will be returned on error or when the platform
* doesn't implement this functionality, call SDL_GetError() for more * doesn't implement this functionality, call SDL_GetError() for more
@ -80,7 +77,7 @@ extern "C" {
* *
* \sa SDL_GetPrefPath * \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. * 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 * The returned path is guaranteed to end with a path separator ('\\' on
* Windows, '/' on most other platforms). * 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 org the name of your organization.
* \param app the name of your application. * \param app the name of your application.
* \returns a UTF-8 string of the user directory in platform-dependent * \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 * \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. * 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 * The returned path is guaranteed to end with a path separator ('\\' on
* Windows, '/' on most other platforms). * 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(). * If NULL is returned, the error may be obtained with SDL_GetError().
* *
* \param folder the type of folder to find. * \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. * \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 */ /* 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 * convenience, but if `count` is non-NULL, on return it will contain the
* number of items in the array, not counting the NULL terminator. * 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 path the path of the directory to enumerate.
* \param pattern the pattern that files in the directory must match. Can be * \param pattern the pattern that files in the directory must match. Can be
* NULL. * 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. * \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++ */ /* Ends C function definitions when using C++ */
#ifdef __cplusplus #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. * 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 * \param count a pointer filled in with the number of mappings returned, can
* be NULL. * be NULL.
* \returns an array of the mapping strings, NULL-terminated, or NULL on * \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. * \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. * 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. * \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 * \returns a mapping string or NULL on failure; call SDL_GetError() for more
* information. * information.
@ -416,14 +410,11 @@ extern SDL_DECLSPEC const char * const * SDLCALL SDL_GetGamepadMappings(int *cou
* \sa SDL_GetJoystickGUIDForID * \sa SDL_GetJoystickGUIDForID
* \sa SDL_GetJoystickGUID * \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. * 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(). * Details about mappings are discussed with SDL_AddGamepadMapping().
* *
* \param gamepad the gamepad you want to get the current mapping for. * \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_GetGamepadMappingForGUID
* \sa SDL_SetGamepadMapping * \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. * 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. * 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 * \param count a pointer filled in with the number of gamepads returned, may
* be NULL. * be NULL.
* \returns a 0 terminated array of joystick instance IDs or NULL on failure; * \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_HasGamepad
* \sa SDL_OpenGamepad * \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. * 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 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. * \param instance_id the joystick instance ID.
* \returns the name of the selected gamepad. If no name can be found, this * \returns the name of the selected gamepad. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information. * 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_GetGamepadName
* \sa SDL_GetGamepads * \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. * Get the implementation dependent path of a gamepad.
* *
* This can be called before any gamepads are opened. * 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. * \param instance_id the joystick instance ID.
* \returns the path of the selected gamepad. If no path can be found, this * \returns the path of the selected gamepad. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information. * 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_GetGamepadPath
* \sa SDL_GetGamepads * \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. * 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 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. * \param instance_id the joystick instance ID.
* \returns the mapping string. Returns NULL if no mapping is available. * \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_GetGamepads
* \sa SDL_GetGamepadMapping * \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. * 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. * 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 * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad(). * SDL_OpenGamepad().
* \returns the implementation dependent name for the gamepad, or NULL if * \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 * \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. * 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 * \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad(). * SDL_OpenGamepad().
* \returns the implementation dependent path for the gamepad, or NULL if * \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 * \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. * 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. * 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. * \param gamepad the gamepad object to query.
* \returns the serial number, or NULL if unavailable. * \returns the serial number, or NULL if unavailable.
* *
* \since This function is available since SDL 3.0.0. * \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. * 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. * 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 gamepad a gamepad.
* \param count a pointer filled in with the number of bindings returned. * \param count a pointer filled in with the number of bindings returned.
* \returns a NULL terminated array of pointers to bindings or NULL on * \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. * \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. * 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. * 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. * \param type an enum value for a given SDL_GamepadType.
* \returns a string for the given type, or NULL if an invalid type is * \returns a string for the given type, or NULL if an invalid type is
* specified. The string returned is of the format used by * 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 * \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. * 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. * 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. * \param axis an enum value for a given SDL_GamepadAxis.
* \returns a string for the given axis, or NULL if an invalid axis is * \returns a string for the given axis, or NULL if an invalid axis is
* specified. The string returned is of the format used by * 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 * \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. * 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. * 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. * \param button an enum value for a given SDL_GamepadButton.
* \returns a string for the given button, or NULL if an invalid button is * \returns a string for the given button, or NULL if an invalid button is
* specified. The string returned is of the format used by * 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 * \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. * 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 * Return the sfSymbolsName for a given button on a gamepad on Apple
* platforms. * 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 gamepad the gamepad to query.
* \param button a button on the gamepad. * \param button a button on the gamepad.
* \returns the sfSymbolsName or NULL if the name can't be found. * \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 * \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. * 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 gamepad the gamepad to query.
* \param axis an axis on the gamepad. * \param axis an axis on the gamepad.
* \returns the sfSymbolsName or NULL if the name can't be found. * \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 * \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++ */ /* 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. * 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. * \param guid the SDL_GUID you wish to convert to string.
* \returns the string representation of the GUID or NULL on failure; call * \returns the string representation of the GUID or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@ -77,7 +74,7 @@ typedef struct SDL_GUID {
* *
* \sa SDL_StringToGUID * \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. * 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. * 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 * \param count a pointer filled in with the number of haptic devices
* returned, may be NULL. * returned, may be NULL.
* \returns a 0 terminated array of haptic device instance IDs or NULL on * \returns a 0 terminated array of haptic device instance IDs or NULL on
@ -943,16 +940,13 @@ typedef Uint32 SDL_HapticID;
* *
* \sa SDL_OpenHaptic * \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. * Get the implementation dependent name of a haptic device.
* *
* This can be called before any haptic devices are opened. * 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. * \param instance_id the haptic device instance ID.
* \returns the name of the selected haptic device. If no name can be found, * \returns the name of the selected haptic device. If no name can be found,
* this function returns NULL; call SDL_GetError() for more * 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_GetHapticName
* \sa SDL_OpenHaptic * \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. * 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. * 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(). * \param haptic the SDL_Haptic obtained from SDL_OpenJoystick().
* \returns the name of the selected haptic device. If no name can be found, * \returns the name of the selected haptic device. If no name can be found,
* this function returns NULL; call SDL_GetError() for more * 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 * \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. * 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. * 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. * \param name the hint to query.
* \returns the string value of a hint or NULL if the hint isn't set. * \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_SetHint
* \sa SDL_SetHintWithPriority * \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. * 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. * 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 * \param count a pointer filled in with the number of joysticks returned, may
* be NULL. * be NULL.
* \returns a 0 terminated array of joystick instance IDs or NULL on failure; * \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_HasJoystick
* \sa SDL_OpenJoystick * \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. * Get the implementation dependent name of a joystick.
* *
* This can be called before any joysticks are opened. * 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. * \param instance_id the joystick instance ID.
* \returns the name of the selected joystick. If no name can be found, this * \returns the name of the selected joystick. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information. * 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_GetJoystickName
* \sa SDL_GetJoysticks * \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. * Get the implementation dependent path of a joystick.
* *
* This can be called before any joysticks are opened. * 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. * \param instance_id the joystick instance ID.
* \returns the path of the selected joystick. If no path can be found, this * \returns the path of the selected joystick. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information. * 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_GetJoystickPath
* \sa SDL_GetJoysticks * \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. * 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. * 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(). * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the name of the selected joystick. If no name can be found, this * \returns the name of the selected joystick. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information. * 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 * \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. * 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(). * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the path of the selected joystick. If no path can be found, this * \returns the path of the selected joystick. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information. * 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 * \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. * 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. * 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(). * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the serial number of the selected joystick, or NULL if * \returns the serial number of the selected joystick, or NULL if
* unavailable. * unavailable.
* *
* \since This function is available since SDL 3.0.0. * \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. * 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 * power buttons, etc. You should wait for input from a device before you
* consider it actively in use. * 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 * \param count a pointer filled in with the number of keyboards returned, may
* be NULL. * be NULL.
* \returns a 0 terminated array of keyboards instance IDs or NULL on failure; * \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_GetKeyboardNameForID
* \sa SDL_HasKeyboard * \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. * Get the name of a keyboard.
* *
* This function returns "" if the keyboard doesn't have a name. * 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. * \param instance_id the keyboard instance ID.
* \returns the name of the selected keyboard or NULL on failure; call * \returns the name of the selected keyboard or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@ -104,7 +98,7 @@ extern SDL_DECLSPEC const SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count);
* *
* \sa SDL_GetKeyboards * \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. * 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. * 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, * **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 * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left
* Windows" under Microsoft Windows, and some scancodes like * 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_GetScancodeFromName
* \sa SDL_SetScancodeName * \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. * 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 (""). * 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. * \param key the desired SDL_Keycode to query.
* \returns a UTF-8 encoded string of the key name. * \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_GetKeyFromScancode
* \sa SDL_GetScancodeFromKey * \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. * 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 * if possible, and you can call this function again to get an updated copy of
* preferred locales. * 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 * \param count a pointer filled in with the number of locales returned, may
* be NULL. * be NULL.
* \returns a NULL terminated array of locale pointers, or NULL on failure; * \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. * \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++ */ /* Ends C function definitions when using C++ */
#ifdef __cplusplus #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 * You should wait for input from a device before you consider it actively in
* use. * 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 * \param count a pointer filled in with the number of mice returned, may be
* NULL. * NULL.
* \returns a 0 terminated array of mouse instance IDs or NULL on failure; * \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_GetMouseNameForID
* \sa SDL_HasMouse * \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. * Get the name of a mouse.
* *
* This function returns "" if the mouse doesn't have a name. * 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. * \param instance_id the mouse instance ID.
* \returns the name of the selected mouse, or NULL on failure; call * \returns the name of the selected mouse, or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@ -166,7 +160,7 @@ extern SDL_DECLSPEC const SDL_MouseID * SDLCALL SDL_GetMice(int *count);
* *
* \sa SDL_GetMice * \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. * 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. * 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. * \param instance_id the pen to query.
* \returns a string that contains the name of the pen, intended for human * \returns a string that contains the name of the pen, intended for human
* consumption. The string might or might not be localised, depending * 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. * \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() * 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. * 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 props the properties to query.
* \param name the name of the property to query. * \param name the name of the property to query.
* \param default_value the default value of the property. * \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_HasProperty
* \sa SDL_SetStringProperty * \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. * 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 * "direct3d12" or "metal". These never have Unicode characters, and are not
* meant to be proper names. * 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 * \param index the index of the rendering driver; the value ranges from 0 to
* SDL_GetNumRenderDrivers() - 1. * SDL_GetNumRenderDrivers() - 1.
* \returns the name of the rendering driver at the requested index, or NULL * \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 * \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. * 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. * 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. * \param renderer the rendering context.
* \returns the name of the selected renderer, or NULL on failure; call * \returns the name of the selected renderer, or NULL on failure; call
* SDL_GetError() for more information. * 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_CreateRenderer
* \sa SDL_CreateRendererWithProperties * \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. * 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 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. * \param instance_id the sensor instance ID.
* \returns the sensor name, or NULL if `instance_id` is not valid. * \returns the sensor name, or NULL if `instance_id` is not valid.
* *
* \since This function is available since SDL 3.0.0. * \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. * 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. * 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. * \param sensor the SDL_Sensor object.
* \returns the sensor name or NULL on failure; call SDL_GetError() for more * \returns the sensor name or NULL on failure; call SDL_GetError() for more
* information. * information.
* *
* \since This function is available since SDL 3.0.0. * \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. * 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 * convenience, but if `count` is non-NULL, on return it will contain the
* number of items in the array, not counting the NULL terminator. * 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 storage a storage container.
* \param path the path of the directory to enumerate. * \param path the path of the directory to enumerate.
* \param pattern the pattern that files in the directory must match. Can be * \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. * \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++ */ /* Ends C function definitions when using C++ */
#ifdef __cplusplus #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() * 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 * \returns the path used for internal storage or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
@ -421,7 +418,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void);
* *
* \sa SDL_GetAndroidExternalStorageState * \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. * 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() * 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 * \returns the path used for external storage for this application on success
* or NULL on failure; call SDL_GetError() for more information. * 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 * \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. * 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() * 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 * \returns the path used for caches for this application on success or NULL
* on failure; call SDL_GetError() for more information. * on failure; call SDL_GetError() for more information.
* *
* \since This function is available since SDL 3.0.0. * \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); 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 * 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. * \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 * \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 * 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. * \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. * 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(). * 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. * \param thread the thread to query.
* \returns a pointer to a UTF-8 string that names the specified thread, or * \returns a pointer to a UTF-8 string that names the specified thread, or
* NULL if it doesn't have a name. * NULL if it doesn't have a name.
* *
* \since This function is available since SDL 3.0.0. * \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. * 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. * Therefore the returned list might be empty, although devices are available.
* After using all devices at least once the number will be correct. * 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 * \param count a pointer filled in with the number of devices returned, may
* be NULL. * be NULL.
* \returns a 0 terminated array of touch device IDs or NULL on failure; call * \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. * \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. * 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. * \param touchID the touch device instance ID.
* \returns touch device name, or NULL on failure; call SDL_GetError() for * \returns touch device name, or NULL on failure; call SDL_GetError() for
* more information. * more information.
* *
* \since This function is available since SDL 3.0.0. * \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. * 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. * 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 touchID the ID of a touch device.
* \param count a pointer filled in with the number of fingers returned, can * \param count a pointer filled in with the number of fingers returned, can
* be NULL. * 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. * \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++ */ /* Ends C function definitions when using C++ */
#ifdef __cplusplus #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 * "x11" or "windows". These never have Unicode characters, and are not meant
* to be proper names. * 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. * \param index the index of a video driver.
* \returns the name of the video driver with the given **index**. * \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 * \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. * 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 * "x11" or "windows". These never have Unicode characters, and are not meant
* to be proper names. * 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 * \returns the name of the current video driver or NULL if no driver has been
* initialized. * initialized.
* *
@ -379,7 +373,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index);
* \sa SDL_GetNumVideoDrivers * \sa SDL_GetNumVideoDrivers
* \sa SDL_GetVideoDriver * \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. * 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. * 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 * \param count a pointer filled in with the number of displays returned, may
* be NULL. * be NULL.
* \returns a 0 terminated array of display instance IDs or NULL on failure; * \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. * \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. * 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. * 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. * \param displayID the instance ID of the display to query.
* \returns the name of a display or NULL on failure; call SDL_GetError() for * \returns the name of a display or NULL on failure; call SDL_GetError() for
* more information. * more information.
@ -460,7 +448,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa
* *
* \sa SDL_GetDisplays * \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. * 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 * - refresh rate -> highest to lowest
* - pixel density -> lowest to highest * - 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 displayID the instance ID of the display to query.
* \param count a pointer filled in with the number of display modes returned, * \param count a pointer filled in with the number of display modes returned,
* may be NULL. * may be NULL.
@ -572,7 +557,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ
* *
* \sa SDL_GetDisplays * \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. * 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 * and finally checking the refresh rate. If all the available modes are too
* small, then NULL is returned. * 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 displayID the instance ID of the display to query.
* \param w the width in pixels of the desired display mode. * \param w the width in pixels of the desired display mode.
* \param h the height 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_GetDisplays
* \sa SDL_GetFullscreenDisplayModes * \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. * 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 * function will return the previous native display mode, and not the current
* display mode. * 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. * \param displayID the instance ID of the display to query.
* \returns a pointer to the desktop display mode or NULL on failure; call * \returns a pointer to the desktop display mode or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@ -625,7 +604,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetClosestFullscreenDisp
* \sa SDL_GetCurrentDisplayMode * \sa SDL_GetCurrentDisplayMode
* \sa SDL_GetDisplays * \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. * 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 * function will return the current display mode, and not the previous native
* display mode. * 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. * \param displayID the instance ID of the display to query.
* \returns a pointer to the desktop display mode or NULL on failure; call * \returns a pointer to the desktop display mode or NULL on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
@ -647,7 +623,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetDesktopDisplayMode(SD
* \sa SDL_GetDesktopDisplayMode * \sa SDL_GetDesktopDisplayMode
* \sa SDL_GetDisplays * \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. * 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. * 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. * \param window the window to query.
* \returns a pointer to the exclusive fullscreen mode to use or NULL for * \returns a pointer to the exclusive fullscreen mode to use or NULL for
* borderless fullscreen desktop mode. * borderless fullscreen desktop mode.
@ -780,14 +753,11 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowFullscreenMode(SDL_Window *window,
* \sa SDL_SetWindowFullscreenMode * \sa SDL_SetWindowFullscreenMode
* \sa SDL_SetWindowFullscreen * \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. * 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 window the window to query.
* \param size the size of the ICC profile. * \param size the size of the ICC profile.
* \returns the raw ICC profile data on success or NULL on failure; call * \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. * \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. * 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. * 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 * \param count a pointer filled in with the number of windows returned, may
* be NULL. * be NULL.
* \returns a NULL terminated array of SDL_Window pointers or NULL on failure; * \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. * \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. * 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. * 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. * \param window the window to query.
* \returns the title of the window in UTF-8 format or "" if there is no * \returns the title of the window in UTF-8 format or "" if there is no
* title. * title.
@ -1358,7 +1322,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowTitle(SDL_Window *window, const cha
* *
* \sa SDL_SetWindowTitle * \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. * 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_FlushEvent;
SDL_FlushEvents; SDL_FlushEvents;
SDL_FlushRenderer; SDL_FlushRenderer;
SDL_FreeTemporaryMemory;
SDL_GDKSuspendComplete; SDL_GDKSuspendComplete;
SDL_GL_CreateContext; SDL_GL_CreateContext;
SDL_GL_DestroyContext; SDL_GL_DestroyContext;

1
src/dynapi/SDL_dynapi_overrides.h
View file

@ -155,6 +155,7 @@
#define SDL_FlushEvent SDL_FlushEvent_REAL #define SDL_FlushEvent SDL_FlushEvent_REAL
#define SDL_FlushEvents SDL_FlushEvents_REAL #define SDL_FlushEvents SDL_FlushEvents_REAL
#define SDL_FlushRenderer SDL_FlushRenderer_REAL #define SDL_FlushRenderer SDL_FlushRenderer_REAL
#define SDL_FreeTemporaryMemory SDL_FreeTemporaryMemory_REAL
#define SDL_GDKSuspendComplete SDL_GDKSuspendComplete_REAL #define SDL_GDKSuspendComplete SDL_GDKSuspendComplete_REAL
#define SDL_GL_CreateContext SDL_GL_CreateContext_REAL #define SDL_GL_CreateContext SDL_GL_CreateContext_REAL
#define SDL_GL_DestroyContext SDL_GL_DestroyContext_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_FlushEvent,(Uint32 a),(a),)
SDL_DYNAPI_PROC(void,SDL_FlushEvents,(Uint32 a, Uint32 b),(a,b),) 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(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(void,SDL_GDKSuspendComplete,(void),(),)
SDL_DYNAPI_PROC(SDL_GLContext,SDL_GL_CreateContext,(SDL_Window *a),(a),return) 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) 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('extern', ' ')
func_ret = func_ret.replace('SDLCALL', ' ') func_ret = func_ret.replace('SDLCALL', ' ')
func_ret = func_ret.replace('SDL_DECLSPEC', ' ') func_ret = func_ret.replace('SDL_DECLSPEC', ' ')
func_ret = func_ret.replace('SDL_DECLSPEC_TEMP', ' ')
# Remove trailing spaces in front of '*' # Remove trailing spaces in front of '*'
tmp = "" tmp = ""
while func_ret != 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 typedef struct SDL_TemporaryMemory
{ {
void *memory; void *memory;
Uint64 timestamp;
struct SDL_TemporaryMemory *prev; struct SDL_TemporaryMemory *prev;
struct SDL_TemporaryMemory *next; struct SDL_TemporaryMemory *next;
} SDL_TemporaryMemory; } SDL_TemporaryMemory;
@ -111,7 +110,6 @@ static struct
SDL_EventEntry *free; SDL_EventEntry *free;
} SDL_EventQ = { NULL, SDL_FALSE, { 0 }, 0, NULL, NULL, NULL }; } SDL_EventQ = { NULL, SDL_FALSE, { 0 }, 0, NULL, NULL, NULL };
static void SDL_FreeTemporaryMemory(void);
static void SDL_CleanupTemporaryMemory(void *data) static void SDL_CleanupTemporaryMemory(void *data)
{ {
@ -268,23 +266,6 @@ static void SDL_TransferTemporaryMemoryFromEvent(SDL_EventEntry *event)
event->memory = NULL; 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) void *SDL_FreeLater(void *memory)
{ {
SDL_TemporaryMemoryState *state; 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. 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)); SDL_TemporaryMemory *entry = (SDL_TemporaryMemory *)SDL_malloc(sizeof(*entry));
if (!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. 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->memory = memory;
entry->timestamp = now;
SDL_LinkTemporaryMemoryEntry(state, entry); SDL_LinkTemporaryMemoryEntry(state, entry);
@ -885,8 +862,6 @@ void SDL_StopEventLoop(void)
SDL_EventQ.free = NULL; SDL_EventQ.free = NULL;
SDL_AtomicSet(&SDL_sentinel_pending, 0); SDL_AtomicSet(&SDL_sentinel_pending, 0);
SDL_FreeTemporaryMemory();
/* Clear disabled event state */ /* Clear disabled event state */
for (i = 0; i < SDL_arraysize(SDL_disabled_events); ++i) { for (i = 0; i < SDL_arraysize(SDL_disabled_events); ++i) {
SDL_free(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 */ /* Run the system dependent event loops */
static void SDL_PumpEventsInternal(SDL_bool push_sentinel) static void SDL_PumpEventsInternal(SDL_bool push_sentinel)
{ {
/* Free old event memory */
SDL_FreeTemporaryMemory();
/* Release any keys held down from last frame */ /* Release any keys held down from last frame */
SDL_ReleaseAutoReleaseKeys(); SDL_ReleaseAutoReleaseKeys();

26
test/testautomation_events.c
View file

@ -233,32 +233,6 @@ static int events_temporaryMemory(void *arg)
SDL_free(claimed); 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; return TEST_COMPLETED;
} }