mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-09-05 19:08:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

Browse Source
This commit is contained in:
SDL Wiki Bot
2024-07-28 14:23:13 +00:00
parent a36fe632fd
commit 18fe89e036
1 changed files with 43 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
include/SDL3/SDL_init.h
View File

@@ -196,8 +196,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_Quit(void);
* *
* There are several locations where SDL can make use of metadata (an "About" * There are several locations where SDL can make use of metadata (an "About"
* box in the macOS menu bar, the name of the app can be shown on some audio * box in the macOS menu bar, the name of the app can be shown on some audio
* mixers, etc). Any piece of metadata can be left as NULL, if a specific detail * mixers, etc). Any piece of metadata can be left as NULL, if a specific
* doesn't make sense for the app. * detail doesn't make sense for the app.
* *
* This function should be called as early as possible, before SDL_Init. * This function should be called as early as possible, before SDL_Init.
* Multiple calls to this function are allowed, but various state might not * Multiple calls to this function are allowed, but various state might not
@@ -206,18 +206,22 @@ extern SDL_DECLSPEC void SDLCALL SDL_Quit(void);
* Passing a NULL removes any previous metadata. * Passing a NULL removes any previous metadata.
* *
* This is a simplified interface for the most important information. You can * This is a simplified interface for the most important information. You can
* supply significantly more detailed metadata with SDL_SetAppMetadataProperty(). * supply significantly more detailed metadata with
* SDL_SetAppMetadataProperty().
* *
* \param appname The name of the application ("My Game 2: Bad Guy's Revenge!"). * \param appname The name of the application ("My Game 2: Bad Guy's
* \param appversion The version of the application ("1.0.0beta5" or a git hash, or whatever makes sense). * Revenge!").
* \param appidentifier A unique string in reverse-domain format that identifies this app ("com.example.mygame2"). * \param appversion The version of the application ("1.0.0beta5" or a git
* hash, or whatever makes sense).
* \param appidentifier A unique string in reverse-domain format that
* identifies this app ("com.example.mygame2").
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* \since This function is available since SDL 3.0.0.
*
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_SetAppMetadataProperty * \sa SDL_SetAppMetadataProperty
*/ */
extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier); extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier);
@@ -241,39 +245,41 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const ch
* *
* These are the supported properties: * These are the supported properties:
* *
* - `SDL_PROP_APP_METADATA_NAME_STRING`: The human-readable name of * - `SDL_PROP_APP_METADATA_NAME_STRING`: The human-readable name of the
* the application, like "My Game 2: Bad Guy's Revenge!". This defaults to "SDL Application". * application, like "My Game 2: Bad Guy's Revenge!". This defaults to "SDL
* - SDL_PROP_APP_METADATA_VERSION_STRING`: The version of the app that * Application".
* is running; there are no rules on format, so "1.0.3beta2" and * - SDL_PROP_APP_METADATA_VERSION_STRING`: The version of the app that is
* "April 22nd, 2024" and a git hash are all valid options. This has no default. * running; there are no rules on format, so "1.0.3beta2" and "April 22nd,
* 2024" and a git hash are all valid options. This has no default.
* - `SDL_PROP_APP_METADATA_IDENTIFIER_STRING`: A unique string that * - `SDL_PROP_APP_METADATA_IDENTIFIER_STRING`: A unique string that
* identifies this app. This must be in reverse-domain format, like * identifies this app. This must be in reverse-domain format, like
* "com.example.mygame2". This string is used by desktop compositors to * "com.example.mygame2". This string is used by desktop compositors to
* identify and group windows together, as well as match applications * identify and group windows together, as well as match applications with
* with associated desktop settings and icons. This has no default. * associated desktop settings and icons. This has no default.
* - SDL_PROP_APP_METADATA_CREATOR_STRING`: The human-readable name * - SDL_PROP_APP_METADATA_CREATOR_STRING`: The human-readable name of the
* of the creator/developer/maker of this app, like "MojoWorkshop, LLC" * creator/developer/maker of this app, like "MojoWorkshop, LLC"
* - SDL_PROP_APP_METADATA_COPYRIGHT_STRING`: The human-readable copyright * - SDL_PROP_APP_METADATA_COPYRIGHT_STRING`: The human-readable copyright
* notice, like "Copyright (c) 2024 MojoWorkshop, LLC" or whatnot. Keep * notice, like "Copyright (c) 2024 MojoWorkshop, LLC" or whatnot. Keep this
* this to one line, don't paste a copy of a whole software license in * to one line, don't paste a copy of a whole software license in here. This
* here. This has no default. * has no default.
* - SDL_PROP_APP_METADATA_URL_STRING`: A URL to the app on the web. Maybe * - SDL_PROP_APP_METADATA_URL_STRING`: A URL to the app on the web. Maybe a
* a product page, or a storefront, or even a GitHub repository, for * product page, or a storefront, or even a GitHub repository, for user's
* user's further information This has no default. * further information This has no default.
* - SDL_PROP_APP_METADATA_TYPE_STRING`: The type of application this is. * - SDL_PROP_APP_METADATA_TYPE_STRING`: The type of application this is.
* Currently this string can be "game" for a video game, "mediaplayer" for * Currently this string can be "game" for a video game, "mediaplayer" for a
* a media player, or generically "application" if nothing else applies. * media player, or generically "application" if nothing else applies.
* Future versions of SDL might add new types. This defaults to "application". * Future versions of SDL might add new types. This defaults to
* "application".
* *
* \param name the name of the metadata property to set. * \param name the name of the metadata property to set.
* \param value the value of the property, or NULL to remove that property. * \param value the value of the property, or NULL to remove that property.
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. * SDL_GetError() for more information.
* *
* \since This function is available since SDL 3.0.0.
*
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetAppMetadataProperty * \sa SDL_GetAppMetadataProperty
* \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadata
*/ */
@@ -290,16 +296,20 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadataProperty(const char *name, con
/** /**
* Get metadata about your app. * Get metadata about your app.
* *
* This returns metadata previously set using SDL_SetAppMetadata() or SDL_SetAppMetadataProperty(). See SDL_SetAppMetadataProperty() for the list of available properties and their meanings. * This returns metadata previously set using SDL_SetAppMetadata() or
* SDL_SetAppMetadataProperty(). See SDL_SetAppMetadataProperty() for the list
* of available properties and their meanings.
* *
* \param name the name of the metadata property to get. * \param name the name of the metadata property to get.
* \returns the current value of the metadata property, or the default if it is not set, NULL for properties with no default. * \returns the current value of the metadata property, or the default if it
* * is not set, NULL for properties with no default.
* \since This function is available since SDL 3.0.0.
* *
* \threadsafety It is safe to call this function from any thread, although * \threadsafety It is safe to call this function from any thread, although
* the string returned is not protected and could potentially be * the string returned is not protected and could potentially be
* freed if you call SDL_SetAppMetadataProperty() to set that property from another thread. * freed if you call SDL_SetAppMetadataProperty() to set that
* property from another thread.
*
* \since This function is available since SDL 3.0.0.
* *
* \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadata
* \sa SDL_SetAppMetadataProperty * \sa SDL_SetAppMetadataProperty