mirrors
/
SDL
mirror of https://github.com/libsdl-org/SDL
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Clarify that the SDL_GetStringRule means that SDL will automatically free the memory later.

This commit is contained in:
Sam Lantinga 2024-07-17 23:20:23 -07:00
parent 0d24b6e9f3
commit d73c7311d5
23 changed files with 66 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
include/SDL3/SDL_audio.h
View File

@ -400,7 +400,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
* "coreaudio" or "wasapi". These never have Unicode characters, and are not
* meant to be proper names.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param index the index of the audio driver; the value ranges from 0 to
* SDL_GetNumAudioDrivers() - 1.
@ -423,7 +423,7 @@ 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.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \returns the name of the current audio driver or NULL if no driver has been
* initialized.
@ -495,7 +495,7 @@ extern SDL_DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioRecordingDevices(int
/**
* Get the human-readable name of a specific audio device.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param devid the instance ID of the device to query.
* \returns the name of the audio device, or NULL on error.
@ -554,8 +554,7 @@ 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.
*
* The returned array follows the SDL_GetStringRule (even though, strictly
* speaking, it isn't a string, it has the same memory manangement rules).
* The returned array follows the SDL_GetStringRule, and will be automatically freed later.
*
* \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.
@ -1096,8 +1095,7 @@ 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.
*
* The returned array follows the SDL_GetStringRule (even though, strictly
* speaking, it isn't a string, it has the same memory manangement rules).
* The returned array follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param stream the SDL_AudioStream to query.
* \param count On output, set to number of channels in the map. Can be NULL.
@ -1122,8 +1120,7 @@ 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.
*
* The returned array follows the SDL_GetStringRule (even though, strictly
* speaking, it isn't a string, it has the same memory manangement rules).
* The returned array follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param stream the SDL_AudioStream to query.
* \param count On output, set to number of channels in the map. Can be NULL.

6
include/SDL3/SDL_camera.h
View File

@ -134,7 +134,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void);
* "coremedia" or "android". These never have Unicode characters, and are not
* meant to be proper names.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param index the index of the camera driver; the value ranges from 0 to
* SDL_GetNumCameraDrivers() - 1.
@ -156,7 +156,7 @@ 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.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \returns the name of the current camera driver or NULL if no driver has
* been initialized.
@ -230,7 +230,7 @@ extern SDL_DECLSPEC SDL_CameraSpec *SDLCALL SDL_GetCameraSupportedFormats(SDL_Ca
/**
* Get the human-readable device name for a camera.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the camera device instance ID.
* \returns a human-readable device name, or NULL on error; call

4
include/SDL3/SDL_clipboard.h
View File

@ -62,7 +62,7 @@ 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.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \returns the clipboard text on success or an empty string on failure; call
* SDL_GetError() for more information.
@ -106,7 +106,7 @@ 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.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \returns the primary selection text on success or an empty string on
* failure; call SDL_GetError() for more information.

8
include/SDL3/SDL_events.h
View File

@ -350,7 +350,7 @@ typedef struct SDL_KeyboardEvent
* will be inserted into the editing text. The length is the number of UTF-8
* characters that will be replaced by new typing.
*
* The text string follows the SDL_GetStringRule.
* The text string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \since This struct is available since SDL 3.0.0.
*/
@ -368,7 +368,7 @@ typedef struct SDL_TextEditingEvent
/**
* Keyboard IME candidates event structure (event.edit_candidates.*)
*
* The candidates follow the SDL_GetStringRule.
* The candidates follow the SDL_GetStringRule, and will be automatically freed later.
*
* \since This struct is available since SDL 3.0.0.
*/
@ -387,7 +387,7 @@ typedef struct SDL_TextEditingCandidatesEvent
/**
* Keyboard text input event structure (event.text.*)
*
* The text string follows the SDL_GetStringRule.
* The text string follows the SDL_GetStringRule, and will be automatically freed later.
*
* This event will never be delivered unless text input is enabled by calling
* SDL_StartTextInput(). Text input is disabled by default!
@ -784,7 +784,7 @@ typedef struct SDL_PenButtonEvent
* An event used to drop text or request a file open by the system
* (event.drop.*)
*
* The source and data strings follow the SDL_GetStringRule.
* The source and data strings follow the SDL_GetStringRule, and will be automatically freed later.
*
* \since This struct is available since SDL 3.0.0.
*/

8
include/SDL3/SDL_filesystem.h
View File

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

30
include/SDL3/SDL_gamepad.h
View File

@ -389,12 +389,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReloadGamepadMappings(void);
/**
* Get the current gamepad mappings.
*
* The returned pointer follows the SDL_GetStringRule.
* The returned pointer follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param count a pointer filled in with the number of mappings returned, can
* be NULL.
* \returns an array of the mapping strings, NULL-terminated. Returns NULL on
* error.
* error; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -403,7 +403,7 @@ extern SDL_DECLSPEC const char * const * SDLCALL SDL_GetGamepadMappings(int *cou
/**
* Get the gamepad mapping string for a given GUID.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param guid a structure containing the GUID for which a mapping is desired.
* \returns a mapping string or NULL on error; call SDL_GetError() for more
@ -419,7 +419,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_Joysti
/**
* Get the current mapping of a gamepad.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* Details about mappings are discussed with SDL_AddGamepadMapping().
*
@ -499,7 +499,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id);
*
* This can be called before any gamepads are opened.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the joystick instance ID.
* \returns the name of the selected gamepad. If no name can be found, this
@ -517,7 +517,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID i
*
* This can be called before any gamepads are opened.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the joystick instance ID.
* \returns the path of the selected gamepad. If no path can be found, this
@ -650,7 +650,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys
*
* This can be called before any gamepads are opened.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the joystick instance ID.
* \returns the mapping string. Returns NULL if no mapping is available.
@ -749,7 +749,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad
/**
* Get the implementation-dependent name for an opened gamepad.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad().
@ -765,7 +765,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad)
/**
* Get the implementation-dependent path for an opened gamepad.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad().
@ -892,7 +892,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *ga
*
* Returns the serial number of the gamepad, or NULL if it is not available.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param gamepad the gamepad object to query.
* \returns the serial number, or NULL if unavailable.
@ -1052,7 +1052,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c
/**
* Convert from an SDL_GamepadType enum to a string.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param type an enum value for a given SDL_GamepadType.
* \returns a string for the given type, or NULL if an invalid type is
@ -1090,7 +1090,7 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c
/**
* Convert from an SDL_GamepadAxis enum to a string.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param axis an enum value for a given SDL_GamepadAxis.
* \returns a string for the given axis, or NULL if an invalid axis is
@ -1165,7 +1165,7 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con
/**
* Convert from an SDL_GamepadButton enum to a string.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param button an enum value for a given SDL_GamepadButton.
* \returns a string for the given button, or NULL if an invalid button is
@ -1453,7 +1453,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad);
* Return the sfSymbolsName for a given button on a gamepad on Apple
* platforms.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param gamepad the gamepad to query.
* \param button a button on the gamepad.
@ -1468,7 +1468,7 @@ extern SDL_DECLSPEC const char* SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButto
/**
* Return the sfSymbolsName for a given axis on a gamepad on Apple platforms.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param gamepad the gamepad to query.
* \param axis an axis on the gamepad.

4
include/SDL3/SDL_haptic.h
View File

@ -949,7 +949,7 @@ extern SDL_DECLSPEC SDL_HapticID *SDLCALL SDL_GetHaptics(int *count);
*
* This can be called before any haptic devices are opened.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the haptic device instance ID.
* \returns the name of the selected haptic device. If no name can be found,
@ -1014,7 +1014,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic);
/**
* Get the implementation dependent name of a haptic device.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param haptic the SDL_Haptic obtained from SDL_OpenJoystick().
* \returns the name of the selected haptic device. If no name can be found,

2
include/SDL3/SDL_hints.h
View File

@ -3883,7 +3883,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void);
/**
* Get the value of a hint.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param name the hint to query.
* \returns the string value of a hint or NULL if the hint isn't set.

10
include/SDL3/SDL_joystick.h
View File

@ -227,7 +227,7 @@ extern SDL_DECLSPEC SDL_JoystickID *SDLCALL SDL_GetJoysticks(int *count);
*
* This can be called before any joysticks are opened.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the joystick instance ID.
* \returns the name of the selected joystick. If no name can be found, this
@ -245,7 +245,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID
*
* This can be called before any joysticks are opened.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the joystick instance ID.
* \returns the path of the selected joystick. If no path can be found, this
@ -666,7 +666,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst
/**
* Get the implementation dependent name of a joystick.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the name of the selected joystick. If no name can be found, this
@ -681,7 +681,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetJoystickName(SDL_Joystick *joysti
/**
* Get the implementation dependent path of a joystick.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the path of the selected joystick. If no path can be found, this
@ -800,7 +800,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *
*
* Returns the serial number of the joystick, or NULL if it is not available.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick().
* \returns the serial number of the selected joystick, or NULL if

6
include/SDL3/SDL_keyboard.h
View File

@ -90,7 +90,7 @@ extern SDL_DECLSPEC SDL_KeyboardID *SDLCALL SDL_GetKeyboards(int *count);
*
* This function returns "" if the keyboard doesn't have a name.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the keyboard instance ID.
* \returns the name of the selected keyboard, or NULL on failure; call
@ -280,7 +280,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const
/**
* Get a human-readable name for a scancode.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* **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
@ -326,7 +326,7 @@ 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 ("").
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param key the desired SDL_Keycode to query.
* \returns a UTF-8 encoded string of the key name.

2
include/SDL3/SDL_mouse.h
View File

@ -152,7 +152,7 @@ extern SDL_DECLSPEC SDL_MouseID *SDLCALL SDL_GetMice(int *count);
*
* This function returns "" if the mouse doesn't have a name.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the mouse instance ID.
* \returns the name of the selected mouse, or NULL on failure; call

2
include/SDL3/SDL_pen.h
View File

@ -224,7 +224,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
/**
* Retrieves a human-readable description for a SDL_PenID.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the pen to query.
* \returns a string that contains the name of the pen, intended for human

2
include/SDL3/SDL_pixels.h
View File

@ -723,7 +723,7 @@ typedef struct SDL_PixelFormatDetails
/**
* Get the human readable name of a pixel format.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param format the pixel format to query.
* \returns the human readable name of the specified pixel format or

2
include/SDL3/SDL_platform.h
View File

@ -48,7 +48,7 @@ extern "C" {
* - "iOS"
* - "Android"
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \returns the name of the platform. If the correct platform name is not
* available, returns a string beginning with the text "Unknown".

2
include/SDL3/SDL_properties.h
View File

@ -378,7 +378,7 @@ extern SDL_DECLSPEC void *SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props,
/**
* Get a string property from a group of properties.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param props the properties to query.
* \param name the name of the property to query.

4
include/SDL3/SDL_render.h
View File

@ -154,7 +154,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
* "direct3d12" or "metal". These never have Unicode characters, and are not
* meant to be proper names.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param index the index of the rendering driver; the value ranges from 0 to
* SDL_GetNumRenderDrivers() - 1.
@ -324,7 +324,7 @@ extern SDL_DECLSPEC SDL_Window *SDLCALL SDL_GetRenderWindow(SDL_Renderer *render
/**
* Get the name of a renderer.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param renderer the rendering context.
* \returns the name of the selected renderer, or NULL if the renderer is

4
include/SDL3/SDL_sensor.h
View File

@ -160,7 +160,7 @@ extern SDL_DECLSPEC SDL_SensorID *SDLCALL SDL_GetSensors(int *count);
*
* This can be called before any sensors are opened.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the sensor instance ID.
* \returns the sensor name, or NULL if `instance_id` is not valid.
@ -229,7 +229,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor
/**
* Get the implementation dependent name of a sensor.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param sensor the SDL_Sensor object.
* \returns the sensor name, or NULL if `sensor` is NULL.

2
include/SDL3/SDL_storage.h
View File

@ -383,7 +383,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto
* convenience, but if `count` is non-NULL, on return it will contain the
* number of items in the array, not counting the NULL terminator.
*
* The returned pointer follows the SDL_GetStringRule.
* The returned pointer follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param storage a storage container.
* \param path the path of the directory to enumerate.

8
include/SDL3/SDL_system.h
View File

@ -407,7 +407,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void);
*
* https://developer.android.com/reference/android/content/Context#getFilesDir()
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \returns the path used for internal storage or NULL on failure; call
* SDL_GetError() for more information.
@ -448,7 +448,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void);
*
* https://developer.android.com/reference/android/content/Context#getExternalFilesDir()
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \returns the path used for external storage for this application on success
* or NULL on failure; call SDL_GetError() for more information.
@ -471,7 +471,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void)
*
* https://developer.android.com/reference/android/content/Context#getCacheDir()
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \returns the path used for caches for this application on success or NULL
* on failure; call SDL_GetError() for more information.
@ -625,7 +625,7 @@ typedef enum SDL_WinRT_DeviceFamily
*
* https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \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

2
include/SDL3/SDL_thread.h
View File

@ -330,7 +330,7 @@ extern SDL_DECLSPEC SDL_Thread *SDLCALL SDL_CreateThreadWithPropertiesRuntime(SD
/**
* Get the thread name as it was specified in SDL_CreateThread().
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param thread the thread to query.
* \returns a pointer to a UTF-8 string that names the specified thread, or

2
include/SDL3/SDL_touch.h
View File

@ -96,7 +96,7 @@ extern SDL_DECLSPEC SDL_TouchID *SDLCALL SDL_GetTouchDevices(int *count);
/**
* Get the touch device name as reported from the driver.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param touchID the touch device instance ID.
* \returns touch device name, or NULL on error; call SDL_GetError() for more

2
include/SDL3/SDL_version.h
View File

@ -163,7 +163,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetVersion(void);
* You shouldn't use this function for anything but logging it for debugging
* purposes. The string is not intended to be reliable in any way.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \returns an arbitrary string, uniquely identifying the exact revision of
* the SDL library in use.

8
include/SDL3/SDL_video.h
View File

@ -349,7 +349,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
* "x11" or "windows". These never have Unicode characters, and are not meant
* to be proper names.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param index the index of a video driver.
* \returns the name of the video driver with the given **index**.
@ -367,7 +367,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
* "x11" or "windows". These never have Unicode characters, and are not meant
* to be proper names.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \returns the name of the current video driver or NULL if no driver has been
* initialized.
@ -445,7 +445,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa
/**
* Get the name of a display in UTF-8 encoding.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param displayID the instance ID of the display to query.
* \returns the name of a display or NULL on failure; call SDL_GetError() for
@ -1304,7 +1304,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowTitle(SDL_Window *window, const cha
/**
* Get the title of a window.
*
* The returned string follows the SDL_GetStringRule.
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param window the window to query.
* \returns the title of the window in UTF-8 format or "" if there is no