Sync SDL3 wiki -> header

include/SDL3/SDL_gamepad.h

@@ -317,9 +317,10 @@ extern DECLSPEC int SDLCALL SDL_ReloadGamepadMappings(void);
  * You must free the returned pointer with SDL_free() when you are done with
  * it, but you do _not_ free each string in the array.
  *
- * \param count a pointer filled in with the number of mappings returned, can be NULL.
- * \returns an array of the mapping strings, NULL-terminated. Must be freed with SDL_free().
- *          Returns NULL on error.
+ * \param count a pointer filled in with the number of mappings returned, can
+ *              be NULL.
+ * \returns an array of the mapping strings, NULL-terminated. Must be freed
+ *          with SDL_free(). Returns NULL on error.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_keyboard.h

@@ -300,10 +300,11 @@ extern DECLSPEC void SDLCALL SDL_ClearComposition(void);
 extern DECLSPEC SDL_bool SDLCALL SDL_TextInputShown(void);
 
 /**
- * Set the rectangle used to type Unicode text inputs. Native input methods
- * will place a window with word suggestions near it, without covering the
- * text being inputted.
- * 
+ * Set the rectangle used to type Unicode text inputs.
+ *
+ * Native input methods will place a window with word suggestions near it,
+ * without covering the text being inputted.
+ *
  * To start text input in a given location, this function is intended to be
  * called before SDL_StartTextInput, although some platforms support moving
  * the rectangle even while text input (and a composition) is active.

include/SDL3/SDL_render.h

@@ -251,9 +251,12 @@ extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window, co
  * These are the supported properties:
  *
  * - "window" (pointer) - the window where rendering is displayed
- * - "surface" (pointer) - the surface where rendering is displayed, if you want a software renderer without a window
- * - "name" (string) - the name of the rendering driver to use, if a specific one is desired
- * - "present_vsync" (boolean) - true if you want present synchronized with the refresh rate
+ * - "surface" (pointer) - the surface where rendering is displayed, if you
+ *   want a software renderer without a window
+ * - "name" (string) - the name of the rendering driver to use, if a specific
+ *   one is desired
+ * - "present_vsync" (boolean) - true if you want present synchronized with
+ *   the refresh rate
  *
  * \param props the properties to use
  * \returns a valid rendering context or NULL if there was an error; call
@@ -447,36 +450,52 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *
  *
  * These are the supported properties:
  *
- * - "format" (number) - one of the enumerated values in SDL_PixelFormatEnum, defaults to the best RGBA format for the renderer
- * - "access" (number) - one of the enumerated values in SDL_TextureAccess, defaults to SDL_TEXTUREACCESS_STATIC
+ * - "format" (number) - one of the enumerated values in SDL_PixelFormatEnum,
+ *   defaults to the best RGBA format for the renderer
+ * - "access" (number) - one of the enumerated values in SDL_TextureAccess,
+ *   defaults to SDL_TEXTUREACCESS_STATIC
  * - "width" (number) - the width of the texture in pixels, required
  * - "height" (number) - the height of the texture in pixels, required
  *
  * With the direct3d11 renderer:
  *
- * - "d3d11.texture" (pointer) - the ID3D11Texture2D associated with the texture, if you want to wrap an existing texture.
- * - "d3d11.texture_u" (pointer) - the ID3D11Texture2D associated with the U plane of a YUV texture, if you want to wrap an existing texture.
- * - "d3d11.texture_v" (pointer) - the ID3D11Texture2D associated with the V plane of a YUV texture, if you want to wrap an existing texture.
+ * - "d3d11.texture" (pointer) - the ID3D11Texture2D associated with the
+ *   texture, if you want to wrap an existing texture.
+ * - "d3d11.texture_u" (pointer) - the ID3D11Texture2D associated with the U
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ * - "d3d11.texture_v" (pointer) - the ID3D11Texture2D associated with the V
+ *   plane of a YUV texture, if you want to wrap an existing texture.
  *
  * With the direct3d12 renderer:
  *
- * - "d3d12.texture" (pointer) - the ID3D12Resource associated with the texture, if you want to wrap an existing texture.
- * - "d3d12.texture_u" (pointer) - the ID3D12Resource associated with the U plane of a YUV texture, if you want to wrap an existing texture.
- * - "d3d12.texture_v" (pointer) - the ID3D12Resource associated with the V plane of a YUV texture, if you want to wrap an existing texture.
+ * - "d3d12.texture" (pointer) - the ID3D12Resource associated with the
+ *   texture, if you want to wrap an existing texture.
+ * - "d3d12.texture_u" (pointer) - the ID3D12Resource associated with the U
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ * - "d3d12.texture_v" (pointer) - the ID3D12Resource associated with the V
+ *   plane of a YUV texture, if you want to wrap an existing texture.
  *
  * With the opengl renderer:
  *
- * - "opengl.texture" (number) - the GLuint texture associated with the texture, if you want to wrap an existing texture.
- * - "opengl.texture_uv" (number) - the GLuint texture associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.
- * - "opengl.texture_u" (number) - the GLuint texture associated with the U plane of a YUV texture, if you want to wrap an existing texture.
- * - "opengl.texture_v" (number) - the GLuint texture associated with the V plane of a YUV texture, if you want to wrap an existing texture.
+ * - "opengl.texture" (number) - the GLuint texture associated with the
+ *   texture, if you want to wrap an existing texture.
+ * - "opengl.texture_uv" (number) - the GLuint texture associated with the UV
+ *   plane of an NV12 texture, if you want to wrap an existing texture.
+ * - "opengl.texture_u" (number) - the GLuint texture associated with the U
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ * - "opengl.texture_v" (number) - the GLuint texture associated with the V
+ *   plane of a YUV texture, if you want to wrap an existing texture.
  *
  * With the opengles2 renderer:
  *
- * - "opengles2.texture" (number) - the GLuint texture associated with the texture, if you want to wrap an existing texture.
- * - "opengles2.texture_uv" (number) - the GLuint texture associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.
- * - "opengles2.texture_u" (number) - the GLuint texture associated with the U plane of a YUV texture, if you want to wrap an existing texture.
- * - "opengles2.texture_v" (number) - the GLuint texture associated with the V plane of a YUV texture, if you want to wrap an existing texture.
+ * - "opengles2.texture" (number) - the GLuint texture associated with the
+ *   texture, if you want to wrap an existing texture.
+ * - "opengles2.texture_uv" (number) - the GLuint texture associated with the
+ *   UV plane of an NV12 texture, if you want to wrap an existing texture.
+ * - "opengles2.texture_u" (number) - the GLuint texture associated with the U
+ *   plane of a YUV texture, if you want to wrap an existing texture.
+ * - "opengles2.texture_v" (number) - the GLuint texture associated with the V
+ *   plane of a YUV texture, if you want to wrap an existing texture.
  *
  * \param renderer the rendering context
  * \param props the properties to use
@@ -501,31 +520,47 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureWithProperties(SDL_Rendere
  *
  * With the direct3d11 renderer:
  *
- * - "SDL.texture.d3d11.texture" (pointer) - the ID3D11Texture2D associated with the texture
- * - "SDL.texture.d3d11.texture_u" (pointer) - the ID3D11Texture2D associated with the U plane of a YUV texture
- * - "SDL.texture.d3d11.texture_v" (pointer) - the ID3D11Texture2D associated with the V plane of a YUV texture
+ * - "SDL.texture.d3d11.texture" (pointer) - the ID3D11Texture2D associated
+ *   with the texture
+ * - "SDL.texture.d3d11.texture_u" (pointer) - the ID3D11Texture2D associated
+ *   with the U plane of a YUV texture
+ * - "SDL.texture.d3d11.texture_v" (pointer) - the ID3D11Texture2D associated
+ *   with the V plane of a YUV texture
  *
  * With the direct3d12 renderer:
  *
- * - "SDL.texture.d3d12.texture" (pointer) - the ID3D12Resource associated with the texture
- * - "SDL.texture.d3d12.texture_u" (pointer) - the ID3D12Resource associated with the U plane of a YUV texture
- * - "SDL.texture.d3d12.texture_v" (pointer) - the ID3D12Resource associated with the V plane of a YUV texture
+ * - "SDL.texture.d3d12.texture" (pointer) - the ID3D12Resource associated
+ *   with the texture
+ * - "SDL.texture.d3d12.texture_u" (pointer) - the ID3D12Resource associated
+ *   with the U plane of a YUV texture
+ * - "SDL.texture.d3d12.texture_v" (pointer) - the ID3D12Resource associated
+ *   with the V plane of a YUV texture
  *
  * With the opengl renderer:
  *
- * - "SDL.texture.opengl.texture" (number) - the GLuint texture associated with the texture
- * - "SDL.texture.opengl.texture_uv" (number) - the GLuint texture associated with the UV plane of an NV12 texture
- * - "SDL.texture.opengl.texture_u" (number) - the GLuint texture associated with the U plane of a YUV texture
- * - "SDL.texture.opengl.texture_v" (number) - the GLuint texture associated with the V plane of a YUV texture
- * - "SDL.texture.opengl.tex_w" (float) - the texture coordinate width of the texture (0.0 - 1.0)
- * - "SDL.texture.opengl.tex_h" (float) - the texture coordinate height of the texture (0.0 - 1.0)
+ * - "SDL.texture.opengl.texture" (number) - the GLuint texture associated
+ *   with the texture
+ * - "SDL.texture.opengl.texture_uv" (number) - the GLuint texture associated
+ *   with the UV plane of an NV12 texture
+ * - "SDL.texture.opengl.texture_u" (number) - the GLuint texture associated
+ *   with the U plane of a YUV texture
+ * - "SDL.texture.opengl.texture_v" (number) - the GLuint texture associated
+ *   with the V plane of a YUV texture
+ * - "SDL.texture.opengl.tex_w" (float) - the texture coordinate width of the
+ *   texture (0.0 - 1.0)
+ * - "SDL.texture.opengl.tex_h" (float) - the texture coordinate height of the
+ *   texture (0.0 - 1.0)
  *
  * With the opengles2 renderer:
  *
- * - "SDL.texture.opengles2.texture" (number) - the GLuint texture associated with the texture
- * - "SDL.texture.opengles2.texture_uv" (number) - the GLuint texture associated with the UV plane of an NV12 texture
- * - "SDL.texture.opengles2.texture_u" (number) - the GLuint texture associated with the U plane of a YUV texture
- * - "SDL.texture.opengles2.texture_v" (number) - the GLuint texture associated with the V plane of a YUV texture
+ * - "SDL.texture.opengles2.texture" (number) - the GLuint texture associated
+ *   with the texture
+ * - "SDL.texture.opengles2.texture_uv" (number) - the GLuint texture
+ *   associated with the UV plane of an NV12 texture
+ * - "SDL.texture.opengles2.texture_u" (number) - the GLuint texture
+ *   associated with the U plane of a YUV texture
+ * - "SDL.texture.opengles2.texture_v" (number) - the GLuint texture
+ *   associated with the V plane of a YUV texture
  *
  * \param texture the texture to query
  * \returns a valid property ID on success or 0 on failure; call
@@ -1565,15 +1600,14 @@ extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer);
  *
  * In all other cases, you can ignore this function.
  *
- * This call makes SDL flush any pending rendering work it was queueing up
- * to do later in a single batch, and marks any internal cached state as
- * invalid, so it'll prepare all its state again later, from scratch.
+ * This call makes SDL flush any pending rendering work it was queueing up to
+ * do later in a single batch, and marks any internal cached state as invalid,
+ * so it'll prepare all its state again later, from scratch.
  *
  * This means you do not need to save state in your rendering code to protect
- * the SDL renderer. However, there lots of arbitrary pieces of Direct3D
- * and OpenGL state that can confuse things; you should use your best
- * judgement and be prepared to make changes if specific state needs to be
- * protected.
+ * the SDL renderer. However, there lots of arbitrary pieces of Direct3D and
+ * OpenGL state that can confuse things; you should use your best judgement
+ * and be prepared to make changes if specific state needs to be protected.
  *
  * \param renderer the rendering context
  * \returns 0 on success or a negative error code on failure; call

include/SDL3/SDL_touch.h

@@ -68,16 +68,16 @@ typedef struct SDL_Finger
  * Get a list of registered touch devices.
  *
  * On some platforms SDL first sees the touch device if it was actually used.
- * Therefore the returned list might be empty, although devices are
- * available. After using all devices at least once the number will be
- * correct.
+ * Therefore the returned list might be empty, although devices are available.
+ * After using all devices at least once the number will be correct.
  *
  * This was fixed for Android in SDL 2.0.1.
  *
- * \param count a pointer filled in with the number of devices returned, can be NULL.
- * \returns a 0 terminated array of touch device IDs which should be
- *          freed with SDL_free(), or NULL on error; call SDL_GetError() for
- *          more details.
+ * \param count a pointer filled in with the number of devices returned, can
+ *              be NULL.
+ * \returns a 0 terminated array of touch device IDs 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.
  */
