Sync SDL3 wiki -> header

2025-09-05 19:08:12 +00:00 · 2024-07-27 03:59:43 +00:00
parent 4f55271571
commit 0f2fc2fbaa
14 changed files with 72 additions and 33 deletions
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -447,7 +447,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void);
 * \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
- *          SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          SDL_GetError() for more information. This should be freed with
+ *          SDL_free() when it is no longer needed.
 *
 * \threadsafety It is safe to call this function from any thread.
 *
@@ -475,7 +476,8 @@ extern SDL_DECLSPEC_FREE SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices
 * \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;
- *          call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          call SDL_GetError() for more information. This should be freed
+ *          with SDL_free() when it is no longer needed.
 *
 * \threadsafety It is safe to call this function from any thread.
 *
@@ -550,7 +552,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid
 * \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
- *          the current output spec's channels, or NULL if default. This should be freed with SDL_free() when it is no longer needed.
+ *          the current output spec's channels, or NULL if default. This
+ *          should be freed with SDL_free() when it is no longer needed.
 *
 * \threadsafety It is safe to call this function from any thread.
 *
@@ -1098,7 +1101,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream,
 * \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
- *          the current output spec's channels, or NULL if default. This should be freed with SDL_free() when it is no longer needed.
+ *          the current output spec's channels, or NULL if default. This
+ *          should be freed with SDL_free() when it is no longer needed.
 *
 * \threadsafety It is safe to call this function from any thread, as it holds
 *               a stream-specific mutex while running.
@@ -1121,7 +1125,8 @@ extern SDL_DECLSPEC_FREE int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_Aud
 * \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
- *          the current output spec's channels, or NULL if default. This should be freed with SDL_free() when it is no longer needed.
+ *          the current output spec's channels, or NULL if default. This
+ *          should be freed with SDL_free() when it is no longer needed.
 *
 * \threadsafety It is safe to call this function from any thread, as it holds
 *               a stream-specific mutex while running.
--- a/include/SDL3/SDL_camera.h
+++ b/include/SDL3/SDL_camera.h
@@ -169,7 +169,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void);
 * \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;
- *          call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          call SDL_GetError() for more information. This should be freed
+ *          with SDL_free() when it is no longer needed.
 *
 * \threadsafety It is safe to call this function from any thread.
 *
@@ -205,7 +206,9 @@ extern SDL_DECLSPEC_FREE SDL_CameraID * SDLCALL SDL_GetCameras(int *count);
 * \param count a pointer filled in with the number of elements in the list,
 *              may be NULL.
 * \returns a NULL terminated array of pointers to SDL_CameraSpec or NULL on
- *          failure; call SDL_GetError() for more information. This is a single allocation that should be freed with SDL_free() when it is no longer needed.
+ *          failure; call SDL_GetError() for more information. This is a
+ *          single allocation that should be freed with SDL_free() when it is
+ *          no longer needed.
 *
 * \threadsafety It is safe to call this function from any thread.
 *
--- a/include/SDL3/SDL_clipboard.h
+++ b/include/SDL3/SDL_clipboard.h
@@ -63,7 +63,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
 * a copy of the clipboard's content.
 *
 * \returns the clipboard text on success or an empty string on failure; call
- *          SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          SDL_GetError() for more information. This should be freed with
+ *          SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
@@ -105,7 +106,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text);
 * a copy of the primary selection's content.
 *
 * \returns the primary selection text on success or an empty string on
- *          failure; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          failure; call SDL_GetError() for more information. This should be
+ *          freed with SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
@@ -215,7 +217,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearClipboardData(void);
 * \param mime_type the mime type to read from the clipboard.
 * \param size a pointer filled in with the length of the returned data.
 * \returns the retrieved data buffer or NULL on failure; call SDL_GetError()
- *          for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          for more information. This should be freed with SDL_free() when it
+ *          is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
--- a/include/SDL3/SDL_filesystem.h
+++ b/include/SDL3/SDL_filesystem.h
@@ -125,7 +125,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void);
 * \param app the name of your application.
 * \returns a UTF-8 string of the user directory in platform-dependent
 *          notation. NULL if there's a problem (creating directory failed,
- *          etc.). This should be freed with SDL_free() when it is no longer needed.
+ *          etc.). This should be freed with SDL_free() when it is no longer
+ *          needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
@@ -367,7 +368,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo *
 * \param count on return, will be set to the number of items in the returned
 *              array. Can be NULL.
 * \returns an array of strings on success or NULL on failure; call
