Skip to content

Commit

Permalink
Don't automatically free temporary memory, let the application call S…
Browse files Browse the repository at this point in the history 
…DL_FreeTemporaryMemory() when it's ready.

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

Fixes libsdl-org#10378
  • Loading branch information
@slouken
slouken committed Jul 26, 2024
1 parent a1a8278 commit f745c46
Show file tree
Hide file tree
Showing 31 changed files with 120 additions and 401 deletions.
9 changes: 6 additions & 3 deletions build-scripts/wikiheaders.pl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1001,14 +1001,17 @@ sub sanitize_c_typename {

if (!$is_forced_inline) { # don't do with forced-inline because we don't want the implementation inserted in the wiki.
$decl = ''; # rebuild this with the line breaks, since it looks better for syntax highlighting.
$shrink_length = 0;
foreach (@decllines) {
if ($decl eq '') {
$decl = $_;
$decl =~ s/\Aextern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\s+(.*?)\s+(\*?)SDLCALL\s+/$3$4 /;
$temp = $decl;
$temp =~ s/\Aextern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\w*\s+(.*?)\s+(\*?)SDLCALL\s+/$3$4 /;
$shrink_length = length($decl) - length($temp);
$decl = $temp;
} else {
my $trimmed = $_;
# !!! FIXME: trim space for SDL_DEPRECATED if it was used, too.
$trimmed =~ s/\A\s{28}//; # 28 for shrinking to match the removed "extern SDL_DECLSPEC SDLCALL "
$trimmed =~ s/\A\s{$shrink_length}//; # shrink to match the removed "extern SDL_DECLSPEC SDLCALL "
$decl .= $trimmed;
}
$decl .= "\n";
Expand Down
1 change: 1 addition & 0 deletions docs/doxyfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1298,6 +1298,7 @@ INCLUDE_FILE_PATTERNS =

PREDEFINED = DOXYGEN_SHOULD_IGNORE_THIS=1 \
SDL_DECLSPEC= \
SDL_DECLSPEC_TEMP= \
SDLCALL= \
_WIN32=1

Expand Down
40 changes: 8 additions & 32 deletions include/SDL3/SDL_audio.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -400,9 +400,6 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
* "coreaudio" or "wasapi". These never have Unicode characters, and are not
* meant to be proper names.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param index the index of the audio driver; the value ranges from 0 to
* SDL_GetNumAudioDrivers() - 1.
* \returns the name of the audio driver at the requested index, or NULL if an
Expand All @@ -414,7 +411,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
*
* \sa SDL_GetNumAudioDrivers
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetAudioDriver(int index);
/* @} */

/**
Expand All @@ -424,17 +421,14 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index);
* "coreaudio" or "wasapi". These never have Unicode characters, and are not
* meant to be proper names.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the name of the current audio driver or NULL if no driver has been
* initialized.
*
* \threadsafety It is safe to call this function from any thread.
*
* \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.
Expand All @@ -450,9 +444,6 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void);
* If this function returns NULL, to signify an error, `*count` will be set to
* zero.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of devices returned, may
* be NULL.
* \returns a 0 terminated array of device instance IDs or NULL on error; call
Expand All @@ -465,7 +456,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void);
* \sa SDL_OpenAudioDevice
* \sa SDL_GetAudioRecordingDevices
*/
extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int *count);
extern SDL_DECLSPEC_TEMP const SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int *count);

/**
* Get a list of currently-connected audio recording devices.
Expand All @@ -481,9 +472,6 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevice
* If this function returns NULL, to signify an error, `*count` will be set to
* zero.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of devices returned, may
* be NULL.
* \returns a 0 terminated array of device instance IDs, or NULL on failure;
Expand All @@ -496,14 +484,11 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevice
* \sa SDL_OpenAudioDevice
* \sa SDL_GetAudioPlaybackDevices
*/
extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int *count);
extern SDL_DECLSPEC_TEMP const SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int *count);

/**
* Get the human-readable name of a specific audio device.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param devid the instance ID of the device to query.
* \returns the name of the audio device, or NULL on failure; call
* SDL_GetError() for more information.
Expand All @@ -516,7 +501,7 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevic
* \sa SDL_GetAudioRecordingDevices
* \sa SDL_GetDefaultAudioInfo
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);

/**
* Get the current audio format of a specific audio device.
Expand Down Expand Up @@ -562,9 +547,6 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid
* Audio devices usually have no remapping applied. This is represented by
* returning NULL, and does not signify an error.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param devid the instance ID of the device to query.
* \param count On output, set to number of channels in the map. Can be NULL.
* \returns an array of the current channel mapping, with as many elements as
Expand All @@ -576,7 +558,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid
*
* \sa SDL_SetAudioStreamInputChannelMap
*/
extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID devid, int *count);
extern SDL_DECLSPEC_TEMP const int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID devid, int *count);

/**
* Open a specific audio device.
Expand Down Expand Up @@ -1113,9 +1095,6 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream,
* Audio streams default to no remapping applied. This is represented by
* returning NULL, and does not signify an error.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param stream the SDL_AudioStream to query.
* \param count On output, set to number of channels in the map. Can be NULL.
* \returns an array of the current channel mapping, with as many elements as
Expand All @@ -1128,7 +1107,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream,
*
* \sa SDL_SetAudioStreamInputChannelMap
*/
extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStream *stream, int *count);
extern SDL_DECLSPEC_TEMP const int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStream *stream, int *count);

