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

16
include/SDL3/SDL_video.h
View File

@@ -338,6 +338,12 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void);
* The video drivers are presented in the order in which they are normally
* checked during initialization.
*
* The names of drivers are all simple, low-ASCII identifiers, like "cocoa",
* "x11" or "windows". These never have Unicode characters, and are not
* meant to be proper names.
*
* The returned string follows the SDL_GetStringRule.
*
* \param index the index of a video driver
* \returns the name of the video driver with the given **index**.
*
@@ -350,6 +356,12 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index);
/**
* Get the name of the currently initialized video driver.
*
* The names of drivers are all simple, low-ASCII identifiers, like "cocoa",
* "x11" or "windows". These never have Unicode characters, and are not
* meant to be proper names.
*
* The returned string follows the SDL_GetStringRule.
*
* \returns the name of the current video driver or NULL if no driver has been
* initialized.
*
@@ -438,6 +450,8 @@ 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.
*
* \param displayID the instance ID of the display to query
* \returns the name of a display or NULL on failure; call SDL_GetError() for
* more information.
@@ -1260,6 +1274,8 @@ 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.
*
* \param window the window to query
* \returns the title of the window in UTF-8 format or "" if there is no
* title.