From 0598ecc150841b22256aabe66068868d906cafcd Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Fri, 24 Feb 2023 11:49:41 -0500
Subject: [PATCH] Sync wiki -> headers.
---
include/SDL3/SDL_assert.h | 4 +++-
include/SDL3/SDL_audio.h | 6 ++++--
include/SDL3/SDL_error.h | 1 +
include/SDL3/SDL_joystick.h | 3 ++-
include/SDL3/SDL_locale.h | 2 +-
include/SDL3/SDL_main.h | 2 +-
include/SDL3/SDL_render.h | 34 ++++++++++++++++++----------------
include/SDL3/SDL_shape.h | 16 ++++++++--------
include/SDL3/SDL_surface.h | 4 ++--
include/SDL3/SDL_system.h | 3 ++-
include/SDL3/SDL_touch.h | 3 ++-
include/SDL3/SDL_video.h | 26 ++++++++++++++++----------
12 files changed, 60 insertions(+), 44 deletions(-)
diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index e26faed0f6fa..830fb3a98f7b 100644
--- a/include/SDL3/SDL_assert.h
+++ b/include/SDL3/SDL_assert.h
@@ -137,7 +137,9 @@ typedef struct SDL_AssertData
#if (SDL_ASSERT_LEVEL > 0)
/**
- * Never call this directly. Use the SDL_assert* macros.
+ * Never call this directly.
+ *
+ * Use the SDL_assert* macros.
*
* \param data assert data structure
* \param func function name
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index e03680358e88..ce8529a95939 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -811,7 +811,7 @@ extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
/**
* Clear any pending data in the stream without converting it
*
- * \param stream The audio stream to clear
+ * \param stream The audio stream to clear
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@@ -830,6 +830,7 @@ extern DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
* Free an audio stream
*
* \param stream The audio stream to free
+ *
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateAudioStream
@@ -1149,7 +1150,8 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
* \param dst_channels The number of channels of the desired audio output
* \param dst_rate The sampling rate of the desired audio output
* \param dst_data Will be filled with a pointer to converted audio data,
- * which should be freed with SDL_free(). On error, it will be NULL.
+ * which should be freed with SDL_free(). On error, it will be
+ * NULL.
* \param dst_len Will be filled with the len of dst_data
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
diff --git a/include/SDL3/SDL_error.h b/include/SDL3/SDL_error.h
index 1658f2fc238c..9440f4277432 100644
--- a/include/SDL3/SDL_error.h
+++ b/include/SDL3/SDL_error.h
@@ -148,6 +148,7 @@ typedef enum
SDL_UNSUPPORTED,
SDL_LASTERROR
} SDL_errorcode;
+
/**
* SDL_Error()
*
diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h
index 005a072a0805..92da0ce894ed 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -918,7 +918,8 @@ extern DECLSPEC int SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, U
* DualShock 4 controller.
*
* \param joystick The joystick to query
- * \returns SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise.
+ * \returns SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE
+ * otherwise.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_locale.h b/include/SDL3/SDL_locale.h
index d8c184203c19..ebf965ec282a 100644
--- a/include/SDL3/SDL_locale.h
+++ b/include/SDL3/SDL_locale.h
@@ -84,7 +84,7 @@ typedef struct SDL_Locale
* preferred locales.
*
* \returns array of locales, terminated with a locale with a NULL language
- * field. Will return NULL on error.
+ * field. Will return NULL on error.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h
index 6954bd3334c5..2e560b0fa3a2 100644
--- a/include/SDL3/SDL_main.h
+++ b/include/SDL3/SDL_main.h
@@ -192,7 +192,7 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
* \param reserved should be NULL (reserved for future use, will probably be
* platform-specific then)
* \returns the return value from mainFunction: 0 on success, -1 on failure;
- * SDL_GetError() might have more information on the failure
+ * SDL_GetError() might have more information on the failure
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h
index 1eea867d1319..f502cb9fc826 100644
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@@ -235,9 +235,9 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(int width, int height, U
* need a specific renderer, specify NULL and SDL will attempt to chooes the
* best option for you, based on what is available on the user's system.
*
- * By default the rendering size matches the window size in screen coordinates,
- * but you can call SDL_SetRenderLogicalPresentation() to enable high DPI
- * rendering or change the content size and scaling options.
+ * By default the rendering size matches the window size in screen
+ * coordinates, but you can call SDL_SetRenderLogicalPresentation() to enable
+ * high DPI rendering or change the content size and scaling options.
*
* \param window the window where rendering is displayed
* \param name the name of the rendering driver to initialize, or NULL to
@@ -337,8 +337,8 @@ extern DECLSPEC int SDLCALL SDL_GetRenderWindowSize(SDL_Renderer *renderer, int
/**
* Get the output size in pixels of a rendering context.
*
- * This returns the true output size in pixels, ignoring any render targets
- * or logical size and presentation.
+ * This returns the true output size in pixels, ignoring any render targets or
+ * logical size and presentation.
*
* \param renderer the rendering context
* \param w a pointer filled in with the width in pixels
@@ -355,9 +355,9 @@ extern DECLSPEC int SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int
/**
* Get the current output size in pixels of a rendering context.
*
- * If a rendering target is active, this will return the size of the
- * rendering target in pixels, otherwise if a logical size is set, it will
- * return the logical size, otherwise it will return the value of
+ * If a rendering target is active, this will return the size of the rendering
+ * target in pixels, otherwise if a logical size is set, it will return the
+ * logical size, otherwise it will return the value of
* SDL_GetRenderOutputSize().
*
* \param renderer the rendering context
@@ -610,7 +610,7 @@ extern DECLSPEC int SDLCALL SDL_SetTextureUserData(SDL_Texture *texture, void *u
*
* \param texture the texture to query.
* \returns the pointer associated with the texture, or NULL if the texture is
- * not valid.
+ * not valid.
*
* \since This function is available since SDL 3.0.0.
*
@@ -836,9 +836,9 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer)
/**
* Set a device independent resolution and presentation mode for rendering.
*
- * This function sets the width and height of the logical rendering output.
- * A render target is created at the specified size and used for rendering
- * and then copied to the output during presentation.
+ * This function sets the width and height of the logical rendering output. A
+ * render target is created at the specified size and used for rendering and
+ * then copied to the output during presentation.
*
* When a renderer is created, the logical size is set to match the window
* size in screen coordinates. The actual output size may be higher pixel
@@ -869,8 +869,8 @@ extern DECLSPEC int SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *rende
/**
* Get device independent resolution and presentation mode for rendering.
*
- * This function gets the width and height of the logical rendering output,
- * or the output size in pixels if a logical resolution is not enabled.
+ * This function gets the width and height of the logical rendering output, or
+ * the output size in pixels if a logical resolution is not enabled.
*
* \param renderer the rendering context
* \param w an int to be filled with the width
@@ -910,8 +910,10 @@ extern DECLSPEC int SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *render
* \param renderer the rendering context
* \param x the x coordinate in render coordinates
* \param y the y coordinate in render coordinates
- * \param window_x a pointer filled with the x coordinate in window coordinates
- * \param window_y a pointer filled with the y coordinate in window coordinates
+ * \param window_x a pointer filled with the x coordinate in window
+ * coordinates
+ * \param window_y a pointer filled with the y coordinate in window
+ * coordinates
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
diff --git a/include/SDL3/SDL_shape.h b/include/SDL3/SDL_shape.h
index 36fa1ed71d6c..964556ad96aa 100644
--- a/include/SDL3/SDL_shape.h
+++ b/include/SDL3/SDL_shape.h
@@ -72,8 +72,8 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,un
* Return whether the given window is a shaped window.
*
* \param window The window to query for being shaped.
- * \returns SDL_TRUE if the window is a window that can be shaped, SDL_FALSE if
- * the window is unshaped or NULL.
+ * \returns SDL_TRUE if the window is a window that can be shaped, SDL_FALSE
+ * if the window is unshaped or NULL.
*
* \since This function is available since SDL 3.0.0.
*
@@ -117,8 +117,8 @@ typedef struct SDL_WindowShapeMode {
* \param shape A surface encoding the desired shape for the window.
* \param shape_mode The parameters to set for the shaped window.
* \returns 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
- * argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
- * not reference a valid shaped window.
+ * argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
+ * not reference a valid shaped window.
*
* \since This function is available since SDL 3.0.0.
*
@@ -134,10 +134,10 @@ extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *s
* \param shape_mode An empty shape-mode structure to fill, or NULL to check
* whether the window has a shape.
* \returns 0 if the window has a shape and, provided shape_mode was not NULL,
- * shape_mode has been filled with the mode data,
- * SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped
- * window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a
- * shapeable window currently lacking a shape.
+ * shape_mode has been filled with the mode data,
+ * SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped
+ * window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a
+ * shapeable window currently lacking a shape.
*
* \since This function is available since SDL 3.0.0.
*
diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index 100d297eb26b..a9ee35b46aa9 100644
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -797,6 +797,8 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
* Perform a fast, low quality, stretch blit between two surfaces of the same
* format.
*
+ * **WARNING**: Please use SDL_BlitScaled() instead.
+ *
* \param src the SDL_Surface structure to be copied from
* \param srcrect the SDL_Rect structure representing the rectangle to be
* copied
@@ -806,8 +808,6 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
- * Please use SDL_BlitScaled() instead.
- *
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src,
diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index 7d6860fe688f..a85f4a182c44 100644
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@@ -385,7 +385,8 @@ extern DECLSPEC const char * SDLCALL SDL_AndroidGetInternalStoragePath(void);
*
* If external storage is currently unavailable, this will return 0.
*
- * \param state filled with the current state of external storage. 0 if external storage is currently unavailable.
+ * \param state filled with the current state of external storage. 0 if
+ * external storage is currently unavailable.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
diff --git a/include/SDL3/SDL_touch.h b/include/SDL3/SDL_touch.h
index cc1a9de1c19d..c374ba6a8731 100644
--- a/include/SDL3/SDL_touch.h
+++ b/include/SDL3/SDL_touch.h
@@ -121,7 +121,8 @@ extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID t
*
* \param touchID the ID of a touch device
* \returns the number of active fingers for a given touch device on success
- * or a negative error code on failure; call SDL_GetError() for more information.
+ * or a negative error code on failure; call SDL_GetError() for more
+ * information.
*
* \since This function is available since SDL 3.0.0.
*
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index 749f2e999643..f64e92ae9254 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -392,6 +392,7 @@ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(SDL_Dis
* Get a list of fullscreen display modes available on a display.
*
* The display modes are sorted in this priority:
+ *
* - screen_w -> largest to smallest
* - screen_h -> largest to smallest
* - pixel_w -> largest to smallest
@@ -402,9 +403,9 @@ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(SDL_Dis
*
* \param displayID the instance ID of the display to query
* \param count a pointer filled in with the number of displays returned
- * \returns a NULL terminated array of display mode pointers which should be freed
- * with SDL_free(), or NULL on error; call SDL_GetError() for more
- * details.
+ * \returns a NULL terminated array of display mode pointers which should be
+ * freed with SDL_free(), or NULL on error; call SDL_GetError() for
+ * more details.
*
* \since This function is available since SDL 3.0.0.
*
@@ -425,8 +426,11 @@ extern DECLSPEC const SDL_DisplayMode **SDLCALL SDL_GetFullscreenDisplayModes(SD
* \param displayID the instance ID of the display to query
* \param w the width in pixels of the desired display mode
* \param h the height in pixels of the desired display mode
- * \param refresh_rate the refresh rate of the desired display mode, or 0.0f for the desktop refresh rate
- * \returns a pointer to the closest display mode equal to or larger than the desired mode, or NULL on error; call SDL_GetError() for more information.
+ * \param refresh_rate the refresh rate of the desired display mode, or 0.0f
+ * for the desktop refresh rate
+ * \returns a pointer to the closest display mode equal to or larger than the
+ * desired mode, or NULL on error; call SDL_GetError() for more
+ * information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -525,7 +529,9 @@ extern DECLSPEC SDL_DisplayID SDLCALL SDL_GetDisplayForWindow(SDL_Window *window
* SDL_SetWindowSize().
*
* \param window the window to affect
- * \param mode a pointer to the display mode to use, which can be NULL for desktop mode, or one of the fullscreen modes returned by SDL_GetFullscreenDisplayModes().
+ * \param mode a pointer to the display mode to use, which can be NULL for
+ * desktop mode, or one of the fullscreen modes returned by
+ * SDL_GetFullscreenDisplayModes().
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@@ -822,8 +828,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowPosition(SDL_Window *window, int *x, in
* The window size in screen coordinates may differ from the size in pixels if
* the window is on a high density display (one with an OS scaling factor).
*
- * This only affects the size of the window when not in fullscreen mode. To change
- * the fullscreen mode of a window, use SDL_SetWindowFullscreenMode()
+ * This only affects the size of the window when not in fullscreen mode. To
+ * change the fullscreen mode of a window, use SDL_SetWindowFullscreenMode()
*
* \param window the window to change
* \param w the width of the window, must be > 0
@@ -1127,8 +1133,8 @@ extern DECLSPEC int SDLCALL SDL_RestoreWindow(SDL_Window *window);
/**
* Set a window's fullscreen state.
*
- * By default a window in fullscreen state uses fullscreen desktop mode,
- * but a specific display mode can be set using SDL_SetWindowFullscreenMode().
+ * By default a window in fullscreen state uses fullscreen desktop mode, but a
+ * specific display mode can be set using SDL_SetWindowFullscreenMode().
*
* \param window the window to change
* \param fullscreen SDL_TRUE for fullscreen mode, SDL_FALSE for windowed mode