gitea/SDL3_fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Introduce formal policy for APIs that return strings.

Browse Source 
This declares that any `const char *` returned from SDL is owned by SDL, and
promises to be valid _at least_ until the next time the event queue runs, or
SDL_Quit() is called, even if the thing that owns the string gets destroyed
or changed before then.

This is noted in the headers as "the SDL_GetStringRule", so this will both be
greppable to find a detailed explaination in docs/README-strings.md and
wikiheaders will automatically turn it into a link we can point at the
appropriate documentation.

Fixes #9902.

(and several FIXMEs, both known and yet-undocumented.)
This commit is contained in:
Ryan C. Gordon
2024-06-01 22:05:21 -04:00
parent b1f3682216
commit e23257307e
51 changed files with 262 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
include/SDL3/SDL_gamepad.h
View File

@@ -500,6 +500,8 @@ 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.
*
* \param instance_id the joystick instance ID
* \returns the name of the selected gamepad. If no name can be found, this
* function returns NULL; call SDL_GetError() for more information.
@@ -516,6 +518,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetGamepadInstanceName(SDL_JoystickI
*
* This can be called before any gamepads are opened.
*
* The returned string follows the SDL_GetStringRule.
*
* \param instance_id the joystick instance ID
* \returns the path of the selected gamepad. If no path can be found, this
* function returns NULL; call SDL_GetError() for more information.
@@ -748,6 +752,8 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadInstanceID(SDL_Gamepad
/**
* Get the implementation-dependent name for an opened gamepad.
*
* The returned string follows the SDL_GetStringRule.
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad()
* \returns the implementation dependent name for the gamepad, or NULL if
@@ -762,6 +768,8 @@ 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.
*
* \param gamepad a gamepad identifier previously returned by
* SDL_OpenGamepad()
* \returns the implementation dependent path for the gamepad, or NULL if
@@ -887,6 +895,8 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *ga
*
* Returns the serial number of the gamepad, or NULL if it is not available.
*
* The returned string follows the SDL_GetStringRule.
*
* \param gamepad the gamepad object to query.
* \returns the serial number, or NULL if unavailable.
*
@@ -1045,7 +1055,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c
/**
* Convert from an SDL_GamepadType enum to a string.
*
* The caller should not SDL_free() the returned string.
* The returned string follows the SDL_GetStringRule.
*
* \param type an enum value for a given SDL_GamepadType
* \returns a string for the given type, or NULL if an invalid type is
@@ -1083,7 +1093,7 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c
/**
* Convert from an SDL_GamepadAxis enum to a string.
*
* The caller should not SDL_free() the returned string.
* The returned string follows the SDL_GetStringRule.
*
* \param axis an enum value for a given SDL_GamepadAxis
* \returns a string for the given axis, or NULL if an invalid axis is
@@ -1158,7 +1168,7 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con
/**
* Convert from an SDL_GamepadButton enum to a string.
*
* The caller should not SDL_free() the returned string.
* The returned string follows the SDL_GetStringRule.
*
* \param button an enum value for a given SDL_GamepadButton
* \returns a string for the given button, or NULL if an invalid button is
@@ -1446,6 +1456,8 @@ 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.
*
* \param gamepad the gamepad to query
* \param button a button on the gamepad
* \returns the sfSymbolsName or NULL if the name can't be found
@@ -1459,6 +1471,8 @@ 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.
*
* \param gamepad the gamepad to query
* \param axis an axis on the gamepad
* \returns the sfSymbolsName or NULL if the name can't be found