diff --git a/include/SDL3/SDL_pen.h b/include/SDL3/SDL_pen.h index e5e6731ee5..9d73406cf2 100644 --- a/include/SDL3/SDL_pen.h +++ b/include/SDL3/SDL_pen.h @@ -147,15 +147,13 @@ typedef enum /** * Retrieves all pens that are connected to the system. * - * Yields an array of ::SDL_PenID values. These identify and track pens throughout a session. - * To track pens across sessions (program restart), use ::SDL_GUID . + * Yields an array of ::SDL_PenID values. These identify and track pens + * throughout a session. To track pens across sessions (program restart), use + * ::SDL_GUID . * - * \param[out] count The number of pens in the array (number of array elements minus 1, i.e., not - * counting the terminator 0). - * - * \returns A 0 terminated array of ::SDL_PenID values, or NULL on error. - * The array must be freed with ::SDL_free(). - * On a NULL return, ::SDL_GetError() is set. + * \returns A 0 terminated array of ::SDL_PenID values, or NULL on error. The + * array must be freed with ::SDL_free(). On a NULL return, + * ::SDL_GetError() is set. * * \since This function is available since SDL 3.TBD */ @@ -168,15 +166,11 @@ extern DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count); * default values. * * \param instance_id The pen to query. - * \param[out] x Out-mode parameter for pen x coordinate. May be NULL. - * \param[out] y Out-mode parameter for pen y coordinate. May be NULL. - * \param[out] axes Out-mode parameter for axis information. May be null. The axes are in the same order as for - * ::SDL_PenAxis . * \param num_axes Maximum number of axes to write to "axes". - * - * \returns a bit mask with the current pen button states (::SDL_BUTTON_LMASK etc.), - * possibly ::SDL_PEN_DOWN_MASK, and exactly one of - * ::SDL_PEN_INK_MASK or ::SDL_PEN_ERASER_MASK , or 0 on error (see ::SDL_GetError()). + * \returns a bit mask with the current pen button states (::SDL_BUTTON_LMASK + * etc.), possibly ::SDL_PEN_DOWN_MASK, and exactly one of + * ::SDL_PEN_INK_MASK or ::SDL_PEN_ERASER_MASK , or 0 on error (see + * ::SDL_GetError()). * * \since This function is available since SDL 3.TBD */ @@ -186,12 +180,12 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x, * Retrieves an ::SDL_PenID for the given ::SDL_GUID. * * \param guid A pen GUID. - * - * \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching SDL_PenID. + * \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching + * SDL_PenID. * * \since This function is available since SDL 3.TBD * - * \sa SDL_GUID() + * \sa SDL_GUID */ extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid); @@ -199,25 +193,24 @@ extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid); * Retrieves the ::SDL_GUID for a given ::SDL_PenID. * * \param instance_id The pen to query. - * * \returns The corresponding pen GUID; persistent across multiple sessions. - * If "instance_id" is ::SDL_PEN_INVALID, returns an all-zeroes GUID. + * If "instance_id" is ::SDL_PEN_INVALID, returns an all-zeroes GUID. * * \since This function is available since SDL 3.TBD * - * \sa SDL_PenForID() + * \sa SDL_PenForID */ extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id); /** * Checks whether a pen is still attached. * - * If a pen is detached, it will not show up for ::SDL_GetPens(). - * Other operations will still be available but may return default values. + * If a pen is detached, it will not show up for ::SDL_GetPens(). Other + * operations will still be available but may return default values. * * \param instance_id A pen ID. - * \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is attached, or - * SDL_FALSE otherwise. + * \returns SDL_TRUE if "instance_id" is valid and the corresponding pen is + * attached, or SDL_FALSE otherwise. * * \since This function is available since SDL 3.TBD */ @@ -227,14 +220,13 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id); * Retrieves a human-readable description for a ::SDL_PenID. * * \param instance_id The pen to query. - * - * \returns A string that contains the name of the pen, intended for human consumption. - * The string might or might not be localised, depending on platform settings. - * It is not guaranteed to be unique; use ::SDL_GetPenGUID() for (best-effort) - * unique identifiers. - * The pointer is managed by the SDL pen subsystem and must not be deallocated. - * The pointer remains valid until SDL is shut down. - * Returns NULL on error (cf. ::SDL_GetError()) + * \returns A string that contains the name of the pen, intended for human + * consumption. The string might or might not be localised, depending + * on platform settings. It is not guaranteed to be unique; use + * ::SDL_GetPenGUID() for (best-effort) unique identifiers. The + * pointer is managed by the SDL pen subsystem and must not be + * deallocated. The pointer remains valid until SDL is shut down. + * Returns NULL on error (cf. ::SDL_GetError()) * * \since This function is available since SDL 3.TBD */ @@ -254,10 +246,7 @@ typedef struct SDL_PenCapabilityInfo * Retrieves capability flags for a given ::SDL_PenID. * * \param instance_id The pen to query. - * \param[out] capabilities Detail information about pen capabilities, such as the number of buttons - * - * \returns a set of capability flags, cf. SDL_PEN_CAPABILITIES. Returns 0 on error - * (cf. ::SDL_GetError()) + * \returns a set of capability flags, cf. \link SDL_PEN_CAPABILITIES * * \since This function is available since SDL 3.TBD */ @@ -267,10 +256,13 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL * Retrieves the pen type for a given ::SDL_PenID. * * \param instance_id The pen to query. - * \returns The corresponding pen type (cf. ::SDL_PenSubtype) or 0 on error. Note that the pen type does not - * dictate whether the pen tip is ::SDL_PEN_TIP_INK or ::SDL_PEN_TIP_ERASER; to determine whether a pen - * is being used for drawing or in eraser mode, check either the pen tip on ::SDL_EVENT_PEN_DOWN, or the - * flag ::SDL_PEN_ERASER_MASK in the pen state. + * \returns The corresponding pen type (cf. ::SDL_PenSubtype) or 0 on error. + * Note that the pen type does not dictate whether the pen tip is + * ::SDL_PEN_TIP_INK or ::SDL_PEN_TIP_ERASER; to determine whether a + * pen is being used for drawing or in eraser mode, check either the + * pen tip on ::SDL_EVENT_PEN_DOWN, or the flag ::SDL_PEN_ERASER_MASK + * in the pen state. + * * \since This function is available since SDL 3.TBD */ extern DECLSPEC SDL_PenSubtype SDLCALL SDL_GetPenType(SDL_PenID instance_id); diff --git a/include/SDL3/SDL_properties.h b/include/SDL3/SDL_properties.h index eedc178806..4e535aaacc 100644 --- a/include/SDL3/SDL_properties.h +++ b/include/SDL3/SDL_properties.h @@ -231,7 +231,8 @@ extern DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const * * \param props the properties to query * \param name the name of the property to query - * \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is not set. + * \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is + * not set. * * \threadsafety It is safe to call this function from any thread. * @@ -250,7 +251,8 @@ extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID pr * \param props the properties to query * \param name the name of the property to query * \param default_value the default value of the property - * \returns the value of the property, or `default_value` if it is not set or not a pointer property. + * \returns the value of the property, or `default_value` if it is not set or + * not a pointer property. * * \threadsafety It is safe to call this function from any thread, although * the data returned is not protected and could potentially be @@ -271,7 +273,8 @@ extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char * \param props the properties to query * \param name the name of the property to query * \param default_value the default value of the property - * \returns the value of the property, or `default_value` if it is not set or not a string property. + * \returns the value of the property, or `default_value` if it is not set or + * not a string property. * * \threadsafety It is safe to call this function from any thread. * @@ -285,12 +288,14 @@ extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props /** * Get a number property on a set of properties * - * You can use SDL_GetPropertyType() to query whether the property exists and is a number property. + * You can use SDL_GetPropertyType() to query whether the property exists and + * is a number property. * * \param props the properties to query * \param name the name of the property to query * \param default_value the default value of the property - * \returns the value of the property, or `default_value` if it is not set or not a number property. + * \returns the value of the property, or `default_value` if it is not set or + * not a number property. * * \threadsafety It is safe to call this function from any thread. * @@ -304,12 +309,14 @@ extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, con /** * Get a floating point property on a set of properties * - * You can use SDL_GetPropertyType() to query whether the property exists and is a floating point property. + * You can use SDL_GetPropertyType() to query whether the property exists and + * is a floating point property. * * \param props the properties to query * \param name the name of the property to query * \param default_value the default value of the property - * \returns the value of the property, or `default_value` if it is not set or not a float property. + * \returns the value of the property, or `default_value` if it is not set or + * not a float property. * * \threadsafety It is safe to call this function from any thread. * @@ -323,12 +330,14 @@ extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const /** * Get a boolean property on a set of properties * - * You can use SDL_GetPropertyType() to query whether the property exists and is a boolean property. + * You can use SDL_GetPropertyType() to query whether the property exists and + * is a boolean property. * * \param props the properties to query * \param name the name of the property to query * \param default_value the default value of the property - * \returns the value of the property, or `default_value` if it is not set or not a float property. + * \returns the value of the property, or `default_value` if it is not set or + * not a float property. * * \threadsafety It is safe to call this function from any thread. * @@ -356,10 +365,12 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, extern DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name); typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name); + /** * Enumerate the properties on a set of properties * - * The callback function is called for each property on the set of properties. The properties are locked during enumeration. + * The callback function is called for each property on the set of properties. + * The properties are locked during enumeration. * * \param props the properties to query * \param callback the function to call for each property diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h index 72cb5d263d..86a2abb1a0 100644 --- a/include/SDL3/SDL_render.h +++ b/include/SDL3/SDL_render.h @@ -310,6 +310,7 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_Rend * Get the properties associated with a renderer. * * The following properties are provided by SDL: + * * ``` * "SDL.renderer.d3d9.device" (pointer) - the IDirect3DDevice9 associated with the renderer * "SDL.renderer.d3d11.device" (pointer) - the ID3D11Device associated with the renderer @@ -423,6 +424,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer * * The following properties are provided by SDL: * * 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 @@ -430,6 +432,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer * * ``` * * 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 @@ -437,6 +440,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer * * ``` * * With the opengl renderer: + * * ``` * "SDL.texture.opengl.texture" (number) - the GLuint texture associated with the texture * "SDL.texture.opengl.texture_u" (number) - the GLuint texture associated with the U plane of a YUV texture @@ -446,6 +450,7 @@ extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer * * ``` * * 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 diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index 262409f9e7..b75ffda4e1 100644 --- a/include/SDL3/SDL_video.h +++ b/include/SDL3/SDL_video.h @@ -868,28 +868,33 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindowWithPosition(const char *tit extern DECLSPEC SDL_Window *SDLCALL SDL_CreatePopupWindow(SDL_Window *parent, int offset_x, int offset_y, int w, int h, Uint32 flags); /** - * Create an SDL window from properties representing an existing native window. + * Create an SDL window from properties representing an existing native + * window. * * These are the supported properties: * * On macOS: + * * ``` * "cocoa.window" (pointer) - the (__unsafe_unretained) NSWindow associated with the window * "cocoa.view" (pointer) - optional, the (__unsafe_unretained) NSView associated with the window, defaults to [window contentView] * ``` * * On Windows: + * * ``` * "win32.hwnd" (pointer) - the HWND associated with the 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 * ``` * * On all platforms: + * * ``` * "opengl" (boolean) - optional, true if the window will be used with OpenGL rendering * "vulkan" (boolean) - optional, true if the window will be used with Vulkan rendering @@ -957,18 +962,21 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window); * The following properties are provided by SDL: * * On Android: + * * ``` * "SDL.window.android.window" (pointer) - the ANativeWindow associated with the window * "SDL.window.android.surface" (pointer) - the EGLSurface associated with the window * ``` * * On iOS: + * * ``` * "SDL.window.uikit.window" (pointer) - the (__unsafe_unretained) UIWindow associated with the window * "SDL.window.uikit.metal_view_tag" (number) - the NSInteger tag assocated with metal views on the window * ``` * * On KMS/DRM: + * * ``` * "SDL.window.kmsdrm.dev_index" (number) - the device index associated with the window (e.g. the X in /dev/dri/cardX) * "SDL.window.kmsdrm.drm_fd" (number) - the DRM FD associated with the window @@ -976,12 +984,14 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window); * ``` * * On macOS: + * * ``` * "SDL.window.cocoa.window" (pointer) - the (__unsafe_unretained) NSWindow associated with the window * "SDL.window.cocoa.metal_view_tag" (number) - the NSInteger tag assocated with metal views on the window * ``` * * On Vivante: + * * ``` * "SDL.window.vivante.display" (pointer) - the EGLNativeDisplayType associated with the window * "SDL.window.vivante.window" (pointer) - the EGLNativeWindowType associated with the window @@ -989,11 +999,13 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window); * ``` * * On UWP: + * * ``` * "SDL.window.winrt.window" (pointer) - the IInspectable CoreWindow associated with the window * ``` * * On Windows: + * * ``` * "SDL.window.win32.hwnd" (pointer) - the HWND associated with the window * "SDL.window.win32.hdc" (pointer) - the HDC associated with the window @@ -1001,6 +1013,7 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window); * ``` * * On Wayland: + * * ``` * "SDL.window.wayland.registry" (pointer) - the wl_registry associated with the window * "SDL.window.wayland.display" (pointer) - the wl_display associated with the window @@ -1012,10 +1025,12 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window); * "SDL.window.wayland.xdg_positioner" (pointer) - the xdg_positioner associated with the window, in popup mode * ``` * - * Note: The xdg_* window objects do not internally persist across window show/hide calls. - * They will be null if the window is hidden and must be queried each time it is shown. + * Note: The xdg_* window objects do not internally persist across window + * show/hide calls. They will be null if the window is hidden and must be + * queried each time it is shown. * * On X11: + * * ``` * "SDL.window.x11.display" (pointer) - the X11 Display associated with the window * "SDL.window.x11.screen" (number) - the screen number associated with the window