- *          SDL_GetError() for more information. This is a single allocation that should be freed with SDL_free() when it is no longer needed.
+ *          SDL_GetError() for more information. This is a single allocation
+ *          that should be freed with SDL_free() when it is no longer needed.
 *
 * \threadsafety It is safe to call this function from any thread.
 *
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -392,7 +392,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReloadGamepadMappings(void);
 * \param count a pointer filled in with the number of mappings returned, can
 *              be NULL.
 * \returns an array of the mapping strings, NULL-terminated, or NULL on
- *          failure; call SDL_GetError() for more information. This is a single allocation that should be freed with SDL_free() when it is no longer needed.
+ *          failure; call SDL_GetError() for more information. This is a
+ *          single allocation that should be freed with SDL_free() when it is
+ *          no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 */
@@ -403,7 +405,8 @@ extern SDL_DECLSPEC_FREE char ** SDLCALL SDL_GetGamepadMappings(int *count);
 *
 * \param guid a structure containing the GUID for which a mapping is desired.
 * \returns a mapping string or NULL on failure; call SDL_GetError() for more
- *          information. This should be freed with SDL_free() when it is no longer needed.
+ *          information. This should be freed with SDL_free() when it is no
+ *          longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
@@ -419,7 +422,8 @@ extern SDL_DECLSPEC_FREE char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID gu
 *
 * \param gamepad the gamepad you want to get the current mapping for.
 * \returns a string that has the gamepad's mapping or NULL if no mapping is
- *          available; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          available; call SDL_GetError() for more information. This should
+ *          be freed with SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
@@ -465,7 +469,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void);
 * \param count a pointer filled in with the number of gamepads returned, may
 *              be NULL.
 * \returns a 0 terminated array of joystick instance IDs or NULL on failure;
- *          call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          call SDL_GetError() for more information. This should be freed
+ *          with SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
@@ -640,7 +645,8 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys
 * This can be called before any gamepads are opened.
 *
 * \param instance_id the joystick instance ID.
- * \returns the mapping string. Returns NULL if no mapping is available. This should be freed with SDL_free() when it is no longer needed.
+ * \returns the mapping string. Returns NULL if no mapping is available. This
+ *          should be freed with SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
@@ -995,7 +1001,9 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void);
 * \param gamepad a gamepad.
 * \param count a pointer filled in with the number of bindings returned.
 * \returns a NULL terminated array of pointers to bindings or NULL on
- *          failure; call SDL_GetError() for more information. This is a single allocation that should be freed with SDL_free() when it is no longer needed.
+ *          failure; call SDL_GetError() for more information. This is a
+ *          single allocation that should be freed with SDL_free() when it is
+ *          no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 */
--- a/include/SDL3/SDL_haptic.h
+++ b/include/SDL3/SDL_haptic.h
@@ -935,7 +935,8 @@ typedef Uint32 SDL_HapticID;
 * \param count a pointer filled in with the number of haptic devices
 *              returned, may be NULL.
 * \returns a 0 terminated array of haptic device instance IDs or NULL on
- *          failure; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          failure; call SDL_GetError() for more information. This should be
+ *          freed with SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -204,7 +204,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void);
 * \param count a pointer filled in with the number of joysticks returned, may
 *              be NULL.
 * \returns a 0 terminated array of joystick instance IDs or NULL on failure;
- *          call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          call SDL_GetError() for more information. This should be freed
+ *          with SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
--- a/include/SDL3/SDL_keyboard.h
+++ b/include/SDL3/SDL_keyboard.h
@@ -76,7 +76,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void);
 * \param count a pointer filled in with the number of keyboards returned, may
 *              be NULL.
 * \returns a 0 terminated array of keyboards instance IDs or NULL on failure;
- *          call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          call SDL_GetError() for more information. This should be freed
+ *          with SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
--- a/include/SDL3/SDL_locale.h
+++ b/include/SDL3/SDL_locale.h
@@ -92,7 +92,9 @@ typedef struct SDL_Locale
 * \param count a pointer filled in with the number of locales returned, may
 *              be NULL.
 * \returns a NULL terminated array of locale pointers, or NULL on failure;
- *          call SDL_GetError() for more information. This is a single allocation that should be freed with SDL_free() when it is no longer needed.
+ *          call SDL_GetError() for more information. This is a single
+ *          allocation that should be freed with SDL_free() when it is no
+ *          longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 */
--- a/include/SDL3/SDL_mouse.h
+++ b/include/SDL3/SDL_mouse.h
@@ -138,7 +138,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void);
 * \param count a pointer filled in with the number of mice returned, may be
 *              NULL.
 * \returns a 0 terminated array of mouse instance IDs or NULL on failure;
