From 3fa0537565514946ac5dbfb2f88cb6a1ae014d9e Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Mon, 16 Dec 2024 06:13:48 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
[ci skip]
---
include/SDL3/SDL_camera.h | 26 +++++++++++++-------------
include/SDL3/SDL_clipboard.h | 33 ++++++++++++++++-----------------
include/SDL3/SDL_cpuinfo.h | 3 ++-
include/SDL3/SDL_endian.h | 7 ++++---
include/SDL3/SDL_events.h | 14 +++++++-------
include/SDL3/SDL_joystick.h | 4 ++--
include/SDL3/SDL_keycode.h | 4 ++--
include/SDL3/SDL_loadso.h | 4 ++--
include/SDL3/SDL_main.h | 8 ++++----
include/SDL3/SDL_scancode.h | 4 ++--
10 files changed, 54 insertions(+), 53 deletions(-)
diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h
index 849684aaf8572..c3611f0721e32 100644
--- a/include/SDL3/SDL_camera.h
+++ b/include/SDL3/SDL_camera.h
@@ -31,22 +31,22 @@
*
* Several platforms will alert the user if an app tries to access a camera,
* and some will present a UI asking the user if your application should be
- * allowed to obtain images at all, which they can deny. A successfully
- * opened camera will not provide images until permission is granted.
- * Applications, after opening a camera device, can see if they were granted
- * access by either polling with the SDL_GetCameraPermissionState() function,
- * or waiting for an SDL_EVENT_CAMERA_DEVICE_APPROVED or
- * SDL_EVENT_CAMERA_DEVICE_DENIED event. Platforms that don't have any
- * user approval process will report approval immediately.
+ * allowed to obtain images at all, which they can deny. A successfully opened
+ * camera will not provide images until permission is granted. Applications,
+ * after opening a camera device, can see if they were granted access by
+ * either polling with the SDL_GetCameraPermissionState() function, or waiting
+ * for an SDL_EVENT_CAMERA_DEVICE_APPROVED or SDL_EVENT_CAMERA_DEVICE_DENIED
+ * event. Platforms that don't have any user approval process will report
+ * approval immediately.
*
* Note that SDL cameras only provide video as individual frames; they will
* not provide full-motion video encoded in a movie file format, although an
- * app is free to encode the acquired frames into any format it likes. It
- * also does not provide audio from the camera hardware through this API;
- * not only do many webcams not have microphones at all, many people--from
- * streamers to people on Zoom calls--will want to use a separate microphone
- * regardless of the camera. In any case, recorded audio will be available
- * through SDL's audio API no matter what hardware provides the microphone.
+ * app is free to encode the acquired frames into any format it likes. It also
+ * does not provide audio from the camera hardware through this API; not only
+ * do many webcams not have microphones at all, many people--from streamers to
+ * people on Zoom calls--will want to use a separate microphone regardless of
+ * the camera. In any case, recorded audio will be available through SDL's
+ * audio API no matter what hardware provides the microphone.
*
* ## Camera gotchas
*
diff --git a/include/SDL3/SDL_clipboard.h b/include/SDL3/SDL_clipboard.h
index f6be9d8d5ebfc..448cb4a53f560 100644
--- a/include/SDL3/SDL_clipboard.h
+++ b/include/SDL3/SDL_clipboard.h
@@ -29,19 +29,18 @@
*
* ## Basic use (text)
*
- * Obtaining and publishing simple text to the system clipboard is as easy
- * as calling SDL_GetClipboardText() and SDL_SetClipboardText(),
- * respectively. These deal with C strings in UTF-8 encoding. Data
- * transmission and encoding conversion is completely managed by SDL.
+ * Obtaining and publishing simple text to the system clipboard is as easy as
+ * calling SDL_GetClipboardText() and SDL_SetClipboardText(), respectively.
+ * These deal with C strings in UTF-8 encoding. Data transmission and encoding
+ * conversion is completely managed by SDL.
*
* ## Clipboard callbacks (data other than text)
*
* Things get more complicated when the clipboard contains something other
- * than text. Not only can the system clipboard contain data of any type,
- * in some cases it can contain the same data in different formats! For
- * example, an image painting app might let the user copy a graphic to the
- * clipboard, and offers it in .BMP, .JPG, or .PNG format for other apps to
- * consume.
+ * than text. Not only can the system clipboard contain data of any type, in
+ * some cases it can contain the same data in different formats! For example,
+ * an image painting app might let the user copy a graphic to the clipboard,
+ * and offers it in .BMP, .JPG, or .PNG format for other apps to consume.
*
* Obtaining clipboard data ("pasting") like this is a matter of calling
* SDL_GetClipboardData() and telling it the mimetype of the data you want.
@@ -56,9 +55,9 @@
* rather the mimetypes it is willing to provide and a callback function.
* During the callback, the app will generate the data. This allows massive
* data sets to be provided to the clipboard, without any data being copied
- * before it is explicitly requested. More specifically, it allows an app
- * to offer data in multiple formats without providing a copy of all of
- * them upfront. If the app has an image that it could provide in PNG or JPG
+ * before it is explicitly requested. More specifically, it allows an app to
+ * offer data in multiple formats without providing a copy of all of them
+ * upfront. If the app has an image that it could provide in PNG or JPG
* format, it doesn't have to encode it to either of those unless and until
* something tries to paste it.
*
@@ -67,11 +66,11 @@
* The X11 and Wayland video targets have a concept of the "primary selection"
* in addition to the usual clipboard. This is generally highlighted (but not
* explicitly copied) text from various apps. SDL offers APIs for this through
- * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText().
- * SDL offers these APIs on platforms without this concept, too, but only so
- * far that it will keep a copy of a string that the app sets for later
- * retrieval; the operating system will not ever attempt to change the
- * string externally if it doesn't support a primary selection.
+ * SDL_GetPrimarySelectionText() and SDL_SetPrimarySelectionText(). SDL offers
+ * these APIs on platforms without this concept, too, but only so far that it
+ * will keep a copy of a string that the app sets for later retrieval; the
+ * operating system will not ever attempt to change the string externally if
+ * it doesn't support a primary selection.
*/
#ifndef SDL_clipboard_h_
diff --git a/include/SDL3/SDL_cpuinfo.h b/include/SDL3/SDL_cpuinfo.h
index 94e366c23c78a..eca703aa1bdcc 100644
--- a/include/SDL3/SDL_cpuinfo.h
+++ b/include/SDL3/SDL_cpuinfo.h
@@ -33,7 +33,8 @@
* CPU instruction set checks, like SDL_HasSSE() and SDL_HasNEON(), are
* available on all platforms, even if they don't make sense (an ARM processor
* will never have SSE and an x86 processor will never have NEON, for example,
- * but these functions still exist and will simply return false in these cases).
+ * but these functions still exist and will simply return false in these
+ * cases).
*/
#ifndef SDL_cpuinfo_h_
diff --git a/include/SDL3/SDL_endian.h b/include/SDL3/SDL_endian.h
index d1c1173284612..86aa4aa6b052c 100644
--- a/include/SDL3/SDL_endian.h
+++ b/include/SDL3/SDL_endian.h
@@ -28,13 +28,14 @@
* SDL_Swap32, SDL_Swap64, SDL_SwapFloat), or they swap to/from the system's
* native byte order (SDL_Swap16LE, SDL_Swap16BE, SDL_Swap32LE, SDL_Swap32BE,
* SDL_Swap32LE, SDL_Swap32BE, SDL_SwapFloatLE, SDL_SwapFloatBE). In the
- * latter case, the functionality is provided by macros that become no-ops
- * if a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE
+ * latter case, the functionality is provided by macros that become no-ops if
+ * a swap isn't necessary: on an x86 (littleendian) processor, SDL_Swap32LE
* does nothing, but SDL_Swap32BE reverses the bytes of the data. On a PowerPC
* processor (bigendian), the macros behavior is reversed.
*
* The swap routines are inline functions, and attempt to use compiler
- * intrinsics, inline assembly, and other magic to make byteswapping efficient.
+ * intrinsics, inline assembly, and other magic to make byteswapping
+ * efficient.
*/
#ifndef SDL_endian_h_
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index 596bdd124b681..c55154bea0e0c 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -25,9 +25,9 @@
* Event queue management.
*
* It's extremely common--often required--that an app deal with SDL's event
- * queue. Almost all useful information about interactions with the real
- * world flow through here: the user interacting with the computer and app,
- * hardware coming and going, the system changing in some way, etc.
+ * queue. Almost all useful information about interactions with the real world
+ * flow through here: the user interacting with the computer and app, hardware
+ * coming and going, the system changing in some way, etc.
*
* An app generally takes a moment, perhaps at the start of a new frame, to
* examine any events that have occured since the last time and process or
@@ -43,10 +43,10 @@
* beneficial for certain types of programs on low-power hardware. One may
* also call SDL_AddEventWatch() to set a callback when new events arrive.
*
- * The app is free to generate their own events, too: SDL_PushEvent allows
- * the app to put events onto the queue for later retrieval;
- * SDL_RegisterEvents can guarantee that these events have a type that isn't
- * in use by other parts of the system.
+ * The app is free to generate their own events, too: SDL_PushEvent allows the
+ * app to put events onto the queue for later retrieval; SDL_RegisterEvents
+ * can guarantee that these events have a type that isn't in use by other
+ * parts of the system.
*/
#ifndef SDL_events_h_
diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h
index f10b3ec729c6c..580000206b81e 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -25,8 +25,8 @@
* SDL joystick support.
*
* This is the lower-level joystick handling. If you want the simpler option,
- * where what each button does is well-defined, you should use the gamepad
- * API instead.
+ * where what each button does is well-defined, you should use the gamepad API
+ * instead.
*
* The term "instance_id" is the current instantiation of a joystick device in
* the system, if the joystick is removed and then re-inserted then it will
diff --git a/include/SDL3/SDL_keycode.h b/include/SDL3/SDL_keycode.h
index d1c474e3ae113..3d7723d1346ca 100644
--- a/include/SDL3/SDL_keycode.h
+++ b/include/SDL3/SDL_keycode.h
@@ -24,8 +24,8 @@
*
* Defines constants which identify keyboard keys and modifiers.
*
- * Please refer to the Best Keyboard Practices document for
- * details on what this information means and how best to use it.
+ * Please refer to the Best Keyboard Practices document for details on what
+ * this information means and how best to use it.
*
* https://wiki.libsdl.org/SDL3/BestKeyboardPractices
*/
diff --git a/include/SDL3/SDL_loadso.h b/include/SDL3/SDL_loadso.h
index 11991788dfcb2..027462fe55d43 100644
--- a/include/SDL3/SDL_loadso.h
+++ b/include/SDL3/SDL_loadso.h
@@ -49,8 +49,8 @@
* - Once a library is unloaded, all pointers into it obtained through
* SDL_LoadFunction() become invalid, even if the library is later reloaded.
* Don't unload a library if you plan to use these pointers in the future.
- * Notably: beware of giving one of these pointers to atexit(), since it
- * may call that pointer after the library unloads.
+ * Notably: beware of giving one of these pointers to atexit(), since it may
+ * call that pointer after the library unloads.
*/
#ifndef SDL_loadso_h_
diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h
index 152a2cc5c060c..fca557e5d74fe 100644
--- a/include/SDL3/SDL_main.h
+++ b/include/SDL3/SDL_main.h
@@ -35,12 +35,12 @@
*
* SDL will take care of platform specific details on how it gets called.
*
- * This is also where an app can be configured to use the main callbacks,
- * via the SDL_MAIN_USE_CALLBACKS macro.
+ * This is also where an app can be configured to use the main callbacks, via
+ * the SDL_MAIN_USE_CALLBACKS macro.
*
* This is a "single-header library," which is to say that including this
- * header inserts code into your program, and you should only include it
- * once in most cases. SDL.h does not include this header automatically.
+ * header inserts code into your program, and you should only include it once
+ * in most cases. SDL.h does not include this header automatically.
*
* For more information, see:
*
diff --git a/include/SDL3/SDL_scancode.h b/include/SDL3/SDL_scancode.h
index d0a0c2df62214..1259f80086c44 100644
--- a/include/SDL3/SDL_scancode.h
+++ b/include/SDL3/SDL_scancode.h
@@ -24,8 +24,8 @@
*
* Defines keyboard scancodes.
*
- * Please refer to the Best Keyboard Practices document for
- * details on what this information means and how best to use it.
+ * Please refer to the Best Keyboard Practices document for details on what
+ * this information means and how best to use it.
*
* https://wiki.libsdl.org/SDL3/BestKeyboardPractices
*/