From aa7baf63aa2cb8ca2d92f0bef32388fd7218762b Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Thu, 9 Nov 2023 20:11:23 -0500
Subject: [PATCH] Sync wiki -> headers.
---
include/SDL3/SDL_properties.h | 8 +++-
include/SDL3/SDL_render.h | 7 +--
include/SDL3/SDL_system.h | 10 ++++-
include/SDL3/SDL_video.h | 76 ++++++++++++++++----------------
include/SDL3/SDL_video_capture.h | 28 +++++++-----
5 files changed, 74 insertions(+), 55 deletions(-)
diff --git a/include/SDL3/SDL_properties.h b/include/SDL3/SDL_properties.h
index 588bdfc4ca49..17b280ae19e0 100644
--- a/include/SDL3/SDL_properties.h
+++ b/include/SDL3/SDL_properties.h
@@ -124,7 +124,8 @@ extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value);
/**
- * Set a property on a set of properties with a cleanup function that is called when the property is deleted
+ * Set a property on a set of properties with a cleanup function that is
+ * called when the property is deleted
*
* \param props the properties to modify
* \param name the name of the property to modify
@@ -147,7 +148,10 @@ extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, c
/**
* Get a property on a set of properties
*
- * By convention, the names of properties that SDL exposes on objects will start with "SDL.", and properties that SDL uses internally will start with "SDL.internal.". These should be considered read-only and should not be modified by applications.
+ * By convention, the names of properties that SDL exposes on objects will
+ * start with "SDL.", and properties that SDL uses internally will start with
+ * "SDL.internal.". These should be considered read-only and should not be
+ * modified by applications.
*
* \param props the properties to query
* \param name the name of the property to query
diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h
index 5b745b54eac1..73c2c40cf8bf 100644
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@@ -309,11 +309,12 @@ 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" - the IDirect3DDevice9 associated with the renderer
+ * The following properties are provided by SDL: "SDL.renderer.d3d9.device" -
+ * the IDirect3DDevice9 associated with the renderer
* "SDL.renderer.d3d11.device" - the ID3D11Device associated with the renderer
* "SDL.renderer.d3d12.device" - the ID3D12Device associated with the renderer
- * "SDL.renderer.d3d12.command_queue" - the ID3D12CommandQueue associated with the renderer
+ * "SDL.renderer.d3d12.command_queue" - the ID3D12CommandQueue associated with
+ * the renderer
*
* \param renderer the rendering context
* \returns a valid property ID on success or 0 on failure; call
diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index a2cd27d8704c..04b2cce56f06 100644
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@@ -47,10 +47,13 @@ extern "C" {
typedef struct tagMSG MSG;
typedef SDL_bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg);
+
/**
* Set a callback for every Windows message, run before TranslateMessage().
*
- * The callback may modify the message, and should return SDL_TRUE if the message should continue to be processed, or SDL_FALSE to prevent further processing.
+ * The callback may modify the message, and should return SDL_TRUE if the
+ * message should continue to be processed, or SDL_FALSE to prevent further
+ * processing.
*
* \param callback The SDL_WindowsMessageHook function to call.
* \param userdata a pointer to pass to every iteration of `callback`
@@ -106,10 +109,13 @@ extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo(SDL_DisplayID displayID,
typedef union _XEvent XEvent;
typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);
+
/**
* Set a callback for every X11 event
*
- * The callback may modify the event, and should return SDL_TRUE if the event should continue to be processed, or SDL_FALSE to prevent further processing.
+ * The callback may modify the event, and should return SDL_TRUE if the event
+ * should continue to be processed, or SDL_FALSE to prevent further
+ * processing.
*
* \param callback The SDL_X11EventHook function to call.
* \param userdata a pointer to pass to every iteration of `callback`
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index 8c89fae443a2..8a466a68b4c9 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -936,53 +936,53 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetWindowParent(SDL_Window *window);
*
* The following properties are provided by SDL:
*
- * On Android:
- * "SDL.window.android.window" - the ANativeWindow associated with the window
- * "SDL.window.android.surface" - the EGLSurface associated with the window
+ * On Android: "SDL.window.android.window" - the ANativeWindow associated with
+ * the window "SDL.window.android.surface" - the EGLSurface associated with
+ * the window
*
- * On iOS:
- * "SDL.window.uikit.window" - the (__unsafe_unretained) UIWindow associated with the window
- * "SDL.window.uikit.metal_view_tag" - the NSInteger tag assocated with metal views on the window
+ * On iOS: "SDL.window.uikit.window" - the (__unsafe_unretained) UIWindow
+ * associated with the window "SDL.window.uikit.metal_view_tag" - the
+ * NSInteger tag assocated with metal views on the window
*
- * On KMS/DRM:
- * "SDL.window.kmsdrm.dev_index" - the device index associated with the window (e.g. the X in /dev/dri/cardX)
- * "SDL.window.kmsdrm.drm_fd" - the DRM FD associated with the window
- * "SDL.window.kmsdrm.gbm_dev" - the GBM device associated with the window
+ * On KMS/DRM: "SDL.window.kmsdrm.dev_index" - the device index associated
+ * with the window (e.g. the X in /dev/dri/cardX) "SDL.window.kmsdrm.drm_fd" -
+ * the DRM FD associated with the window "SDL.window.kmsdrm.gbm_dev" - the GBM
+ * device associated with the window
*
- * On macOS:
- * "SDL.window.cocoa.window" - the (__unsafe_unretained) NSWindow associated with the window
- * "SDL.window.cocoa.metal_view_tag" - the NSInteger tag assocated with metal views on the window
+ * On macOS: "SDL.window.cocoa.window" - the (__unsafe_unretained) NSWindow
+ * associated with the window "SDL.window.cocoa.metal_view_tag" - the
+ * NSInteger tag assocated with metal views on the window
*
- * On Vivante:
- * "SDL.window.vivante.display" - the EGLNativeDisplayType associated with the window
- * "SDL.window.vivante.window" - the EGLNativeWindowType associated with the window
- * "SDL.window.vivante.surface" - the EGLSurface associated with the window
+ * On Vivante: "SDL.window.vivante.display" - the EGLNativeDisplayType
+ * associated with the window "SDL.window.vivante.window" - the
+ * EGLNativeWindowType associated with the window "SDL.window.vivante.surface"
+ * - the EGLSurface associated with the window
*
- * On UWP:
- * "SDL.window.winrt.window" - the IInspectable CoreWindow associated with the window
+ * On UWP: "SDL.window.winrt.window" - the IInspectable CoreWindow associated
+ * with the window
*
- * On Windows:
- * "SDL.window.win32.hwnd" - the HWND associated with the window
+ * On Windows: "SDL.window.win32.hwnd" - the HWND associated with the window
* "SDL.window.win32.hdc" - the HDC associated with the window
* "SDL.window.win32.instance" - the HINSTANCE associated with the window
*
- * On Wayland:
- * "SDL.window.wayland.registry" - the wl_registry associated with the window
- * "SDL.window.wayland.display" - the wl_display associated with the window
- * "SDL.window.wayland.surface" - the wl_surface associated with the window
- * "SDL.window.wayland.egl_window" - the wl_egl_window associated with the window
- * "SDL.window.wayland.xdg_surface" - the xdg_surface associated with the window
- * "SDL.window.wayland.xdg_toplevel" - the xdg_toplevel role associated with the window
- * "SDL.window.wayland.xdg_popup" - the xdg_popup role associated with the window
- * "SDL.window.wayland.xdg_positioner" - 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.
- *
- * On X11:
- * "SDL.window.x11.display" - the X11 Display associated with the window
- * "SDL.window.x11.screen" - the screen number associated with the window
- * "SDL.window.x11.window" - the X11 Window associated with the window
+ * On Wayland: "SDL.window.wayland.registry" - the wl_registry associated with
+ * the window "SDL.window.wayland.display" - the wl_display associated with
+ * the window "SDL.window.wayland.surface" - the wl_surface associated with
+ * the window "SDL.window.wayland.egl_window" - the wl_egl_window associated
+ * with the window "SDL.window.wayland.xdg_surface" - the xdg_surface
+ * associated with the window "SDL.window.wayland.xdg_toplevel" - the
+ * xdg_toplevel role associated with the window "SDL.window.wayland.xdg_popup"
+ * - the xdg_popup role associated with the window
+ * "SDL.window.wayland.xdg_positioner" - 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.
+ *
+ * On X11: "SDL.window.x11.display" - the X11 Display associated with the
+ * window "SDL.window.x11.screen" - the screen number associated with the
+ * window "SDL.window.x11.window" - the X11 Window associated with the window
*
* \param window the window to query
* \returns a valid property ID on success or 0 on failure; call
diff --git a/include/SDL3/SDL_video_capture.h b/include/SDL3/SDL_video_capture.h
index 3d3ce7e64198..12baaf5a4605 100644
--- a/include/SDL3/SDL_video_capture.h
+++ b/include/SDL3/SDL_video_capture.h
@@ -126,8 +126,8 @@ extern DECLSPEC SDL_VideoCaptureDeviceID *SDLCALL SDL_GetVideoCaptureDevices(int
* Open a Video Capture device
*
* \param instance_id the video capture device instance ID
- * \returns device, or NULL on failure; call
- * SDL_GetError() for more information.
+ * \returns device, or NULL on failure; call SDL_GetError() for more
+ * information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -165,8 +165,8 @@ extern DECLSPEC int SDLCALL SDL_SetVideoCaptureSpec(SDL_VideoCaptureDevice *devi
* \param desired desired video capture spec
* \param obtained obtained video capture spec
* \param allowed_changes allow changes or not
- * \returns device, or NULL on failure; call
- * SDL_GetError() for more information.
+ * \returns device, or NULL on failure; call SDL_GetError() for more
+ * information.
*
* \since This function is available since SDL 3.0.0.
*
@@ -178,6 +178,7 @@ extern DECLSPEC SDL_VideoCaptureDevice *SDLCALL SDL_OpenVideoCaptureWithSpec(SDL
const SDL_VideoCaptureSpec *desired,
SDL_VideoCaptureSpec *obtained,
int allowed_changes);
+
/**
* Get device name
*
@@ -208,6 +209,7 @@ extern DECLSPEC int SDLCALL SDL_GetVideoCaptureSpec(SDL_VideoCaptureDevice *devi
/**
* Get frame format of video capture device.
+ *
* The value can be used to fill SDL_VideoCaptureSpec structure.
*
* \param device opened video capture device
@@ -240,6 +242,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumVideoCaptureFormats(SDL_VideoCaptureDevice
/**
* Get frame sizes of the device and the specified input format.
+ *
* The value can be used to fill SDL_VideoCaptureSpec structure.
*
* \param device opened video capture device
@@ -300,11 +303,13 @@ extern DECLSPEC int SDLCALL SDL_StartVideoCapture(SDL_VideoCaptureDevice *device
/**
* Acquire a frame.
- * The frame is a memory pointer to the image data, whose size and format
- * are given by the the obtained spec.
*
- * Non blocking API. If there is a frame available, frame->num_planes is non 0.
- * If frame->num_planes is 0 and returned code is 0, there is no frame at that time.
+ * The frame is a memory pointer to the image data, whose size and format are
+ * given by the the obtained spec.
+ *
+ * Non blocking API. If there is a frame available, frame->num_planes is non
+ * 0. If frame->num_planes is 0 and returned code is 0, there is no frame at
+ * that time.
*
* After used, the frame should be released with SDL_ReleaseVideoCaptureFrame
*
@@ -320,7 +325,9 @@ extern DECLSPEC int SDLCALL SDL_StartVideoCapture(SDL_VideoCaptureDevice *device
extern DECLSPEC int SDLCALL SDL_AcquireVideoCaptureFrame(SDL_VideoCaptureDevice *device, SDL_VideoCaptureFrame *frame);
/**
- * Release a frame. Let the back-end re-use the internal buffer for video capture.
+ * Release a frame.
+ *
+ * Let the back-end re-use the internal buffer for video capture.
*
* All acquired frames should be released before closing the device.
*
@@ -349,7 +356,8 @@ extern DECLSPEC int SDLCALL SDL_ReleaseVideoCaptureFrame(SDL_VideoCaptureDevice
extern DECLSPEC int SDLCALL SDL_StopVideoCapture(SDL_VideoCaptureDevice *device);
/**
- * Use this function to shut down video_capture processing and close the video_capture device.
+ * Use this function to shut down video_capture processing and close the
+ * video_capture device.
*
* \param device opened video capture device
*