@@ -89,8 +89,8 @@ extern DECLSPEC SDL_TouchID *SDLCALL SDL_GetTouchDevices(int *count);
  * You do not own the returned string, do not modify or free it.
  *
  * \param touchID the touch device instance ID.
- * \returns touch device name, or NULL on error; call SDL_GetError() for
- *          more details.
+ * \returns touch device name, or NULL on error; call SDL_GetError() for more
+ *          details.
  *
  * \since This function is available since SDL 3.0.0.
  */

include/SDL3/SDL_video.h

@@ -750,7 +750,8 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindow(const char *title, int w, i
  * input events. - 'SDL_WINDOW_POPUP_MENU': The popup window is a popup menu.
  * The topmost popup menu will implicitly gain the keyboard focus.
  *
- * The following flags are not relevant to popup window creation and will be ignored:
+ * The following flags are not relevant to popup window creation and will be
+ * ignored:
  *
  * - 'SDL_WINDOW_MINIMIZED'
  * - 'SDL_WINDOW_MAXIMIZED'
@@ -803,45 +804,63 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreatePopupWindow(SDL_Window *parent, in
  *
  * - "always-on-top" (boolean) - true if the window should be always on top
  * - "borderless" (boolean) - true if the window has no window decoration
- * - "focusable" (boolean) - true if the window should accept keyboard input (defaults true)
- * - "fullscreen" (boolean) - true if the window should start in fullscreen mode at desktop resolution
+ * - "focusable" (boolean) - true if the window should accept keyboard input
+ *   (defaults true)
+ * - "fullscreen" (boolean) - true if the window should start in fullscreen
+ *   mode at desktop resolution
  * - "height" (number) - the height of the window
  * - "hidden" (boolean) - true if the window should start hidden
- * - "high-pixel-density" (boolean) - true if the window uses a high pixel density buffer if possible
+ * - "high-pixel-density" (boolean) - true if the window uses a high pixel
+ *   density buffer if possible
  * - "maximized" (boolean) - true if the window should start maximized
  * - "menu" (boolean) - true if the window is a popup menu
  * - "metal" (string) - true if the window will be used with Metal rendering
  * - "minimized" (boolean) - true if the window should start minimized
- * - "mouse-grabbed" (boolean) - true if the window starts with grabbed mouse focus
- * - "opengl" (boolean) - true if the window will be used with OpenGL rendering
- * - "parent" (pointer) - an SDL_Window that will be the parent of this window, required for windows with the "toolip" and "menu" properties
+ * - "mouse-grabbed" (boolean) - true if the window starts with grabbed mouse
+ *   focus
+ * - "opengl" (boolean) - true if the window will be used with OpenGL
+ *   rendering
+ * - "parent" (pointer) - an SDL_Window that will be the parent of this
+ *   window, required for windows with the "toolip" and "menu" properties
  * - "resizable" (boolean) - true if the window should be resizable
  * - "title" (string) - the title of the window, in UTF-8 encoding
- * - "transparent" (string) - true if the window show transparent in the areas with alpha of 0
+ * - "transparent" (string) - true if the window show transparent in the areas
+ *   with alpha of 0
  * - "tooltip" (boolean) - true if the window is a tooltip
- * - "utility" (boolean) - true if the window is a utility window, not showing in the task bar and window list
+ * - "utility" (boolean) - true if the window is a utility window, not showing
+ *   in the task bar and window list
  * - "vulkan" (string) - true if the window will be used with Vulkan rendering
  * - "width" (number) - the width of the window
- * - "x" (number) - the x position of the window, or `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is relative to the parent for windows with the "parent" property set.
- * - "y" (number) - the y position of the window, or `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is relative to the parent for windows with the "parent" property set.
+ * - "x" (number) - the x position of the window, or `SDL_WINDOWPOS_CENTERED`,
+ *   defaults to `SDL_WINDOWPOS_UNDEFINED`. This is relative to the parent for
+ *   windows with the "parent" property set.
+ * - "y" (number) - the y position of the window, or `SDL_WINDOWPOS_CENTERED`,
+ *   defaults to `SDL_WINDOWPOS_UNDEFINED`. This is relative to the parent for
+ *   windows with the "parent" property set.
  *
  * On macOS:
  *
- * - "cocoa.window" (pointer) - the (__unsafe_unretained) NSWindow associated with the window, if you want to wrap an existing window.
- * - "cocoa.view" (pointer) - the (__unsafe_unretained) NSView associated with the window, defaults to [window contentView]
+ * - "cocoa.window" (pointer) - the (__unsafe_unretained) NSWindow associated
+ *   with the window, if you want to wrap an existing window.
+ * - "cocoa.view" (pointer) - the (__unsafe_unretained) NSView associated with
+ *   the window, defaults to [window contentView]
  *
  * On Windows:
  *
- * - "win32.hwnd" (pointer) - the HWND associated with the window, if you want to wrap an existing window.
- * - "win32.pixel_format_hwnd" (pointer) - optional, another window to share pixel format with, useful for OpenGL windows
+ * - "win32.hwnd" (pointer) - the HWND associated with the window, if you want
+ *   to wrap an existing window.
+ * - "win32.pixel_format_hwnd" (pointer) - optional, another window to share
+ *   pixel format with, useful for OpenGL windows
  *
  * On X11:
  *
- * - "x11.window" (number) - the X11 Window associated with the window, if you want to wrap an existing window.
+ * - "x11.window" (number) - the X11 Window associated with the window, if you
+ *   want to wrap an existing window.
  *
  * The SDL_Window is implicitly shown if the "hidden" property is not set.
  *
- * Windows with the "tooltip" and "menu" properties are popup windows and have the behaviors and guidelines outlined in `SDL_CreatePopupWindow()`.
+ * Windows with the "tooltip" and "menu" properties are popup windows and have
+ * the behaviors and guidelines outlined in `SDL_CreatePopupWindow()`.
  *
  * \param props the properties to use
  * \returns the window that was created or NULL on failure; call