diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h index bc1d9c47b6..f536ce352a 100644 --- a/include/SDL3/SDL_gamepad.h +++ b/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. */ diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h index b56f5e85d9..35f6141ba9 100644 --- a/include/SDL3/SDL_keyboard.h +++ b/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. diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h index d235e40ae4..af5889ba9d 100644 --- a/include/SDL3/SDL_render.h +++ b/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 diff --git a/include/SDL3/SDL_touch.h b/include/SDL3/SDL_touch.h index 26558c7dbf..58a8461c93 100644 --- a/include/SDL3/SDL_touch.h +++ b/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. */ diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index c12c1115b3..8f9e398bf4 100644 --- a/include/SDL3/SDL_video.h +++ b/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