From e044318a8e3a50675777d0440adead960f4cce6f Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 9 Apr 2024 00:49:23 -0400
Subject: [PATCH] Sync SDL3 wiki -> headers
---
include/SDL3/SDL_assert.h | 4 +-
include/SDL3/SDL_audio.h | 24 +-
include/SDL3/SDL_blendmode.h | 18 +-
include/SDL3/SDL_camera.h | 11 +-
include/SDL3/SDL_dialog.h | 3 +-
include/SDL3/SDL_events.h | 87 +-
include/SDL3/SDL_filesystem.h | 6 +-
include/SDL3/SDL_gamepad.h | 52 +-
include/SDL3/SDL_guid.h | 22 +-
include/SDL3/SDL_haptic.h | 406 ++++-----
include/SDL3/SDL_hidapi.h | 7 +-
include/SDL3/SDL_hints.h | 1507 ++++++++++++++++++++++-----------
include/SDL3/SDL_init.h | 6 +-
include/SDL3/SDL_iostream.h | 21 +-
include/SDL3/SDL_joystick.h | 6 +-
include/SDL3/SDL_keyboard.h | 5 +-
include/SDL3/SDL_locale.h | 8 +-
include/SDL3/SDL_log.h | 15 +-
include/SDL3/SDL_messagebox.h | 4 +-
include/SDL3/SDL_mouse.h | 6 +-
include/SDL3/SDL_mutex.h | 4 +-
include/SDL3/SDL_pen.h | 30 +-
include/SDL3/SDL_pixels.h | 24 +-
include/SDL3/SDL_rect.h | 19 +-
include/SDL3/SDL_render.h | 2 +-
include/SDL3/SDL_sensor.h | 16 +-
include/SDL3/SDL_stdinc.h | 20 +-
include/SDL3/SDL_surface.h | 28 +-
include/SDL3/SDL_system.h | 10 +-
include/SDL3/SDL_thread.h | 13 +-
include/SDL3/SDL_time.h | 3 +-
include/SDL3/SDL_version.h | 23 +-
include/SDL3/SDL_video.h | 33 +-
33 files changed, 1522 insertions(+), 921 deletions(-)
diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index 6863f4c989226..1c27484c74647 100644
--- a/include/SDL3/SDL_assert.h
+++ b/include/SDL3/SDL_assert.h
@@ -129,8 +129,8 @@ typedef enum
* Information about an assertion failure.
*
* This structure is filled in with information about a triggered assertion,
- * used by the assertion handler, then added to the assertion report.
- * This is returned as a linked list from SDL_GetAssertionReport().
+ * used by the assertion handler, then added to the assertion report. This is
+ * returned as a linked list from SDL_GetAssertionReport().
*
* \since This struct is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 7a7ee934b0b8f..de27ba43d2d74 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -149,9 +149,9 @@ typedef Uint32 SDL_AudioDeviceID;
/**
* Format specifier for audio data.
*
- * \sa SDL_AudioFormat
- *
* \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_AudioFormat
*/
typedef struct SDL_AudioSpec
{
@@ -168,19 +168,19 @@ typedef struct SDL_AudioSpec
*
* SDL_AudioStream is an audio conversion interface.
*
- * - It can handle resampling data in chunks without generating
- * artifacts, when it doesn't have the complete buffer available.
+ * - It can handle resampling data in chunks without generating artifacts,
+ * when it doesn't have the complete buffer available.
* - It can handle incoming data in any variable size.
* - It can handle input/output format changes on the fly.
* - You push data as you have it, and pull it when you need it
- * - It can also function as a basic audio data queue even if you
- * just have sound that needs to pass from one place to another.
- * - You can hook callbacks up to them when more data is added or
- * requested, to manage data on-the-fly.
- *
- * Audio streams are the core of the SDL3 audio interface. You create
- * one or more of them, bind them to an opened audio device, and feed
- * data to them (or for recording, consume data from them).
+ * - It can also function as a basic audio data queue even if you just have
+ * sound that needs to pass from one place to another.
+ * - You can hook callbacks up to them when more data is added or requested,
+ * to manage data on-the-fly.
+ *
+ * Audio streams are the core of the SDL3 audio interface. You create one or
+ * more of them, bind them to an opened audio device, and feed data to them
+ * (or for recording, consume data from them).
*
* \since This struct is available since SDL 3.0.0.
*
diff --git a/include/SDL3/SDL_blendmode.h b/include/SDL3/SDL_blendmode.h
index 111bf5a5300a9..3b00790c33090 100644
--- a/include/SDL3/SDL_blendmode.h
+++ b/include/SDL3/SDL_blendmode.h
@@ -37,11 +37,12 @@ extern "C" {
/**
* An enumeration of blend modes used in drawing operations.
*
- * Note that additional values may be obtained from SDL_ComposeCustomBlendMode.
- *
- * \sa SDL_ComposeCustomBlendMode
+ * Note that additional values may be obtained from
+ * SDL_ComposeCustomBlendMode.
*
* \since This enum is available since SDL 3.0.0.
+ *
+ * \sa SDL_ComposeCustomBlendMode
*/
typedef enum SDL_BlendMode
{
@@ -66,7 +67,8 @@ typedef enum SDL_BlendMode
} SDL_BlendMode;
/**
- * The blend operation used when combining source and destination pixel components.
+ * The blend operation used when combining source and destination pixel
+ * components.
*
* \since This enum is available since SDL 3.0.0.
*/
@@ -82,10 +84,10 @@ typedef enum SDL_BlendOperation
/**
* The normalized factor used to multiply pixel components.
*
- * The blend factors are multiplied with the pixels from a drawing
- * operation (src) and the pixels from the render target (dst) before
- * the blend operation. The comma-separated factors listed above are always
- * applied in the component order red, green, blue, and alpha.
+ * The blend factors are multiplied with the pixels from a drawing operation
+ * (src) and the pixels from the render target (dst) before the blend
+ * operation. The comma-separated factors listed above are always applied in
+ * the component order red, green, blue, and alpha.
*
* \since This enum is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h
index 3546d8b5434ba..e9f705b147bb7 100644
--- a/include/SDL3/SDL_camera.h
+++ b/include/SDL3/SDL_camera.h
@@ -59,12 +59,13 @@ typedef struct SDL_Camera SDL_Camera;
/**
* The details of an output format for a camera device.
*
- * Cameras often support multiple formats; each one will be encapsulated in this struct.
+ * Cameras often support multiple formats; each one will be encapsulated in
+ * this struct.
+ *
+ * \since This struct is available since SDL 3.0.0.
*
* \sa SDL_GetCameraDeviceSupportedFormats
* \sa SDL_GetCameraFormat
- *
- * \since This struct is available since SDL 3.0.0.
*/
typedef struct SDL_CameraSpec
{
@@ -78,9 +79,9 @@ typedef struct SDL_CameraSpec
/**
* The position of camera in relation to system device.
*
- * \sa SDL_GetCameraDevicePosition
- *
* \since This enum is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetCameraDevicePosition
*/
typedef enum SDL_CameraPosition
{
diff --git a/include/SDL3/SDL_dialog.h b/include/SDL3/SDL_dialog.h
index 6a7402efe28d4..c73cc79e0e61f 100644
--- a/include/SDL3/SDL_dialog.h
+++ b/include/SDL3/SDL_dialog.h
@@ -34,7 +34,8 @@ extern "C" {
/**
* An entry for filters for file dialogs.
*
- * `name` is a user-readable label for the filter (for example, "Office document").
+ * `name` is a user-readable label for the filter (for example, "Office
+ * document").
*
* `pattern` is a semicolon-separated list of file extensions (for example,
* "doc;docx"). File extensions may only contain alphanumeric characters,
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index 17417ac432ec6..11267cf45b472 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -240,7 +240,7 @@ typedef enum SDL_EventType
} SDL_EventType;
/**
- * Fields shared by every event
+ * Fields shared by every event
*/
typedef struct SDL_CommonEvent
{
@@ -250,7 +250,7 @@ typedef struct SDL_CommonEvent
} SDL_CommonEvent;
/**
- * Display state change event data (event.display.*)
+ * Display state change event data (event.display.*)
*/
typedef struct SDL_DisplayEvent
{
@@ -262,7 +262,7 @@ typedef struct SDL_DisplayEvent
} SDL_DisplayEvent;
/**
- * Window state change event data (event.window.*)
+ * Window state change event data (event.window.*)
*/
typedef struct SDL_WindowEvent
{
@@ -275,7 +275,7 @@ typedef struct SDL_WindowEvent
} SDL_WindowEvent;
/**
- * Keyboard device event structure (event.kdevice.*)
+ * Keyboard device event structure (event.kdevice.*)
*/
typedef struct SDL_KeyboardDeviceEvent
{
@@ -286,7 +286,7 @@ typedef struct SDL_KeyboardDeviceEvent
} SDL_KeyboardDeviceEvent;
/**
- * Keyboard button event structure (event.key.*)
+ * Keyboard button event structure (event.key.*)
*/
typedef struct SDL_KeyboardEvent
{
@@ -303,11 +303,12 @@ typedef struct SDL_KeyboardEvent
} SDL_KeyboardEvent;
#define SDL_TEXTEDITINGEVENT_TEXT_SIZE 64
+
/**
- * Keyboard text editing event structure (event.edit.*)
+ * Keyboard text editing event structure (event.edit.*)
*
- * The `text` is owned by SDL and should be copied if the application
- * wants to hold onto it beyond the scope of handling this event.
+ * The `text` is owned by SDL and should be copied if the application wants to
+ * hold onto it beyond the scope of handling this event.
*/
typedef struct SDL_TextEditingEvent
{
@@ -321,10 +322,10 @@ typedef struct SDL_TextEditingEvent
} SDL_TextEditingEvent;
/**
- * Keyboard text input event structure (event.text.*)
+ * Keyboard text input event structure (event.text.*)
*
- * The `text` is owned by SDL and should be copied if the application
- * wants to hold onto it beyond the scope of handling this event.
+ * The `text` is owned by SDL and should be copied if the application wants to
+ * hold onto it beyond the scope of handling this event.
*/
typedef struct SDL_TextInputEvent
{
@@ -336,7 +337,7 @@ typedef struct SDL_TextInputEvent
} SDL_TextInputEvent;
/**
- * Mouse device event structure (event.mdevice.*)
+ * Mouse device event structure (event.mdevice.*)
*/
typedef struct SDL_MouseDeviceEvent
{
@@ -347,7 +348,7 @@ typedef struct SDL_MouseDeviceEvent
} SDL_MouseDeviceEvent;
/**
- * Mouse motion event structure (event.motion.*)
+ * Mouse motion event structure (event.motion.*)
*/
typedef struct SDL_MouseMotionEvent
{
@@ -364,7 +365,7 @@ typedef struct SDL_MouseMotionEvent
} SDL_MouseMotionEvent;
/**
- * Mouse button event structure (event.button.*)
+ * Mouse button event structure (event.button.*)
*/
typedef struct SDL_MouseButtonEvent
{
@@ -382,7 +383,7 @@ typedef struct SDL_MouseButtonEvent
} SDL_MouseButtonEvent;
/**
- * Mouse wheel event structure (event.wheel.*)
+ * Mouse wheel event structure (event.wheel.*)
*/
typedef struct SDL_MouseWheelEvent
{
@@ -399,7 +400,7 @@ typedef struct SDL_MouseWheelEvent
} SDL_MouseWheelEvent;
/**
- * Joystick axis motion event structure (event.jaxis.*)
+ * Joystick axis motion event structure (event.jaxis.*)
*/
typedef struct SDL_JoyAxisEvent
{
@@ -416,7 +417,7 @@ typedef struct SDL_JoyAxisEvent
} SDL_JoyAxisEvent;
/**
- * \brief Joystick trackball motion event structure (event.jball.*)
+ * Joystick trackball motion event structure (event.jball.*)
*/
typedef struct SDL_JoyBallEvent
{
@@ -433,7 +434,7 @@ typedef struct SDL_JoyBallEvent
} SDL_JoyBallEvent;
/**
- * Joystick hat position change event structure (event.jhat.*)
+ * Joystick hat position change event structure (event.jhat.*)
*/
typedef struct SDL_JoyHatEvent
{
@@ -454,7 +455,7 @@ typedef struct SDL_JoyHatEvent
} SDL_JoyHatEvent;
/**
- * Joystick button event structure (event.jbutton.*)
+ * Joystick button event structure (event.jbutton.*)
*/
typedef struct SDL_JoyButtonEvent
{
@@ -469,7 +470,7 @@ typedef struct SDL_JoyButtonEvent
} SDL_JoyButtonEvent;
/**
- * Joystick device event structure (event.jdevice.*)
+ * Joystick device event structure (event.jdevice.*)
*/
typedef struct SDL_JoyDeviceEvent
{
@@ -480,7 +481,7 @@ typedef struct SDL_JoyDeviceEvent
} SDL_JoyDeviceEvent;
/**
- * Joysick battery level change event structure (event.jbattery.*)
+ * Joysick battery level change event structure (event.jbattery.*)
*/
typedef struct SDL_JoyBatteryEvent
{
@@ -493,7 +494,7 @@ typedef struct SDL_JoyBatteryEvent
} SDL_JoyBatteryEvent;
/**
- * Gamepad axis motion event structure (event.gaxis.*)
+ * Gamepad axis motion event structure (event.gaxis.*)
*/
typedef struct SDL_GamepadAxisEvent
{
@@ -511,7 +512,7 @@ typedef struct SDL_GamepadAxisEvent
/**
- * Gamepad button event structure (event.gbutton.*)
+ * Gamepad button event structure (event.gbutton.*)
*/
typedef struct SDL_GamepadButtonEvent
{
@@ -527,7 +528,7 @@ typedef struct SDL_GamepadButtonEvent
/**
- * Gamepad device event structure (event.gdevice.*)
+ * Gamepad device event structure (event.gdevice.*)
*/
typedef struct SDL_GamepadDeviceEvent
{
@@ -538,7 +539,7 @@ typedef struct SDL_GamepadDeviceEvent
} SDL_GamepadDeviceEvent;
/**
- * Gamepad touchpad event structure (event.gtouchpad.*)
+ * Gamepad touchpad event structure (event.gtouchpad.*)
*/
typedef struct SDL_GamepadTouchpadEvent
{
@@ -554,7 +555,7 @@ typedef struct SDL_GamepadTouchpadEvent
} SDL_GamepadTouchpadEvent;
/**
- * Gamepad sensor event structure (event.gsensor.*)
+ * Gamepad sensor event structure (event.gsensor.*)
*/
typedef struct SDL_GamepadSensorEvent
{
@@ -568,7 +569,7 @@ typedef struct SDL_GamepadSensorEvent
} SDL_GamepadSensorEvent;
/**
- * Audio device event structure (event.adevice.*)
+ * Audio device event structure (event.adevice.*)
*/
typedef struct SDL_AudioDeviceEvent
{
@@ -583,7 +584,7 @@ typedef struct SDL_AudioDeviceEvent
} SDL_AudioDeviceEvent;
/**
- * Camera device event structure (event.cdevice.*)
+ * Camera device event structure (event.cdevice.*)
*/
typedef struct SDL_CameraDeviceEvent
{
@@ -597,7 +598,7 @@ typedef struct SDL_CameraDeviceEvent
} SDL_CameraDeviceEvent;
/**
- * Touch finger event structure (event.tfinger.*)
+ * Touch finger event structure (event.tfinger.*)
*/
typedef struct SDL_TouchFingerEvent
{
@@ -616,8 +617,9 @@ typedef struct SDL_TouchFingerEvent
#define SDL_DROPEVENT_DATA_SIZE 64
+
/**
- * Pressure-sensitive pen touched or stopped touching surface (event.ptip.*)
+ * Pressure-sensitive pen touched or stopped touching surface (event.ptip.*)
*/
typedef struct SDL_PenTipEvent
{
@@ -635,7 +637,8 @@ typedef struct SDL_PenTipEvent
} SDL_PenTipEvent;
/**
- * Pressure-sensitive pen motion / pressure / angle event structure (event.pmotion.*)
+ * Pressure-sensitive pen motion / pressure / angle event structure
+ * (event.pmotion.*)
*/
typedef struct SDL_PenMotionEvent
{
@@ -653,7 +656,7 @@ typedef struct SDL_PenMotionEvent
} SDL_PenMotionEvent;
/**
- * Pressure-sensitive pen button event structure (event.pbutton.*)
+ * Pressure-sensitive pen button event structure (event.pbutton.*)
*/
typedef struct SDL_PenButtonEvent
{
@@ -671,10 +674,11 @@ typedef struct SDL_PenButtonEvent
} SDL_PenButtonEvent;
/**
- * An event used to drop text or request a file open by the system (event.drop.*)
+ * An event used to drop text or request a file open by the system
+ * (event.drop.*)
*
- * The `data` is owned by SDL and should be copied if the application
- * wants to hold onto it beyond the scope of handling this event. Do not free it!
+ * The `data` is owned by SDL and should be copied if the application wants to
+ * hold onto it beyond the scope of handling this event. Do not free it!
*/
typedef struct SDL_DropEvent
{
@@ -689,7 +693,8 @@ typedef struct SDL_DropEvent
} SDL_DropEvent;
/**
- * An event triggered when the clipboard contents have changed (event.clipboard.*)
+ * An event triggered when the clipboard contents have changed
+ * (event.clipboard.*)
*/
typedef struct SDL_ClipboardEvent
{
@@ -699,7 +704,7 @@ typedef struct SDL_ClipboardEvent
} SDL_ClipboardEvent;
/**
- * Sensor event structure (event.sensor.*)
+ * Sensor event structure (event.sensor.*)
*/
typedef struct SDL_SensorEvent
{
@@ -712,7 +717,7 @@ typedef struct SDL_SensorEvent
} SDL_SensorEvent;
/**
- * The "quit requested" event
+ * The "quit requested" event
*/
typedef struct SDL_QuitEvent
{
@@ -726,9 +731,9 @@ typedef struct SDL_QuitEvent
*
* This event is unique; it is never created by SDL, but only by the
* application. The event can be pushed onto the event queue using
- * SDL_PushEvent(). The contents of the structure members are completely
- * up to the programmer; the only requirement is that '''type''' is a value
- * obtained from SDL_RegisterEvents().
+ * SDL_PushEvent(). The contents of the structure members are completely up to
+ * the programmer; the only requirement is that '''type''' is a value obtained
+ * from SDL_RegisterEvents().
*/
typedef struct SDL_UserEvent
{
diff --git a/include/SDL3/SDL_filesystem.h b/include/SDL3/SDL_filesystem.h
index 7b4bff582b69b..e27bfb3326905 100644
--- a/include/SDL3/SDL_filesystem.h
+++ b/include/SDL3/SDL_filesystem.h
@@ -142,9 +142,9 @@ extern DECLSPEC char *SDLCALL SDL_GetPrefPath(const char *org, const char *app);
/**
* The type of the OS-provided default folder for a specific purpose.
*
- * Note that the Trash folder isn't included here, because trashing files usually
- * involves extra OS-specific functionality to remember the file's original
- * location.
+ * Note that the Trash folder isn't included here, because trashing files
+ * usually involves extra OS-specific functionality to remember the file's
+ * original location.
*
* The folders supported per platform are:
*
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index a889c73c72a37..de7b9f44b4aab 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -76,24 +76,25 @@ typedef enum SDL_GamepadType
} SDL_GamepadType;
/**
- * The list of buttons available on a gamepad
+ * The list of buttons available on a gamepad
*
- * For controllers that use a diamond pattern for the face buttons,
- * the south/east/west/north buttons below correspond to the locations
- * in the diamond pattern. For Xbox controllers, this would be A/B/X/Y,
- * for Nintendo Switch controllers, this would be B/A/Y/X, for
- * PlayStation controllers this would be Cross/Circle/Square/Triangle.
+ * For controllers that use a diamond pattern for the face buttons, the
+ * south/east/west/north buttons below correspond to the locations in the
+ * diamond pattern. For Xbox controllers, this would be A/B/X/Y, for Nintendo
+ * Switch controllers, this would be B/A/Y/X, for PlayStation controllers this
+ * would be Cross/Circle/Square/Triangle.
*
- * For controllers that don't use a diamond pattern for the face buttons,
- * the south/east/west/north buttons indicate the buttons labeled A, B,
- * C, D, or 1, 2, 3, 4, or for controllers that aren't labeled, they are
- * the primary, secondary, etc. buttons.
+ * For controllers that don't use a diamond pattern for the face buttons, the
+ * south/east/west/north buttons indicate the buttons labeled A, B, C, D, or
+ * 1, 2, 3, 4, or for controllers that aren't labeled, they are the primary,
+ * secondary, etc. buttons.
*
- * The activate action is often the south button and the cancel action
- * is often the east button, but in some regions this is reversed, so
- * your game should allow remapping actions based on user preferences.
+ * The activate action is often the south button and the cancel action is
+ * often the east button, but in some regions this is reversed, so your game
+ * should allow remapping actions based on user preferences.
*
- * You can query the labels for the face buttons using SDL_GetGamepadButtonLabel()
+ * You can query the labels for the face buttons using
+ * SDL_GetGamepadButtonLabel()
*/
typedef enum SDL_GamepadButton
{
@@ -128,11 +129,13 @@ typedef enum SDL_GamepadButton
} SDL_GamepadButton;
/**
- * The set of gamepad button labels
+ * The set of gamepad button labels
*
- * This isn't a complete set, just the face buttons to make it easy to show button prompts.
+ * This isn't a complete set, just the face buttons to make it easy to show
+ * button prompts.
*
- * For a complete set, you should look at the button and gamepad type and have a set of symbols that work well with your art style.
+ * For a complete set, you should look at the button and gamepad type and have
+ * a set of symbols that work well with your art style.
*/
typedef enum SDL_GamepadButtonLabel
{
@@ -148,15 +151,16 @@ typedef enum SDL_GamepadButtonLabel
} SDL_GamepadButtonLabel;
/**
- * The list of axes available on a gamepad
+ * The list of axes available on a gamepad
*
- * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to SDL_JOYSTICK_AXIS_MAX,
- * and are centered within ~8000 of zero, though advanced UI will allow users to set
- * or autodetect the dead zone, which varies between gamepads.
+ * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to
+ * SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though
+ * advanced UI will allow users to set or autodetect the dead zone, which
+ * varies between gamepads.
*
- * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX
- * (fully pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the
- * same range that will be reported by the lower-level SDL_GetJoystickAxis().
+ * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully
+ * pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the
+ * same range that will be reported by the lower-level SDL_GetJoystickAxis().
*/
typedef enum SDL_GamepadAxis
{
diff --git a/include/SDL3/SDL_guid.h b/include/SDL3/SDL_guid.h
index 30abc2741d347..e94350c842e2e 100644
--- a/include/SDL3/SDL_guid.h
+++ b/include/SDL3/SDL_guid.h
@@ -38,19 +38,19 @@ extern "C" {
#endif
/**
- * An SDL_GUID is a 128-bit identifier for an input device that
- * identifies that device across runs of SDL programs on the same
- * platform. If the device is detached and then re-attached to a
- * different port, or if the base system is rebooted, the device
- * should still report the same GUID.
+ * An SDL_GUID is a 128-bit identifier for an input device that identifies
+ * that device across runs of SDL programs on the same platform.
*
- * GUIDs are as precise as possible but are not guaranteed to
- * distinguish physically distinct but equivalent devices. For
- * example, two game controllers from the same vendor with the same
- * product ID and revision may have the same GUID.
+ * If the device is detached and then re-attached to a different port, or if
+ * the base system is rebooted, the device should still report the same GUID.
*
- * GUIDs may be platform-dependent (i.e., the same device may report
- * different GUIDs on different operating systems).
+ * GUIDs are as precise as possible but are not guaranteed to distinguish
+ * physically distinct but equivalent devices. For example, two game
+ * controllers from the same vendor with the same product ID and revision may
+ * have the same GUID.
+ *
+ * GUIDs may be platform-dependent (i.e., the same device may report different
+ * GUIDs on different operating systems).
*/
typedef struct SDL_GUID {
Uint8 data[16];
diff --git a/include/SDL3/SDL_haptic.h b/include/SDL3/SDL_haptic.h
index d79ad4da442b6..c70b421abd39a 100644
--- a/include/SDL3/SDL_haptic.h
+++ b/include/SDL3/SDL_haptic.h
@@ -163,128 +163,128 @@ typedef struct SDL_Haptic SDL_Haptic;
/* @{ */
/**
- * Constant effect supported.
+ * Constant effect supported.
*
- * Constant haptic effect.
+ * Constant haptic effect.
*
- * \sa SDL_HapticCondition
+ * \sa SDL_HapticCondition
*/
#define SDL_HAPTIC_CONSTANT (1u<<0)
/**
- * Sine wave effect supported.
+ * Sine wave effect supported.
*
- * Periodic haptic effect that simulates sine waves.
+ * Periodic haptic effect that simulates sine waves.
*
- * \sa SDL_HapticPeriodic
+ * \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SINE (1u<<1)
/**
- * Square wave effect supported.
+ * Square wave effect supported.
*
- * Periodic haptic effect that simulates square waves.
+ * Periodic haptic effect that simulates square waves.
*
- * \sa SDL_HapticPeriodic
+ * \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SQUARE (1<<2)
/**
- * Triangle wave effect supported.
+ * Triangle wave effect supported.
*
- * Periodic haptic effect that simulates triangular waves.
+ * Periodic haptic effect that simulates triangular waves.
*
- * \sa SDL_HapticPeriodic
+ * \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_TRIANGLE (1u<<3)
/**
- * Sawtoothup wave effect supported.
+ * Sawtoothup wave effect supported.
*
- * Periodic haptic effect that simulates saw tooth up waves.
+ * Periodic haptic effect that simulates saw tooth up waves.
*
- * \sa SDL_HapticPeriodic
+ * \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SAWTOOTHUP (1u<<4)
/**
- * Sawtoothdown wave effect supported.
+ * Sawtoothdown wave effect supported.
*
- * Periodic haptic effect that simulates saw tooth down waves.
+ * Periodic haptic effect that simulates saw tooth down waves.
*
- * \sa SDL_HapticPeriodic
+ * \sa SDL_HapticPeriodic
*/
#define SDL_HAPTIC_SAWTOOTHDOWN (1u<<5)
/**
- * Ramp effect supported.
+ * Ramp effect supported.
*
- * Ramp haptic effect.
+ * Ramp haptic effect.
*
- * \sa SDL_HapticRamp
+ * \sa SDL_HapticRamp
*/
#define SDL_HAPTIC_RAMP (1u<<6)
/**
- * Spring effect supported - uses axes position.
+ * Spring effect supported - uses axes position.
*
- * Condition haptic effect that simulates a spring. Effect is based on the
- * axes position.
+ * Condition haptic effect that simulates a spring. Effect is based on the
+ * axes position.
*
- * \sa SDL_HapticCondition
+ * \sa SDL_HapticCondition
*/
#define SDL_HAPTIC_SPRING (1u<<7)
/**
- * Damper effect supported - uses axes velocity.
+ * Damper effect supported - uses axes velocity.
*
- * Condition haptic effect that simulates dampening. Effect is based on the
- * axes velocity.
+ * Condition haptic effect that simulates dampening. Effect is based on the
+ * axes velocity.
*
- * \sa SDL_HapticCondition
+ * \sa SDL_HapticCondition
*/
#define SDL_HAPTIC_DAMPER (1u<<8)
/**
- * Inertia effect supported - uses axes acceleration.
+ * Inertia effect supported - uses axes acceleration.
*
- * Condition haptic effect that simulates inertia. Effect is based on the axes
- * acceleration.
+ * Condition haptic effect that simulates inertia. Effect is based on the axes
+ * acceleration.
*
- * \sa SDL_HapticCondition
+ * \sa SDL_HapticCondition
*/
#define SDL_HAPTIC_INERTIA (1u<<9)
/**
- * Friction effect supported - uses axes movement.
+ * Friction effect supported - uses axes movement.
*
- * Condition haptic effect that simulates friction. Effect is based on the
- * axes movement.
+ * Condition haptic effect that simulates friction. Effect is based on the
+ * axes movement.
*
- * \sa SDL_HapticCondition
+ * \sa SDL_HapticCondition
*/
#define SDL_HAPTIC_FRICTION (1u<<10)
/**
- * Left/Right effect supported.
+ * Left/Right effect supported.
*
- * Haptic effect for direct control over high/low frequency motors.
+ * Haptic effect for direct control over high/low frequency motors.
*
- * \sa SDL_HapticLeftRight
+ * \sa SDL_HapticLeftRight
*/
#define SDL_HAPTIC_LEFTRIGHT (1u<<11)
/**
- * Reserved for future use
+ * Reserved for future use
*/
#define SDL_HAPTIC_RESERVED1 (1u<<12)
#define SDL_HAPTIC_RESERVED2 (1u<<13)
#define SDL_HAPTIC_RESERVED3 (1u<<14)
/**
- * Custom effect is supported.
+ * Custom effect is supported.
*
- * User defined custom haptic effect.
+ * User defined custom haptic effect.
*/
#define SDL_HAPTIC_CUSTOM (1u<<15)
@@ -293,39 +293,39 @@ typedef struct SDL_Haptic SDL_Haptic;
/* These last few are features the device has, not effects */
/**
- * Device can set global gain.
+ * Device can set global gain.
*
- * Device supports setting the global gain.
+ * Device supports setting the global gain.
*
- * \sa SDL_SetHapticGain
+ * \sa SDL_SetHapticGain
*/
#define SDL_HAPTIC_GAIN (1u<<16)
/**
- * Device can set autocenter.
+ * Device can set autocenter.
*
- * Device supports setting autocenter.
+ * Device supports setting autocenter.
*
- * \sa SDL_SetHapticAutocenter
+ * \sa SDL_SetHapticAutocenter
*/
#define SDL_HAPTIC_AUTOCENTER (1u<<17)
/**
- * Device can be queried for effect status.
+ * Device can be queried for effect status.
*
- * Device supports querying effect status.
+ * Device supports querying effect status.
*
- * \sa SDL_GetHapticEffectStatus
+ * \sa SDL_GetHapticEffectStatus
*/
#define SDL_HAPTIC_STATUS (1u<<18)
/**
- * Device can be paused.
+ * Device can be paused.
*
- * Devices supports being paused.
+ * Devices supports being paused.
*
- * \sa SDL_PauseHaptic
- * \sa SDL_ResumeHaptic
+ * \sa SDL_PauseHaptic
+ * \sa SDL_ResumeHaptic
*/
#define SDL_HAPTIC_PAUSE (1u<<19)
@@ -336,31 +336,31 @@ typedef struct SDL_Haptic SDL_Haptic;
/* @{ */
/**
- * Uses polar coordinates for the direction.
+ * Uses polar coordinates for the direction.
*
- * \sa SDL_HapticDirection
+ * \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_POLAR 0
/**
- * Uses cartesian coordinates for the direction.
+ * Uses cartesian coordinates for the direction.
*
- * \sa SDL_HapticDirection
+ * \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_CARTESIAN 1
/**
- * Uses spherical coordinates for the direction.
+ * Uses spherical coordinates for the direction.
*
- * \sa SDL_HapticDirection
+ * \sa SDL_HapticDirection
*/
#define SDL_HAPTIC_SPHERICAL 2
/**
* Use this value to play an effect on the steering wheel axis.
*
- * This provides better compatibility across platforms and devices as SDL
- * will guess the correct axis.
+ * This provides better compatibility across platforms and devices as SDL will
+ * guess the correct axis.
*
* \sa SDL_HapticDirection
*/
@@ -383,23 +383,23 @@ typedef struct SDL_Haptic SDL_Haptic;
/**
- * Structure that represents a haptic direction.
+ * Structure that represents a haptic direction.
*
- * This is the direction where the force comes from,
- * instead of the direction in which the force is exerted.
+ * This is the direction where the force comes from, instead of the direction
+ * in which the force is exerted.
*
- * Directions can be specified by:
+ * Directions can be specified by:
*
- * - SDL_HAPTIC_POLAR : Specified by polar coordinates.
- * - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
- * - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
+ * - SDL_HAPTIC_POLAR : Specified by polar coordinates.
+ * - SDL_HAPTIC_CARTESIAN : Specified by cartesian coordinates.
+ * - SDL_HAPTIC_SPHERICAL : Specified by spherical coordinates.
*
- * Cardinal directions of the haptic device are relative to the positioning
- * of the device. North is considered to be away from the user.
+ * Cardinal directions of the haptic device are relative to the positioning of
+ * the device. North is considered to be away from the user.
*
- * The following diagram represents the cardinal directions:
+ * The following diagram represents the cardinal directions:
*
- * ```
+ * ```
* .--.
* |__| .-------.
(Patch may be truncated, please check the link at the top of this post.)