From 8766aa39d6cd2969793f7fb94b48934732afc661 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Mon, 13 Nov 2023 13:03:42 -0500
Subject: [PATCH] Sync wiki -> headers.
---
include/SDL3/SDL_pen.h | 76 ++++++++++++++++-------------------
include/SDL3/SDL_properties.h | 31 +++++++++-----
include/SDL3/SDL_render.h | 5 +++
include/SDL3/SDL_video.h | 21 ++++++++--
4 files changed, 78 insertions(+), 55 deletions(-)
diff --git a/include/SDL3/SDL_pen.h b/include/SDL3/SDL_pen.h
index e5e6731ee5a0..9d73406cf246 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 eedc178806f4..4e535aaacce7 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 72cb5d263d81..86a2abb1a050 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 262409f9e7c6..b75ffda4e1e3 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