/**
* Get the current output channel map of an audio stream.
Expand All @@ -1139,9 +1118,6 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_Au
* Audio streams default to no remapping applied. This is represented by
* returning NULL, and does not signify an error.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param stream the SDL_AudioStream to query.
* \param count On output, set to number of channels in the map. Can be NULL.
* \returns an array of the current channel mapping, with as many elements as
Expand All @@ -1154,7 +1130,7 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_Au
*
* \sa SDL_SetAudioStreamInputChannelMap
*/
extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioStream *stream, int *count);
extern SDL_DECLSPEC_TEMP const int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioStream *stream, int *count);

/**
* Set the current input channel map of an audio stream.
Expand Down
2 changes: 2 additions & 0 deletions include/SDL3/SDL_begin_code.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,8 @@
# endif
# endif
#endif
/* This is used to mark functions that return temporary memory */
#define SDL_DECLSPEC_TEMP SDL_DECLSPEC

/* By default SDL uses the C calling convention */
#ifndef SDLCALL
Expand Down
25 changes: 5 additions & 20 deletions include/SDL3/SDL_camera.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -134,9 +134,6 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
* "coremedia" or "android". These never have Unicode characters, and are not
* meant to be proper names.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param index the index of the camera driver; the value ranges from 0 to
* SDL_GetNumCameraDrivers() - 1.
* \returns the name of the camera driver at the requested index, or NULL if
Expand All @@ -148,7 +145,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
*
* \sa SDL_GetNumCameraDrivers
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetCameraDriver(int index);

/**
* Get the name of the current camera driver.
Expand All @@ -157,24 +154,18 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index);
* "coremedia" or "android". These never have Unicode characters, and are not
* meant to be proper names.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the name of the current camera driver or NULL if no driver has
* been initialized.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0.
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetCurrentCameraDriver(void);

/**
* Get a list of currently connected camera devices.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param count a pointer filled in with the number of cameras returned, may
* be NULL.
* \returns a 0 terminated array of camera instance IDs or NULL on failure;
Expand All @@ -186,7 +177,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void);
*
* \sa SDL_OpenCamera
*/
extern SDL_DECLSPEC const SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
extern SDL_DECLSPEC_TEMP const SDL_CameraID * SDLCALL SDL_GetCameras(int *count);

/**
* Get the list of native formats/sizes a camera supports.
Expand All @@ -210,9 +201,6 @@ extern SDL_DECLSPEC const SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
* there _is_ a camera until the user has given you permission to check
* through a scary warning popup.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param devid the camera device instance ID to query.
* \param count a pointer filled in with the number of elements in the list,
* may be NULL.
Expand All @@ -226,14 +214,11 @@ extern SDL_DECLSPEC const SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
* \sa SDL_GetCameras
* \sa SDL_OpenCamera
*/
extern SDL_DECLSPEC const SDL_CameraSpec * const * SDLCALL SDL_GetCameraSupportedFormats(SDL_CameraID devid, int *count);
extern SDL_DECLSPEC_TEMP const SDL_CameraSpec * const * SDLCALL SDL_GetCameraSupportedFormats(SDL_CameraID devid, int *count);

/**
* Get the human-readable device name for a camera.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \param instance_id the camera device instance ID.
* \returns a human-readable device name or NULL on failure; call
* SDL_GetError() for more information.
Expand All @@ -244,7 +229,7 @@ extern SDL_DECLSPEC const SDL_CameraSpec * const * SDLCALL SDL_GetCameraSupporte
*
* \sa SDL_GetCameras
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance_id);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetCameraName(SDL_CameraID instance_id);

/**
* Get the position of the camera in relation to the system.
Expand Down
15 changes: 3 additions & 12 deletions include/SDL3/SDL_clipboard.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,9 +62,6 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
* This functions returns empty string if there was not enough memory left for
* a copy of the clipboard's content.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the clipboard text on success or an empty string on failure; call
* SDL_GetError() for more information.
*
Expand All @@ -73,7 +70,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
* \sa SDL_HasClipboardText
* \sa SDL_SetClipboardText
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetClipboardText(void);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetClipboardText(void);

/**
* Query whether the clipboard exists and contains a non-empty text string.
Expand Down Expand Up @@ -107,9 +104,6 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text);
* This functions returns empty string if there was not enough memory left for
* a copy of the primary selection's content.
*
* This returns temporary memory which will be automatically freed later, and
* can be claimed with SDL_ClaimTemporaryMemory().
*
* \returns the primary selection text on success or an empty string on
* failure; call SDL_GetError() for more information.
*
Expand All @@ -118,7 +112,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text);
* \sa SDL_HasPrimarySelectionText
* \sa SDL_SetPrimarySelectionText
*/
extern SDL_DECLSPEC const char * SDLCALL SDL_GetPrimarySelectionText(void);
extern SDL_DECLSPEC_TEMP const char * SDLCALL SDL_GetPrimarySelectionText(void);

/**
* Query whether the primary selection exists and contains a non-empty text
Expand Down Expand Up @@ -223,15 +217,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearClipboardData(void);
* \returns the retrieved data buffer or NULL on failure; call SDL_GetError()
* for more information.
*
* This returns temporary memory which will be automatically freed
* later, and can be claimed with SDL_ClaimTemporaryMemory().
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_HasClipboardData
* \sa SDL_SetClipboardData
*/
extern SDL_DECLSPEC const void * SDLCALL SDL_GetClipboardData(const char *mime_type, size_t *size);
extern SDL_DECLSPEC_TEMP const void * SDLCALL SDL_GetClipboardData(const char *mime_type, size_t *size);

/**
* Query whether there is data in the clipboard for the provided mime type.
Expand Down
Loading

0 comments on commit f745c46

Please sign in to comment.