- *          call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          call SDL_GetError() for more information. This should be freed
+ *          with SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
--- a/include/SDL3/SDL_sensor.h
+++ b/include/SDL3/SDL_sensor.h
@@ -149,7 +149,8 @@ typedef enum SDL_SensorType
 * \param count a pointer filled in with the number of sensors returned, may
 *              be NULL.
 * \returns a 0 terminated array of sensor instance IDs or NULL on failure;
- *          call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          call SDL_GetError() for more information. This should be freed
+ *          with SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 */
--- a/include/SDL3/SDL_storage.h
+++ b/include/SDL3/SDL_storage.h
@@ -410,7 +410,9 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto
 *              array. Can be NULL.
 * \returns an array of strings on success or NULL on failure; call
 *          SDL_GetError() for more information. The caller should pass the
- *          returned pointer to SDL_free when done with it. This is a single allocation that should be freed with SDL_free() when it is no longer needed.
+ *          returned pointer to SDL_free when done with it. This is a single
+ *          allocation that should be freed with SDL_free() when it is no
+ *          longer needed.
 *
 * \threadsafety It is safe to call this function from any thread, assuming
 *               the `storage` object is thread-safe.
--- a/include/SDL3/SDL_touch.h
+++ b/include/SDL3/SDL_touch.h
@@ -86,7 +86,8 @@ typedef struct SDL_Finger
 * \param count a pointer filled in with the number of devices returned, may
 *              be NULL.
 * \returns a 0 terminated array of touch device IDs or NULL on failure; call
- *          SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          SDL_GetError() for more information. This should be freed with
+ *          SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 */
@@ -120,7 +121,9 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch
 * \param count a pointer filled in with the number of fingers returned, can
 *              be NULL.
 * \returns a NULL terminated array of SDL_Finger pointers or NULL on failure;
- *          call SDL_GetError() for more information. This is a single allocation that should be freed with SDL_free() when it is no longer needed.
+ *          call SDL_GetError() for more information. This is a single
+ *          allocation that should be freed with SDL_free() when it is no
+ *          longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 */
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -390,7 +390,8 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
 * \param count a pointer filled in with the number of displays returned, may
 *              be NULL.
 * \returns a 0 terminated array of display instance IDs or NULL on failure;
- *          call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          call SDL_GetError() for more information. This should be freed
+ *          with SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 */
@@ -551,7 +552,9 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ
 * \param count a pointer filled in with the number of display modes returned,
 *              may be NULL.
 * \returns a NULL terminated array of display mode pointers or NULL on
- *          failure; call SDL_GetError() for more information. This is a single allocation that should be freed with SDL_free() when it is no longer needed.
+ *          failure; call SDL_GetError() for more information. This is a
+ *          single allocation that should be freed with SDL_free() when it is
+ *          no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 *
@@ -576,8 +579,8 @@ extern SDL_DECLSPEC_FREE SDL_DisplayMode ** SDLCALL SDL_GetFullscreenDisplayMode
 *                     for the desktop refresh rate.
 * \param include_high_density_modes boolean to include high density modes in
 *                                   the search.
- * \param mode a pointer filled in with the closest display mode equal to or larger than the
- *          desired mode.
+ * \param mode a pointer filled in with the closest display mode equal to or
+ *             larger than the desired mode.
 * \returns 0 on success or a negative error code on failure; call
 *          SDL_GetError() for more information.
 *
@@ -762,7 +765,8 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode(
 * \param window the window to query.
 * \param size the size of the ICC profile.
 * \returns the raw ICC profile data on success or NULL on failure; call
- *          SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.
+ *          SDL_GetError() for more information. This should be freed with
+ *          SDL_free() when it is no longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 */
@@ -786,7 +790,9 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window
 * \param count a pointer filled in with the number of windows returned, may
 *              be NULL.
 * \returns a NULL terminated array of SDL_Window pointers or NULL on failure;
- *          call SDL_GetError() for more information. This is a single allocation that should be freed with SDL_free() when it is no longer needed.
+ *          call SDL_GetError() for more information. This is a single
+ *          allocation that should be freed with SDL_free() when it is no
+ *          longer needed.
 *
 * \since This function is available since SDL 3.0.0.
 */