From e044318a8e3a50675777d0440adead960f4cce6f Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" 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 | 22 +- 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 | 1487 +++++++++++++++++++++++---------- 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 | 26 +- 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, 1510 insertions(+), 909 deletions(-) diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h index 6863f4c98..1c27484c7 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 7a7ee934b..de27ba43d 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. + * - 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). + * 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 111bf5a53..3b00790c3 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 3546d8b54..e9f705b14 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 6a7402efe..c73cc79e0 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 17417ac43..11267cf45 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 7b4bff582..e27bfb332 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 a889c73c7..de7b9f44b 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 30abc2741..e94350c84 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 d79ad4da4..c70b421ab 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: * - * ``` + * ``` * .--. * |__| .-------. * |=.| |.-----.| @@ -424,41 +424,41 @@ typedef struct SDL_Haptic SDL_Haptic; * \|||/ * (o o) * ---ooO-(_)-Ooo--- - * ``` + * ``` * - * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a - * degree starting north and turning clockwise. SDL_HAPTIC_POLAR only uses - * the first `dir` parameter. The cardinal directions would be: + * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a degree + * starting north and turning clockwise. SDL_HAPTIC_POLAR only uses the first + * `dir` parameter. The cardinal directions would be: * - * - North: 0 (0 degrees) - * - East: 9000 (90 degrees) - * - South: 18000 (180 degrees) - * - West: 27000 (270 degrees) + * - North: 0 (0 degrees) + * - East: 9000 (90 degrees) + * - South: 18000 (180 degrees) + * - West: 27000 (270 degrees) * - * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions - * (X axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses - * the first three `dir` parameters. The cardinal directions would be: + * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X + * axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first + * three `dir` parameters. The cardinal directions would be: * - * - North: 0,-1, 0 - * - East: 1, 0, 0 - * - South: 0, 1, 0 - * - West: -1, 0, 0 + * - North: 0,-1, 0 + * - East: 1, 0, 0 + * - South: 0, 1, 0 + * - West: -1, 0, 0 * - * The Z axis represents the height of the effect if supported, otherwise - * it's unused. In cartesian encoding (1, 2) would be the same as (2, 4), you - * can use any multiple you want, only the direction matters. + * The Z axis represents the height of the effect if supported, otherwise it's + * unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can + * use any multiple you want, only the direction matters. * - * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. - * The first two `dir` parameters are used. The `dir` parameters are as - * follows (all values are in hundredths of degrees): + * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The + * first two `dir` parameters are used. The `dir` parameters are as follows + * (all values are in hundredths of degrees): * - * - Degrees from (1, 0) rotated towards (0, 1). - * - Degrees towards (0, 0, 1) (device needs at least 3 axes). + * - Degrees from (1, 0) rotated towards (0, 1). + * - Degrees towards (0, 0, 1) (device needs at least 3 axes). * - * Example of force coming from the south with all encodings (force coming - * from the south means the user will have to pull the stick to counteract): + * Example of force coming from the south with all encodings (force coming + * from the south means the user will have to pull the stick to counteract): * - * ```c + * ```c * SDL_HapticDirection direction; * * // Cartesian directions @@ -474,14 +474,14 @@ typedef struct SDL_Haptic SDL_Haptic; * // Spherical coordinates * direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. - * ``` + * ``` * - * \sa SDL_HAPTIC_POLAR - * \sa SDL_HAPTIC_CARTESIAN - * \sa SDL_HAPTIC_SPHERICAL - * \sa SDL_HAPTIC_STEERING_AXIS - * \sa SDL_HapticEffect - * \sa SDL_GetNumHapticAxes + * \sa SDL_HAPTIC_POLAR + * \sa SDL_HAPTIC_CARTESIAN + * \sa SDL_HAPTIC_SPHERICAL + * \sa SDL_HAPTIC_STEERING_AXIS + * \sa SDL_HapticEffect + * \sa SDL_GetNumHapticAxes */ typedef struct SDL_HapticDirection { @@ -491,15 +491,15 @@ typedef struct SDL_HapticDirection /** - * A structure containing a template for a Constant effect. + * A structure containing a template for a Constant effect. * - * This struct is exclusively for the SDL_HAPTIC_CONSTANT effect. + * This struct is exclusively for the SDL_HAPTIC_CONSTANT effect. * - * A constant effect applies a constant force in the specified direction - * to the joystick. + * A constant effect applies a constant force in the specified direction to + * the joystick. * - * \sa SDL_HAPTIC_CONSTANT - * \sa SDL_HapticEffect + * \sa SDL_HAPTIC_CONSTANT + * \sa SDL_HapticEffect */ typedef struct SDL_HapticConstant { @@ -526,32 +526,32 @@ typedef struct SDL_HapticConstant } SDL_HapticConstant; /** - * A structure containing a template for a Periodic effect. + * A structure containing a template for a Periodic effect. * - * The struct handles the following effects: + * The struct handles the following effects: * - * - SDL_HAPTIC_SINE - * - SDL_HAPTIC_SQUARE - * - SDL_HAPTIC_TRIANGLE - * - SDL_HAPTIC_SAWTOOTHUP - * - SDL_HAPTIC_SAWTOOTHDOWN + * - SDL_HAPTIC_SINE + * - SDL_HAPTIC_SQUARE + * - SDL_HAPTIC_TRIANGLE + * - SDL_HAPTIC_SAWTOOTHUP + * - SDL_HAPTIC_SAWTOOTHDOWN * - * A periodic effect consists in a wave-shaped effect that repeats itself - * over time. The type determines the shape of the wave and the parameters - * determine the dimensions of the wave. + * A periodic effect consists in a wave-shaped effect that repeats itself over + * time. The type determines the shape of the wave and the parameters + * determine the dimensions of the wave. * - * Phase is given by hundredth of a degree meaning that giving the phase a value - * of 9000 will displace it 25% of its period. Here are sample values: + * Phase is given by hundredth of a degree meaning that giving the phase a + * value of 9000 will displace it 25% of its period. Here are sample values: * - * - 0: No phase displacement. - * - 9000: Displaced 25% of its period. - * - 18000: Displaced 50% of its period. - * - 27000: Displaced 75% of its period. - * - 36000: Displaced 100% of its period, same as 0, but 0 is preferred. + * - 0: No phase displacement. + * - 9000: Displaced 25% of its period. + * - 18000: Displaced 50% of its period. + * - 27000: Displaced 75% of its period. + * - 36000: Displaced 100% of its period, same as 0, but 0 is preferred. * - * Examples: + * Examples: * - * ``` + * ``` * SDL_HAPTIC_SINE * __ __ __ __ * / \ / \ / \ / @@ -576,14 +576,14 @@ typedef struct SDL_HapticConstant * \ |\ |\ |\ |\ |\ |\ | * \ | \ | \ | \ | \ | \ | \ | * \| \| \| \| \| \| \| - * ``` + * ``` * - * \sa SDL_HAPTIC_SINE - * \sa SDL_HAPTIC_SQUARE - * \sa SDL_HAPTIC_TRIANGLE - * \sa SDL_HAPTIC_SAWTOOTHUP - * \sa SDL_HAPTIC_SAWTOOTHDOWN - * \sa SDL_HapticEffect + * \sa SDL_HAPTIC_SINE + * \sa SDL_HAPTIC_SQUARE + * \sa SDL_HAPTIC_TRIANGLE + * \sa SDL_HAPTIC_SAWTOOTHUP + * \sa SDL_HAPTIC_SAWTOOTHDOWN + * \sa SDL_HapticEffect */ typedef struct SDL_HapticPeriodic { @@ -615,29 +615,29 @@ typedef struct SDL_HapticPeriodic } SDL_HapticPeriodic; /** - * A structure containing a template for a Condition effect. + * A structure containing a template for a Condition effect. * - * The struct handles the following effects: + * The struct handles the following effects: * - * - SDL_HAPTIC_SPRING: Effect based on axes position. - * - SDL_HAPTIC_DAMPER: Effect based on axes velocity. - * - SDL_HAPTIC_INERTIA: Effect based on axes acceleration. - * - SDL_HAPTIC_FRICTION: Effect based on axes movement. + * - SDL_HAPTIC_SPRING: Effect based on axes position. + * - SDL_HAPTIC_DAMPER: Effect based on axes velocity. + * - SDL_HAPTIC_INERTIA: Effect based on axes acceleration. + * - SDL_HAPTIC_FRICTION: Effect based on axes movement. * - * Direction is handled by condition internals instead of a direction member. - * The condition effect specific members have three parameters. The first - * refers to the X axis, the second refers to the Y axis and the third - * refers to the Z axis. The right terms refer to the positive side of the - * axis and the left terms refer to the negative side of the axis. Please - * refer to the SDL_HapticDirection diagram for which side is positive and - * which is negative. + * Direction is handled by condition internals instead of a direction member. + * The condition effect specific members have three parameters. The first + * refers to the X axis, the second refers to the Y axis and the third refers + * to the Z axis. The right terms refer to the positive side of the axis and + * the left terms refer to the negative side of the axis. Please refer to the + * SDL_HapticDirection diagram for which side is positive and which is + * negative. * - * \sa SDL_HapticDirection - * \sa SDL_HAPTIC_SPRING - * \sa SDL_HAPTIC_DAMPER - * \sa SDL_HAPTIC_INERTIA - * \sa SDL_HAPTIC_FRICTION - * \sa SDL_HapticEffect + * \sa SDL_HapticDirection + * \sa SDL_HAPTIC_SPRING + * \sa SDL_HAPTIC_DAMPER + * \sa SDL_HAPTIC_INERTIA + * \sa SDL_HAPTIC_FRICTION + * \sa SDL_HapticEffect */ typedef struct SDL_HapticCondition { @@ -664,17 +664,17 @@ typedef struct SDL_HapticCondition } SDL_HapticCondition; /** - * A structure containing a template for a Ramp effect. + * A structure containing a template for a Ramp effect. * - * This struct is exclusively for the SDL_HAPTIC_RAMP effect. + * This struct is exclusively for the SDL_HAPTIC_RAMP effect. * - * The ramp effect starts at start strength and ends at end strength. - * It augments in linear fashion. If you use attack and fade with a ramp - * the effects get added to the ramp effect making the effect become - * quadratic instead of linear. + * The ramp effect starts at start strength and ends at end strength. It + * augments in linear fashion. If you use attack and fade with a ramp the + * effects get added to the ramp effect making the effect become quadratic + * instead of linear. * - * \sa SDL_HAPTIC_RAMP - * \sa SDL_HapticEffect + * \sa SDL_HAPTIC_RAMP + * \sa SDL_HapticEffect */ typedef struct SDL_HapticRamp { @@ -727,19 +727,19 @@ typedef struct SDL_HapticLeftRight } SDL_HapticLeftRight; /** - * A structure containing a template for the SDL_HAPTIC_CUSTOM effect. + * A structure containing a template for the SDL_HAPTIC_CUSTOM effect. * - * This struct is exclusively for the SDL_HAPTIC_CUSTOM effect. + * This struct is exclusively for the SDL_HAPTIC_CUSTOM effect. * - * A custom force feedback effect is much like a periodic effect, where the - * application can define its exact shape. You will have to allocate the - * data yourself. Data should consist of channels * samples Uint16 samples. + * A custom force feedback effect is much like a periodic effect, where the + * application can define its exact shape. You will have to allocate the data + * yourself. Data should consist of channels * samples Uint16 samples. * - * If channels is one, the effect is rotated using the defined direction. - * Otherwise it uses the samples in data for the different axes. + * If channels is one, the effect is rotated using the defined direction. + * Otherwise it uses the samples in data for the different axes. * - * \sa SDL_HAPTIC_CUSTOM - * \sa SDL_HapticEffect + * \sa SDL_HAPTIC_CUSTOM + * \sa SDL_HapticEffect */ typedef struct SDL_HapticCustom { @@ -769,28 +769,28 @@ typedef struct SDL_HapticCustom } SDL_HapticCustom; /** - * The generic template for any haptic effect. + * The generic template for any haptic effect. * - * All values max at 32767 (0x7FFF). Signed values also can be negative. - * Time values unless specified otherwise are in milliseconds. + * All values max at 32767 (0x7FFF). Signed values also can be negative. Time + * values unless specified otherwise are in milliseconds. * - * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 - * value. Neither delay, interval, attack_length nor fade_length support - * SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends. + * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value. + * Neither delay, interval, attack_length nor fade_length support + * SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends. * - * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of - * SDL_HAPTIC_INFINITY. + * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of + * SDL_HAPTIC_INFINITY. * - * Button triggers may not be supported on all devices, it is advised to not - * use them if possible. Buttons start at index 1 instead of index 0 like - * the joystick. + * Button triggers may not be supported on all devices, it is advised to not + * use them if possible. Buttons start at index 1 instead of index 0 like the + * joystick. * - * If both attack_length and fade_level are 0, the envelope is not used, - * otherwise both values are used. + * If both attack_length and fade_level are 0, the envelope is not used, + * otherwise both values are used. * - * Common parts: + * Common parts: * - * ```c + * ```c * // Replay - All effects have this * Uint32 length; // Duration of effect (ms). * Uint16 delay; // Delay before starting effect. @@ -804,11 +804,11 @@ typedef struct SDL_HapticCustom * Uint16 attack_level; // Level at the start of the attack. * Uint16 fade_length; // Duration of the fade out (ms). * Uint16 fade_level; // Level at the end of the fade. - * ``` + * ``` * - * Here we have an example of a constant effect evolution in time: + * Here we have an example of a constant effect evolution in time: * - * ``` + * ``` * Strength * ^ * | @@ -826,17 +826,17 @@ typedef struct SDL_HapticCustom * * [------------------][-----------------------] * delay length - * ``` + * ``` * - * Note either the attack_level or the fade_level may be above the actual - * effect level. + * Note either the attack_level or the fade_level may be above the actual + * effect level. * - * \sa SDL_HapticConstant - * \sa SDL_HapticPeriodic - * \sa SDL_HapticCondition - * \sa SDL_HapticRamp - * \sa SDL_HapticLeftRight - * \sa SDL_HapticCustom + * \sa SDL_HapticConstant + * \sa SDL_HapticPeriodic + * \sa SDL_HapticCondition + * \sa SDL_HapticRamp + * \sa SDL_HapticLeftRight + * \sa SDL_HapticCustom */ typedef union SDL_HapticEffect { diff --git a/include/SDL3/SDL_hidapi.h b/include/SDL3/SDL_hidapi.h index 3416ddf21..00d018566 100644 --- a/include/SDL3/SDL_hidapi.h +++ b/include/SDL3/SDL_hidapi.h @@ -72,13 +72,13 @@ extern "C" { #endif /** - * A handle representing an open HID device + * A handle representing an open HID device */ struct SDL_hid_device; typedef struct SDL_hid_device SDL_hid_device; /**< opaque hidapi structure */ /** - * HID underlying bus types. + * HID underlying bus types. */ typedef enum SDL_hid_bus_type { /** Unknown bus type */ @@ -109,8 +109,9 @@ typedef enum SDL_hid_bus_type { } SDL_hid_bus_type; /** hidapi info structure */ + /** - * Information about a connected HID device + * Information about a connected HID device */ typedef struct SDL_hid_device_info { diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h index 45f4e8fa6..ce67e6957 100644 --- a/include/SDL3/SDL_hints.h +++ b/include/SDL3/SDL_hints.h @@ -51,13 +51,14 @@ extern "C" { /** * Specify the behavior of Alt+Tab while the keyboard is grabbed. * - * By default, SDL emulates Alt+Tab functionality while the keyboard is grabbed - * and your window is full-screen. This prevents the user from getting stuck in - * your application if you've enabled keyboard grab. + * By default, SDL emulates Alt+Tab functionality while the keyboard is + * grabbed and your window is full-screen. This prevents the user from getting + * stuck in your application if you've enabled keyboard grab. * * The variable can be set to the following values: * - * - "0": SDL will not handle Alt+Tab. Your application is responsible for handling Alt+Tab while the keyboard is grabbed. + * - "0": SDL will not handle Alt+Tab. Your application is responsible for + * handling Alt+Tab while the keyboard is grabbed. * - "1": SDL will minimize your window when Alt+Tab is pressed (default) * * This hint can be set anytime. @@ -69,12 +70,16 @@ extern "C" { /** * A variable to control whether the SDL activity is allowed to be re-created. * - * If this hint is true, the activity can be recreated on demand by the OS, and Java static data and C++ static data remain with their current values. If this hint is false, then SDL will call exit() when you return from your main function and the application will be terminated and then started fresh each time. + * If this hint is true, the activity can be recreated on demand by the OS, + * and Java static data and C++ static data remain with their current values. + * If this hint is false, then SDL will call exit() when you return from your + * main function and the application will be terminated and then started fresh + * each time. * * The variable can be set to the following values: * - * - "0": The application starts fresh at each launch. (default) - * - "1": The application activity can be recreated by the OS. + * - "0": The application starts fresh at each launch. (default) + * - "1": The application activity can be recreated by the OS. * * This hint can be set anytime. * @@ -83,12 +88,13 @@ extern "C" { #define SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY "SDL_ANDROID_ALLOW_RECREATE_ACTIVITY" /** - * A variable to control whether the event loop will block itself when the app is paused. + * A variable to control whether the event loop will block itself when the app + * is paused. * * The variable can be set to the following values: * - * - "0": Non blocking. - * - "1": Blocking. (default) + * - "0": Non blocking. + * - "1": Blocking. (default) * * This hint should be set before SDL is initialized. * @@ -101,8 +107,9 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": Not paused, requires that SDL_HINT_ANDROID_BLOCK_ON_PAUSE be set to "0" - * - "1": Paused. (default) + * - "0": Not paused, requires that SDL_HINT_ANDROID_BLOCK_ON_PAUSE be set to + * "0" + * - "1": Paused. (default) * * This hint should be set before SDL is initialized. * @@ -111,16 +118,21 @@ extern "C" { #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO" /** - * A variable to control whether we trap the Android back button to handle it manually. + * A variable to control whether we trap the Android back button to handle it + * manually. * - * This is necessary for the right mouse button to work on some Android devices, or to be able to trap the back button for use in your code reliably. If this hint is true, the back button will show up as an SDL_EVENT_KEY_DOWN / SDL_EVENT_KEY_UP pair with a keycode of SDL_SCANCODE_AC_BACK. + * This is necessary for the right mouse button to work on some Android + * devices, or to be able to trap the back button for use in your code + * reliably. If this hint is true, the back button will show up as an + * SDL_EVENT_KEY_DOWN / SDL_EVENT_KEY_UP pair with a keycode of + * SDL_SCANCODE_AC_BACK. * * The variable can be set to the following values: * - * - "0": Back button will be handled as usual for system. (default) - * - "1": Back button will be trapped, allowing you to handle the key press - * manually. (This will also let right mouse click work on systems - * where the right mouse button functions as back.) + * - "0": Back button will be handled as usual for system. (default) + * - "1": Back button will be trapped, allowing you to handle the key press + * manually. (This will also let right mouse click work on systems where the + * right mouse button functions as back.) * * This hint can be set anytime. * @@ -131,15 +143,29 @@ extern "C" { /** * A variable setting the app ID string. * - * This string is used by desktop compositors to identify and group windows together, as well as match applications with associated desktop settings and icons. + * This string is used by desktop compositors to identify and group windows + * together, as well as match applications with associated desktop settings + * and icons. * - * On Wayland this corresponds to the "app ID" window property and on X11 this corresponds to the WM_CLASS property. Windows inherit the value of this hint at creation time. Changing this hint after a window has been created will not change the app ID or class of existing windows. + * On Wayland this corresponds to the "app ID" window property and on X11 this + * corresponds to the WM_CLASS property. Windows inherit the value of this + * hint at creation time. Changing this hint after a window has been created + * will not change the app ID or class of existing windows. * - * For *nix platforms, this string should be formatted in reverse-DNS notation and follow some basic rules to be valid: + * For *nix platforms, this string should be formatted in reverse-DNS notation + * and follow some basic rules to be valid: * - * - The application ID must be composed of two or more elements separated by a period (.) character. - * - Each element must contain one or more of the alphanumeric characters (A-Z, a-z, 0-9) plus underscore (_) and hyphen (-) and must not start with a digit. Note that hyphens, while technically allowed, should not be used if possible, as they are not supported by all components that use the ID, such as D-Bus. For maximum compatibility, replace hyphens with an underscore. - * - The empty string is not a valid element (ie: your application ID may not start or end with a period and it is not valid to have two periods in a row). + * - The application ID must be composed of two or more elements separated by + * a period (.) character. + * - Each element must contain one or more of the alphanumeric characters + * (A-Z, a-z, 0-9) plus underscore (_) and hyphen (-) and must not start + * with a digit. Note that hyphens, while technically allowed, should not be + * used if possible, as they are not supported by all components that use + * the ID, such as D-Bus. For maximum compatibility, replace hyphens with an + * underscore. + * - The empty string is not a valid element (ie: your application ID may not + * start or end with a period and it is not valid to have two periods in a + * row). * - The entire ID must be less than 255 characters in length. * * Examples of valid app ID strings: @@ -147,12 +173,17 @@ extern "C" { * - org.MyOrg.MyApp * - com.your_company.your_app * - * Desktops such as GNOME and KDE require that the app ID string matches your application's .desktop file name (e.g. if the app ID string is 'org.MyOrg.MyApp', your application's .desktop file should be named 'org.MyOrg.MyApp.desktop'). + * Desktops such as GNOME and KDE require that the app ID string matches your + * application's .desktop file name (e.g. if the app ID string is + * 'org.MyOrg.MyApp', your application's .desktop file should be named + * 'org.MyOrg.MyApp.desktop'). * - * If you plan to package your application in a container such as Flatpak, the app ID should match the name of your Flatpak container as well. + * If you plan to package your application in a container such as Flatpak, the + * app ID should match the name of your Flatpak container as well. * - * If not set, SDL will attempt to use the application executable name. - * If the executable name cannot be retrieved, the generic string "SDL_App" will be used. + * If not set, SDL will attempt to use the application executable name. If the + * executable name cannot be retrieved, the generic string "SDL_App" will be + * used. * * This hint should be set before SDL is initialized. * @@ -166,7 +197,8 @@ extern "C" { * This hint lets you specify the application name sent to the OS when * required. For example, this will often appear in volume control applets for * audio streams, and in lists of applications which are inhibiting the - * screensaver. You should use a string that describes your program ("My Game 2: The Revenge") + * screensaver. You should use a string that describes your program ("My Game + * 2: The Revenge") * * Setting this to "" or leaving it unset will have SDL use a reasonable * default: probably the application's name or "SDL Application" if SDL @@ -182,11 +214,12 @@ extern "C" { #define SDL_HINT_APP_NAME "SDL_APP_NAME" /** - * A variable controlling whether controllers used with the Apple TV generate UI events. + * A variable controlling whether controllers used with the Apple TV generate + * UI events. * * When UI events are generated by controller input, the app will be - * backgrounded when the Apple TV remote's menu button is pressed, and when the - * pause or B buttons on gamepads are pressed. + * backgrounded when the Apple TV remote's menu button is pressed, and when + * the pause or B buttons on gamepads are pressed. * * More information about properly making use of controllers for the Apple TV * can be found here: @@ -204,7 +237,8 @@ extern "C" { #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" /** - * A variable controlling whether the Apple TV remote's joystick axes will automatically match the rotation of the remote. + * A variable controlling whether the Apple TV remote's joystick axes will + * automatically match the rotation of the remote. * * The variable can be set to the following values: * @@ -222,7 +256,8 @@ extern "C" { * * The variable can be set to the following values: * - * - "ambient": Use the AVAudioSessionCategoryAmbient audio category, will be muted by the phone mute switch (default) + * - "ambient": Use the AVAudioSessionCategoryAmbient audio category, will be + * muted by the phone mute switch (default) * - "playback": Use the AVAudioSessionCategoryPlayback category. * * For more information, see Apple's documentation: @@ -261,17 +296,17 @@ extern "C" { * A variable controlling device buffer size. * * This hint is an integer > 0, that represents the size of the device's - * buffer in sample frames (stereo audio data in 16-bit format is 4 bytes - * per sample frame, for example). + * buffer in sample frames (stereo audio data in 16-bit format is 4 bytes per + * sample frame, for example). * * SDL3 generally decides this value on behalf of the app, but if for some * reason the app needs to dictate this (because they want either lower - * latency or higher throughput AND ARE WILLING TO DEAL WITH what that - * might require of the app), they can specify it. + * latency or higher throughput AND ARE WILLING TO DEAL WITH what that might + * require of the app), they can specify it. * - * SDL will try to accomodate this value, but there is no promise you'll - * get the buffer size requested. Many platforms won't honor this request - * at all, or might adjust it. + * SDL will try to accomodate this value, but there is no promise you'll get + * the buffer size requested. Many platforms won't honor this request at all, + * or might adjust it. * * This hint should be set before an audio device is opened. * @@ -297,8 +332,8 @@ extern "C" { * default: "audio stream" or something similar. * * Note that while this talks about audio streams, this is an OS-level - * concept, so it applies to a physical audio device in this case, and - * not an SDL_AudioStream, nor an SDL logical audio device. + * concept, so it applies to a physical audio device in this case, and not an + * SDL_AudioStream, nor an SDL logical audio device. * * This hint should be set before an audio device is opened. * @@ -310,8 +345,8 @@ extern "C" { * Specify an application role for an audio device. * * Some audio backends (such as Pipewire) allow you to describe the role of - * your audio stream. Among other things, this description might show up in - * a system control panel or software for displaying and manipulating media + * your audio stream. Among other things, this description might show up in a + * system control panel or software for displaying and manipulating media * playback/capture graphs. * * This hints lets you transmit that information to the OS. The contents of @@ -323,8 +358,8 @@ extern "C" { * default: "Game" or something similar. * * Note that while this talks about audio streams, this is an OS-level - * concept, so it applies to a physical audio device in this case, and - * not an SDL_AudioStream, nor an SDL logical audio device. + * concept, so it applies to a physical audio device in this case, and not an + * SDL_AudioStream, nor an SDL logical audio device. * * This hint should be set before an audio device is opened. * @@ -335,7 +370,10 @@ extern "C" { /** * A variable that specifies an audio backend to use. * - * By default, SDL will try all available audio backends in a reasonable order until it finds one that can work, but this hint allows the app or user to force a specific driver, such as "pipewire" if, say, you are on PulseAudio but want to try talking to the lower level instead. + * By default, SDL will try all available audio backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific driver, such as "pipewire" if, say, you are on PulseAudio + * but want to try talking to the lower level instead. * * This hint should be set before SDL is initialized. * @@ -348,7 +386,12 @@ extern "C" { * * This is currently only used by the PulseAudio driver. * - * By default, SDL ignores audio devices that aren't associated with physical hardware. Changing this hint to "1" will expose anything SDL sees that appears to be an audio source or sink. This will add "devices" to the list that the user probably doesn't want or need, but it can be useful in scenarios where you want to hook up SDL to some sort of virtual device, etc. + * By default, SDL ignores audio devices that aren't associated with physical + * hardware. Changing this hint to "1" will expose anything SDL sees that + * appears to be an audio source or sink. This will add "devices" to the list + * that the user probably doesn't want or need, but it can be useful in + * scenarios where you want to hook up SDL to some sort of virtual device, + * etc. * * The variable can be set to the following values: * @@ -362,7 +405,8 @@ extern "C" { #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" /** - * A variable controlling whether SDL updates joystick state when getting input events. + * A variable controlling whether SDL updates joystick state when getting + * input events. * * The variable can be set to the following values: * @@ -376,7 +420,8 @@ extern "C" { #define SDL_HINT_AUTO_UPDATE_JOYSTICKS "SDL_AUTO_UPDATE_JOYSTICKS" /** - * A variable controlling whether SDL updates sensor state when getting input events. + * A variable controlling whether SDL updates sensor state when getting input + * events. * * The variable can be set to the following values: * @@ -392,18 +437,19 @@ extern "C" { /** * Prevent SDL from using version 4 of the bitmap header when saving BMPs. * - * The bitmap header version 4 is required for proper alpha channel support and - * SDL will use it when required. Should this not be desired, this hint can - * force the use of the 40 byte header version which is supported everywhere. + * The bitmap header version 4 is required for proper alpha channel support + * and SDL will use it when required. Should this not be desired, this hint + * can force the use of the 40 byte header version which is supported + * everywhere. * * The variable can be set to the following values: * - * - "0": Surfaces with a colorkey or an alpha channel are saved to a - * 32-bit BMP file with an alpha mask. SDL will use the bitmap - * header version 4 and set the alpha mask accordingly. (default) - * - "1": Surfaces with a colorkey or an alpha channel are saved to a - * 32-bit BMP file without an alpha mask. The alpha channel data - * will be in the file, but applications are going to ignore it. + * - "0": Surfaces with a colorkey or an alpha channel are saved to a 32-bit + * BMP file with an alpha mask. SDL will use the bitmap header version 4 and + * set the alpha mask accordingly. (default) + * - "1": Surfaces with a colorkey or an alpha channel are saved to a 32-bit + * BMP file without an alpha mask. The alpha channel data will be in the + * file, but applications are going to ignore it. * * This hint can be set anytime. * @@ -412,31 +458,32 @@ extern "C" { #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" /** - * A variable that decides what camera backend to use. + * A variable that decides what camera backend to use. * - * By default, SDL will try all available camera backends in a reasonable - * order until it finds one that can work, but this hint allows the app - * or user to force a specific target, such as "directshow" if, say, you are - * on Windows Media Foundations but want to try DirectShow instead. + * By default, SDL will try all available camera backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target, such as "directshow" if, say, you are on + * Windows Media Foundations but want to try DirectShow instead. * - * The default value is unset, in which case SDL will try to figure out - * the best camera backend on your behalf. This hint needs to be set - * before SDL_Init() is called to be useful. + * The default value is unset, in which case SDL will try to figure out the + * best camera backend on your behalf. This hint needs to be set before + * SDL_Init() is called to be useful. * * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_CAMERA_DRIVER "SDL_CAMERA_DRIVER" /** - * A variable that limits what CPU features are available. + * A variable that limits what CPU features are available. * - * By default, SDL marks all features the current CPU supports as available. - * This hint allows to limit these to a subset. + * By default, SDL marks all features the current CPU supports as available. + * This hint allows to limit these to a subset. * - * When the hint is unset, or empty, SDL will enable all detected CPU - * features. + * When the hint is unset, or empty, SDL will enable all detected CPU + * features. * - * The variable can be set to a comma separated list containing the following items: + * The variable can be set to a comma separated list containing the following + * items: * * - "all" * - "altivec" @@ -453,7 +500,7 @@ extern "C" { * - "lsx" * - "lasx" * - * The items can be prefixed by '+'/'-' to add/remove features. + * The items can be prefixed by '+'/'-' to add/remove features. * * \since This hint is available since SDL 3.0.0. */ @@ -476,11 +523,17 @@ extern "C" { /** * A variable that specifies a dialog backend to use. * - * By default, SDL will try all available dialog backends in a reasonable order until it finds one that can work, but this hint allows the app or user to force a specific target. + * By default, SDL will try all available dialog backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target. * - * If the specified target does not exist or is not available, the dialog-related function calls will fail. + * If the specified target does not exist or is not available, the + * dialog-related function calls will fail. * - * This hint currently only applies to platforms using the generic "Unix" dialog implementation, but may be extended to more platforms in the future. Note that some Unix and Unix-like platforms have their own implementation, such as macOS and Haiku. + * This hint currently only applies to platforms using the generic "Unix" + * dialog implementation, but may be extended to more platforms in the future. + * Note that some Unix and Unix-like platforms have their own implementation, + * such as macOS and Haiku. * * The variable can be set to the following values: * @@ -499,9 +552,14 @@ extern "C" { /** * Override for SDL_GetDisplayUsableBounds(). * - * If set, this hint will override the expected results for SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want to do this, but this allows an embedded system to request that some of the screen be reserved for other uses when paired with a well-behaved application. + * If set, this hint will override the expected results for + * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want + * to do this, but this allows an embedded system to request that some of the + * screen be reserved for other uses when paired with a well-behaved + * application. * - * The contents of this hint must be 4 comma-separated integers, the first is the bounds x, then y, width and height, in that order. + * The contents of this hint must be 4 comma-separated integers, the first is + * the bounds x, then y, width and height, in that order. * * This hint can be set anytime. * @@ -510,15 +568,18 @@ extern "C" { #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" /** - * Disable giving back control to the browser automatically when running with asyncify. + * Disable giving back control to the browser automatically when running with + * asyncify. * - * With -s ASYNCIFY, SDL calls emscripten_sleep during operations such as refreshing the screen or polling events. + * With -s ASYNCIFY, SDL calls emscripten_sleep during operations such as + * refreshing the screen or polling events. * * This hint only applies to the emscripten platform. * * The variable can be set to the following values: * - * - "0": Disable emscripten_sleep calls (if you give back browser control manually or use asyncify for other purposes). + * - "0": Disable emscripten_sleep calls (if you give back browser control + * manually or use asyncify for other purposes). * - "1": Enable emscripten_sleep calls. (default) * * This hint can be set anytime. @@ -551,7 +612,8 @@ extern "C" { * - "#document": the javascript document object * - "#screen": the javascript window.screen object * - "#canvas": the WebGL canvas element - * - any other string without a leading # sign applies to the element on the page with that ID. + * - any other string without a leading # sign applies to the element on the + * page with that ID. * * This hint should be set before creating a window. * @@ -560,11 +622,13 @@ extern "C" { #define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT" /** - * A variable that controls whether the on-screen keyboard should be shown when text input is active. + * A variable that controls whether the on-screen keyboard should be shown + * when text input is active. * * The variable can be set to the following values: * - * - "auto": The on-screen keyboard will be shown if there is no physical keyboard attached. (default) + * - "auto": The on-screen keyboard will be shown if there is no physical + * keyboard attached. (default) * - "0": Do not show the on-screen keyboard. * - "1": Show the on-screen keyboard, if available. * @@ -575,15 +639,22 @@ extern "C" { #define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" /** - * A variable controlling verbosity of the logging of SDL events pushed onto the internal queue. + * A variable controlling verbosity of the logging of SDL events pushed onto + * the internal queue. * - * The variable can be set to the following values, from least to most verbose: + * The variable can be set to the following values, from least to most + * verbose: * * - "0": Don't log any events. (default) * - "1": Log most events (other than the really spammy ones). * - "2": Include mouse and finger motion events. * - * This is generally meant to be used to debug SDL itself, but can be useful for application developers that need better visibility into what is going on in the event queue. Logged events are sent through SDL_Log(), which means by default they appear on stdout on most platforms or maybe OutputDebugString() on Windows, and can be funneled by the app with SDL_SetLogOutputFunction(), etc. + * This is generally meant to be used to debug SDL itself, but can be useful + * for application developers that need better visibility into what is going + * on in the event queue. Logged events are sent through SDL_Log(), which + * means by default they appear on stdout on most platforms or maybe + * OutputDebugString() on Windows, and can be funneled by the app with + * SDL_SetLogOutputFunction(), etc. * * This hint can be set anytime. * @@ -592,14 +663,18 @@ extern "C" { #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" /** - * A variable controlling whether raising the window should be done more forcefully. + * A variable controlling whether raising the window should be done more + * forcefully. * * The variable can be set to the following values: * * - "0": Honor the OS policy for raising windows. (default) * - "1": Force the window to be raised, overriding any OS policy. * - * At present, this is only an issue under MS Windows, which makes it nearly impossible to programmatically move a window to the foreground, for "security" reasons. See http://stackoverflow.com/a/34414846 for a discussion. + * At present, this is only an issue under MS Windows, which makes it nearly + * impossible to programmatically move a window to the foreground, for + * "security" reasons. See http://stackoverflow.com/a/34414846 for a + * discussion. * * This hint can be set anytime. * @@ -608,15 +683,19 @@ extern "C" { #define SDL_HINT_FORCE_RAISEWINDOW "SDL_FORCE_RAISEWINDOW" /** - * A variable controlling how 3D acceleration is used to accelerate the SDL screen surface. + * A variable controlling how 3D acceleration is used to accelerate the SDL + * screen surface. * - * SDL can try to accelerate the SDL screen surface by using streaming textures with a 3D rendering engine. This variable controls whether and how this is done. + * SDL can try to accelerate the SDL screen surface by using streaming + * textures with a 3D rendering engine. This variable controls whether and how + * this is done. * * The variable can be set to the following values: * * - "0": Disable 3D acceleration * - "1": Enable 3D acceleration, using the default renderer. (default) - * - "X": Enable 3D acceleration, using X where X is one of the valid rendering drivers. (e.g. "direct3d", "opengl", etc.) + * - "X": Enable 3D acceleration, using X where X is one of the valid + * rendering drivers. (e.g. "direct3d", "opengl", etc.) * * This hint should be set before calling SDL_GetWindowSurface() * @@ -627,9 +706,11 @@ extern "C" { /** * A variable that lets you manually hint extra gamecontroller db entries. * - * The variable should be newline delimited rows of gamecontroller config data, see SDL_gamepad.h + * The variable should be newline delimited rows of gamecontroller config + * data, see SDL_gamepad.h * - * You can update mappings after SDL is initialized with SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() + * You can update mappings after SDL is initialized with + * SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() * * This hint should be set before SDL is initialized. * @@ -638,11 +719,14 @@ extern "C" { #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" /** - * A variable that lets you provide a file with extra gamecontroller db entries. + * A variable that lets you provide a file with extra gamecontroller db + * entries. * - * The file should contain lines of gamecontroller config data, see SDL_gamepad.h + * The file should contain lines of gamecontroller config data, see + * SDL_gamepad.h * - * You can update mappings after SDL is initialized with SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() + * You can update mappings after SDL is initialized with + * SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() * * This hint should be set before SDL is initialized. * @@ -675,13 +759,16 @@ extern "C" { #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" /** - * A variable containing a list of devices to skip when scanning for game controllers. + * A variable containing a list of devices to skip when scanning for game + * controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -690,13 +777,16 @@ extern "C" { #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" /** - * If set, all devices will be skipped when scanning for game controllers except for the ones listed in this variable. + * If set, all devices will be skipped when scanning for game controllers + * except for the ones listed in this variable. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -705,18 +795,21 @@ extern "C" { #define SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" /** - * A variable that controls whether the device's built-in accelerometer and gyro should be used as sensors for gamepads. + * A variable that controls whether the device's built-in accelerometer and + * gyro should be used as sensors for gamepads. * * The variable can be set to the following values: * * - "0": Sensor fusion is disabled * - "1": Sensor fusion is enabled for all controllers that lack sensors * - * Or the variable can be a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * Or the variable can be a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint should be set before a gamepad is opened. * @@ -725,7 +818,8 @@ extern "C" { #define SDL_HINT_GAMECONTROLLER_SENSOR_FUSION "SDL_GAMECONTROLLER_SENSOR_FUSION" /** - * This variable sets the default text of the TextInput window on GDK platforms. + * This variable sets the default text of the TextInput window on GDK + * platforms. * * This hint is available only if SDL_GDK_TEXTINPUT defined. * @@ -736,7 +830,8 @@ extern "C" { #define SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT "SDL_GDK_TEXTINPUT_DEFAULT_TEXT" /** - * This variable sets the description of the TextInput window on GDK platforms. + * This variable sets the description of the TextInput window on GDK + * platforms. * * This hint is available only if SDL_GDK_TEXTINPUT defined. * @@ -747,9 +842,11 @@ extern "C" { #define SDL_HINT_GDK_TEXTINPUT_DESCRIPTION "SDL_GDK_TEXTINPUT_DESCRIPTION" /** - * This variable sets the maximum input length of the TextInput window on GDK platforms. + * This variable sets the maximum input length of the TextInput window on GDK + * platforms. * - * The value must be a stringified integer, for example "10" to allow for up to 10 characters of text input. + * The value must be a stringified integer, for example "10" to allow for up + * to 10 characters of text input. * * This hint is available only if SDL_GDK_TEXTINPUT defined. * @@ -760,9 +857,12 @@ extern "C" { #define SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH "SDL_GDK_TEXTINPUT_MAX_LENGTH" /** - * This variable sets the input scope of the TextInput window on GDK platforms. + * This variable sets the input scope of the TextInput window on GDK + * platforms. * - * Set this hint to change the XGameUiTextEntryInputScope value that will be passed to the window creation function. The value must be a stringified integer, for example "0" for XGameUiTextEntryInputScope::Default. + * Set this hint to change the XGameUiTextEntryInputScope value that will be + * passed to the window creation function. The value must be a stringified + * integer, for example "0" for XGameUiTextEntryInputScope::Default. * * This hint is available only if SDL_GDK_TEXTINPUT defined. * @@ -784,14 +884,17 @@ extern "C" { #define SDL_HINT_GDK_TEXTINPUT_TITLE "SDL_GDK_TEXTINPUT_TITLE" /** - * A variable to control whether SDL_hid_enumerate() enumerates all HID devices or only controllers. + * A variable to control whether SDL_hid_enumerate() enumerates all HID + * devices or only controllers. * * The variable can be set to the following values: * * - "0": SDL_hid_enumerate() will enumerate all HID devices. * - "1": SDL_hid_enumerate() will only enumerate controllers. (default) * - * By default SDL will only enumerate controllers, to reduce risk of hanging or crashing on devices with bad drivers and avoiding macOS keyboard capture permission prompts. + * By default SDL will only enumerate controllers, to reduce risk of hanging + * or crashing on devices with bad drivers and avoiding macOS keyboard capture + * permission prompts. * * This hint can be set anytime. * @@ -802,11 +905,13 @@ extern "C" { /** * A variable containing a list of devices to ignore in SDL_hid_enumerate(). * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * For example, to ignore the Shanwan DS3 controller and any Valve controller, you might use the string "0x2563/0x0523,0x28de/0x0000" + * For example, to ignore the Shanwan DS3 controller and any Valve controller, + * you might use the string "0x2563/0x0523,0x28de/0x0000" * * This hint can be set anytime. * @@ -815,15 +920,16 @@ extern "C" { #define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" /** - * A variable to control whether certain IMEs should handle text editing internally instead of sending SDL_EVENT_TEXT_EDITING events. + * A variable to control whether certain IMEs should handle text editing + * internally instead of sending SDL_EVENT_TEXT_EDITING events. * * The variable can be set to the following values: * * - "0": SDL_EVENT_TEXT_EDITING events are sent, and it is the application's - * responsibility to render the text from these events and - * differentiate it somehow from committed text. (default) - * - "1": If supported by the IME then SDL_EVENT_TEXT_EDITING events are not sent, - * and text that is being composed will be rendered in its own UI. + * responsibility to render the text from these events and differentiate it + * somehow from committed text. (default) + * - "1": If supported by the IME then SDL_EVENT_TEXT_EDITING events are not + * sent, and text that is being composed will be rendered in its own UI. * * This hint can be set anytime. * @@ -832,7 +938,8 @@ extern "C" { #define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING" /** - * A variable to control whether certain IMEs should show native UI components (such as the Candidate List) instead of suppressing them. + * A variable to control whether certain IMEs should show native UI components + * (such as the Candidate List) instead of suppressing them. * * The variable can be set to the following values: * @@ -846,13 +953,17 @@ extern "C" { #define SDL_HINT_IME_SHOW_UI "SDL_IME_SHOW_UI" /** - * A variable controlling whether the home indicator bar on iPhone X should be hidden. + * A variable controlling whether the home indicator bar on iPhone X should be + * hidden. * * The variable can be set to the following values: * * - "0": The indicator bar is not hidden. (default for windowed applications) - * - "1": The indicator bar is hidden and is shown when the screen is touched (useful for movie playback applications). - * - "2": The indicator bar is dim and the first swipe makes it visible and the second swipe performs the "home" action. (default for fullscreen applications) + * - "1": The indicator bar is hidden and is shown when the screen is touched + * (useful for movie playback applications). + * - "2": The indicator bar is dim and the first swipe makes it visible and + * the second swipe performs the "home" action. (default for fullscreen + * applications) * * This hint can be set anytime. * @@ -861,12 +972,15 @@ extern "C" { #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" /** - * A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background. + * A variable that lets you enable joystick (and gamecontroller) events even + * when your app is in the background. * * The variable can be set to the following values: * - * - "0": Disable joystick & gamecontroller input events when the application is in the background. (default) - * - "1": Enable joystick & gamecontroller input events when the application is in the background. + * - "0": Disable joystick & gamecontroller input events when the application + * is in the background. (default) + * - "1": Enable joystick & gamecontroller input events when the application + * is in the background. * * This hint can be set anytime. * @@ -877,11 +991,13 @@ extern "C" { /** * A variable containing a list of arcade stick style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -890,15 +1006,19 @@ extern "C" { #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" /** - * A variable containing a list of devices that are not arcade stick style controllers. + * A variable containing a list of devices that are not arcade stick style + * controllers. * - * This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in device list. + * This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in + * device list. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -907,13 +1027,16 @@ extern "C" { #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" /** - * A variable containing a list of devices that should not be considerd joysticks. + * A variable containing a list of devices that should not be considerd + * joysticks. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -922,13 +1045,19 @@ extern "C" { #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" /** - * A variable containing a list of devices that should be considered joysticks. This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in device list. + * A variable containing a list of devices that should be considered + * joysticks. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -937,7 +1066,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED "SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED" /** - * A variable containing a comma separated list of devices to open as joysticks. + * A variable containing a comma separated list of devices to open as + * joysticks. * * This variable is currently only used by the Linux joystick driver. * @@ -948,11 +1078,13 @@ extern "C" { /** * A variable containing a list of flightstick style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of @file, in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -961,13 +1093,19 @@ extern "C" { #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" /** - * A variable containing a list of devices that are not flightstick style controllers. This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in device list. + * A variable containing a list of devices that are not flightstick style + * controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -976,13 +1114,16 @@ extern "C" { #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" /** - * A variable containing a list of devices known to have a GameCube form factor. + * A variable containing a list of devices known to have a GameCube form + * factor. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -991,13 +1132,19 @@ extern "C" { #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" /** - * A variable containing a list of devices known not to have a GameCube form factor. This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in device list. + * A variable containing a list of devices known not to have a GameCube form + * factor. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -1013,7 +1160,8 @@ extern "C" { * - "0": HIDAPI drivers are not used. * - "1": HIDAPI drivers are used. (default) * - * This variable is the default for all drivers, but can be overridden by the hints for specific drivers below. + * This variable is the default for all drivers, but can be overridden by the + * hints for specific drivers below. * * This hint should be set before enumerating controllers. * @@ -1022,12 +1170,15 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" /** - * A variable controlling whether Nintendo Switch Joy-Con controllers will be combined into a single Pro-like controller when using the HIDAPI driver. + * A variable controlling whether Nintendo Switch Joy-Con controllers will be + * combined into a single Pro-like controller when using the HIDAPI driver. * * The variable can be set to the following values: * - * - "0": Left and right Joy-Con controllers will not be combined and each will be a mini-gamepad. - * - "1": Left and right Joy-Con controllers will be combined into a single controller. (default) + * - "0": Left and right Joy-Con controllers will not be combined and each + * will be a mini-gamepad. + * - "1": Left and right Joy-Con controllers will be combined into a single + * controller. (default) * * This hint should be set before enumerating controllers. * @@ -1036,7 +1187,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" /** - * A variable controlling whether the HIDAPI driver for Nintendo GameCube controllers should be used. + * A variable controlling whether the HIDAPI driver for Nintendo GameCube + * controllers should be used. * * The variable can be set to the following values: * @@ -1052,12 +1204,14 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE "SDL_JOYSTICK_HIDAPI_GAMECUBE" /** - * A variable controlling whether rumble is used to implement the GameCube controller's 3 rumble modes, Stop(0), Rumble(1), and StopHard(2). + * A variable controlling whether rumble is used to implement the GameCube + * controller's 3 rumble modes, Stop(0), Rumble(1), and StopHard(2). * - * This is useful for applications that need full compatibility for things like ADSR envelopes. - * - Stop is implemented by setting low_frequency_rumble to 0 and high_frequency_rumble >0 - * - Rumble is both at any arbitrary value - * - StopHard is implemented by setting both low_frequency_rumble and high_frequency_rumble to 0 + * This is useful for applications that need full compatibility for things + * like ADSR envelopes. - Stop is implemented by setting low_frequency_rumble + * to 0 and high_frequency_rumble >0 - Rumble is both at any arbitrary value - + * StopHard is implemented by setting both low_frequency_rumble and + * high_frequency_rumble to 0 * * The variable can be set to the following values: * @@ -1071,7 +1225,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE" /** - * A variable controlling whether the HIDAPI driver for Nintendo Switch Joy-Cons should be used. + * A variable controlling whether the HIDAPI driver for Nintendo Switch + * Joy-Cons should be used. * * The variable can be set to the following values: * @@ -1087,14 +1242,17 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS "SDL_JOYSTICK_HIDAPI_JOY_CONS" /** - * A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Joy-Con controller is opened. + * A variable controlling whether the Home button LED should be turned on when + * a Nintendo Switch Joy-Con controller is opened. * * The variable can be set to the following values: * * - "0": home button LED is turned off * - "1": home button LED is turned on * - * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. * * This hint can be set anytime. * @@ -1103,7 +1261,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" /** - * A variable controlling whether the HIDAPI driver for Amazon Luna controllers connected via Bluetooth should be used. + * A variable controlling whether the HIDAPI driver for Amazon Luna + * controllers connected via Bluetooth should be used. * * The variable can be set to the following values: * @@ -1119,7 +1278,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" /** - * A variable controlling whether the HIDAPI driver for Nintendo Online classic controllers should be used. + * A variable controlling whether the HIDAPI driver for Nintendo Online + * classic controllers should be used. * * The variable can be set to the following values: * @@ -1135,17 +1295,20 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" /** - * A variable controlling whether the HIDAPI driver for PS3 controllers should be used. + * A variable controlling whether the HIDAPI driver for PS3 controllers should + * be used. * * The variable can be set to the following values: * * - "0": HIDAPI driver is not used. * - "1": HIDAPI driver is used. * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on other platforms. + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on + * other platforms. * - * For official Sony driver (sixaxis.sys) use SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER. - * See https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. + * For official Sony driver (sixaxis.sys) use + * SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER. See + * https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. * * This hint should be set before enumerating controllers. * @@ -1154,7 +1317,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" /** - * A variable controlling whether the Sony driver (sixaxis.sys) for PS3 controllers (Sixaxis/DualShock 3) should be used. + * A variable controlling whether the Sony driver (sixaxis.sys) for PS3 + * controllers (Sixaxis/DualShock 3) should be used. * * The variable can be set to the following values: * @@ -1170,7 +1334,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER "SDL_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER" /** - * A variable controlling whether the HIDAPI driver for PS4 controllers should be used. + * A variable controlling whether the HIDAPI driver for PS4 controllers should + * be used. * * The variable can be set to the following values: * @@ -1186,18 +1351,24 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" /** - * A variable controlling whether extended input reports should be used for PS4 controllers when using the HIDAPI driver. + * A variable controlling whether extended input reports should be used for + * PS4 controllers when using the HIDAPI driver. * * The variable can be set to the following values: * * - "0": extended reports are not enabled. (default) * - "1": extended reports are enabled. * - * Extended input reports allow rumble on Bluetooth PS4 controllers, but break DirectInput handling for applications that don't use SDL. + * Extended input reports allow rumble on Bluetooth PS4 controllers, but break + * DirectInput handling for applications that don't use SDL. * - * Once extended reports are enabled, they can not be disabled without power cycling the controller. + * Once extended reports are enabled, they can not be disabled without power + * cycling the controller. * - * For compatibility with applications written for versions of SDL prior to the introduction of PS5 controller support, this value will also control the state of extended reports on PS5 controllers when the SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. + * For compatibility with applications written for versions of SDL prior to + * the introduction of PS5 controller support, this value will also control + * the state of extended reports on PS5 controllers when the + * SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE hint is not explicitly set. * * This hint can be enabled anytime. * @@ -1206,7 +1377,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" /** - * A variable controlling whether the HIDAPI driver for PS5 controllers should be used. + * A variable controlling whether the HIDAPI driver for PS5 controllers should + * be used. * * The variable can be set to the following values: * @@ -1222,7 +1394,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" /** - * A variable controlling whether the player LEDs should be lit to indicate which player is associated with a PS5 controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a PS5 controller. * * The variable can be set to the following values: * @@ -1234,18 +1407,23 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" /** - * A variable controlling whether extended input reports should be used for PS5 controllers when using the HIDAPI driver. + * A variable controlling whether extended input reports should be used for + * PS5 controllers when using the HIDAPI driver. * * The variable can be set to the following values: * * - "0": extended reports are not enabled. (default) * - "1": extended reports. * - * Extended input reports allow rumble on Bluetooth PS5 controllers, but break DirectInput handling for applications that don't use SDL. + * Extended input reports allow rumble on Bluetooth PS5 controllers, but break + * DirectInput handling for applications that don't use SDL. * - * Once extended reports are enabled, they can not be disabled without power cycling the controller. + * Once extended reports are enabled, they can not be disabled without power + * cycling the controller. * - * For compatibility with applications written for versions of SDL prior to the introduction of PS5 controller support, this value defaults to the value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. + * For compatibility with applications written for versions of SDL prior to + * the introduction of PS5 controller support, this value defaults to the + * value of SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE. * * This hint can be enabled anytime. * @@ -1254,7 +1432,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE" /** - * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD controllers should be used. + * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD + * controllers should be used. * * The variable can be set to the following values: * @@ -1270,7 +1449,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" /** - * A variable controlling whether the HIDAPI driver for Google Stadia controllers should be used. + * A variable controlling whether the HIDAPI driver for Google Stadia + * controllers should be used. * * The variable can be set to the following values: * @@ -1284,12 +1464,15 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" /** - * A variable controlling whether the HIDAPI driver for Bluetooth Steam Controllers should be used. + * A variable controlling whether the HIDAPI driver for Bluetooth Steam + * Controllers should be used. * * The variable can be set to the following values: * * - "0": HIDAPI driver is not used. (default) - * - "1": HIDAPI driver is used for Steam Controllers, which requires Bluetooth access and may prompt the user for permission on iOS and Android. + * - "1": HIDAPI driver is used for Steam Controllers, which requires + * Bluetooth access and may prompt the user for permission on iOS and + * Android. * * This hint should be set before enumerating controllers. * @@ -1298,7 +1481,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" /** - * A variable controlling whether the HIDAPI driver for the Steam Deck builtin controller should be used. + * A variable controlling whether the HIDAPI driver for the Steam Deck builtin + * controller should be used. * * The variable can be set to the following values: * @@ -1314,7 +1498,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" /** - * A variable controlling whether the HIDAPI driver for Nintendo Switch controllers should be used. + * A variable controlling whether the HIDAPI driver for Nintendo Switch + * controllers should be used. * * The variable can be set to the following values: * @@ -1330,14 +1515,17 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH "SDL_JOYSTICK_HIDAPI_SWITCH" /** - * A variable controlling whether the Home button LED should be turned on when a Nintendo Switch Pro controller is opened. + * A variable controlling whether the Home button LED should be turned on when + * a Nintendo Switch Pro controller is opened. * * The variable can be set to the following values: * * - "0": Home button LED is turned off. * - "1": Home button LED is turned on. * - * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. * * This hint can be set anytime. * @@ -1346,7 +1534,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" /** - * A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Nintendo Switch controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a Nintendo Switch controller. * * The variable can be set to the following values: * @@ -1360,11 +1549,13 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" /** - * A variable controlling whether Nintendo Switch Joy-Con controllers will be in vertical mode when using the HIDAPI driver. + * A variable controlling whether Nintendo Switch Joy-Con controllers will be + * in vertical mode when using the HIDAPI driver. * * The variable can be set to the following values: * - * - "0": Left and right Joy-Con controllers will not be in vertical mode. (default) + * - "0": Left and right Joy-Con controllers will not be in vertical mode. + * (default) * - "1": Left and right Joy-Con controllers will be in vertical mode. * * This hint should be set before opening a Joy-Con controller. @@ -1374,14 +1565,16 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" /** - * A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U controllers should be used. + * A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U + * controllers should be used. * * The variable can be set to the following values: * * - "0": HIDAPI driver is not used. * - "1": HIDAPI driver is used. * - * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE for now. + * This driver doesn't work with the dolphinbar, so the default is SDL_FALSE + * for now. * * This hint should be set before enumerating controllers. * @@ -1390,7 +1583,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" /** - * A variable controlling whether the player LEDs should be lit to indicate which player is associated with a Wii controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a Wii controller. * * The variable can be set to the following values: * @@ -1404,14 +1598,16 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" /** - * A variable controlling whether the HIDAPI driver for XBox controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox controllers + * should be used. * * The variable can be set to the following values: * * - "0": HIDAPI driver is not used. * - "1": HIDAPI driver is used. * - * The default is "0" on Windows, otherwise the value of SDL_HINT_JOYSTICK_HIDAPI + * The default is "0" on Windows, otherwise the value of + * SDL_HINT_JOYSTICK_HIDAPI * * This hint should be set before enumerating controllers. * @@ -1420,7 +1616,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" /** - * A variable controlling whether the HIDAPI driver for XBox 360 controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox 360 controllers + * should be used. * * The variable can be set to the following values: * @@ -1436,7 +1633,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" /** - * A variable controlling whether the player LEDs should be lit to indicate which player is associated with an Xbox 360 controller. + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with an Xbox 360 controller. * * The variable can be set to the following values: * @@ -1450,7 +1648,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" /** - * A variable controlling whether the HIDAPI driver for XBox 360 wireless controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox 360 wireless + * controllers should be used. * * The variable can be set to the following values: * @@ -1466,14 +1665,15 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" /** - * A variable controlling whether the HIDAPI driver for XBox One controllers should be used. + * A variable controlling whether the HIDAPI driver for XBox One controllers + * should be used. * * The variable can be set to the following values: * * - "0": HIDAPI driver is not used. * - "1": HIDAPI driver is used. * - * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. * * This hint should be set before enumerating controllers. * @@ -1482,14 +1682,17 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" /** - * A variable controlling whether the Home button LED should be turned on when an Xbox One controller is opened. + * A variable controlling whether the Home button LED should be turned on when + * an Xbox One controller is opened. * * The variable can be set to the following values: * * - "0": Home button LED is turned off. * - "1": Home button LED is turned on. * - * By default the Home button LED state is not changed. This hint can also be set to a floating point value between 0.0 and 1.0 which controls the brightness of the Home button LED. The default brightness is 0.4. + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. The default brightness is 0.4. * * This hint can be set anytime. * @@ -1498,7 +1701,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" /** - * A variable controlling whether IOKit should be used for controller handling. + * A variable controlling whether IOKit should be used for controller + * handling. * * The variable can be set to the following values: * @@ -1512,7 +1716,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_IOKIT "SDL_JOYSTICK_IOKIT" /** - * A variable controlling whether to use the classic /dev/input/js* joystick interface or the newer /dev/input/event* joystick interface on Linux. + * A variable controlling whether to use the classic /dev/input/js* joystick + * interface or the newer /dev/input/event* joystick interface on Linux. * * The variable can be set to the following values: * @@ -1526,7 +1731,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_LINUX_CLASSIC "SDL_JOYSTICK_LINUX_CLASSIC" /** - * A variable controlling whether joysticks on Linux adhere to their HID-defined deadzones or return unfiltered values. + * A variable controlling whether joysticks on Linux adhere to their + * HID-defined deadzones or return unfiltered values. * * The variable can be set to the following values: * @@ -1540,12 +1746,16 @@ extern "C" { #define SDL_HINT_JOYSTICK_LINUX_DEADZONES "SDL_JOYSTICK_LINUX_DEADZONES" /** - * A variable controlling whether joysticks on Linux will always treat 'hat' axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking whether they may be analog. + * A variable controlling whether joysticks on Linux will always treat 'hat' + * axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking + * whether they may be analog. * * The variable can be set to the following values: * - * - "0": Only map hat axis inputs to digital hat outputs if the input axes appear to actually be digital. (default) - * - "1": Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as digital hats. + * - "0": Only map hat axis inputs to digital hat outputs if the input axes + * appear to actually be digital. (default) + * - "1": Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as + * digital hats. * * This hint should be set before a controller is opened. * @@ -1554,12 +1764,14 @@ extern "C" { #define SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS "SDL_JOYSTICK_LINUX_DIGITAL_HATS" /** - * A variable controlling whether digital hats on Linux will apply deadzones to their underlying input axes or use unfiltered values. + * A variable controlling whether digital hats on Linux will apply deadzones + * to their underlying input axes or use unfiltered values. * * The variable can be set to the following values: * * - "0": Return digital hat values based on unfiltered input axis values. - * - "1": Return digital hat values with deadzones on the input axes taken into account. (default) + * - "1": Return digital hat values with deadzones on the input axes taken + * into account. (default) * * This hint should be set before a controller is opened. * @@ -1568,7 +1780,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES "SDL_JOYSTICK_LINUX_HAT_DEADZONES" /** - * A variable controlling whether GCController should be used for controller handling. + * A variable controlling whether GCController should be used for controller + * handling. * * The variable can be set to the following values: * @@ -1582,7 +1795,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" /** - * A variable controlling whether the RAWINPUT joystick drivers should be used for better handling XInput-capable devices. + * A variable controlling whether the RAWINPUT joystick drivers should be used + * for better handling XInput-capable devices. * * The variable can be set to the following values: * @@ -1596,12 +1810,15 @@ extern "C" { #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" /** - * A variable controlling whether the RAWINPUT driver should pull correlated data from XInput. + * A variable controlling whether the RAWINPUT driver should pull correlated + * data from XInput. * * The variable can be set to the following values: * * - "0": RAWINPUT driver will only use data from raw input APIs. - * - "1": RAWINPUT driver will also pull data from XInput and Windows.Gaming.Input, providing better trigger axes, guide button presses, and rumble support for Xbox controllers. (default) + * - "1": RAWINPUT driver will also pull data from XInput and + * Windows.Gaming.Input, providing better trigger axes, guide button + * presses, and rumble support for Xbox controllers. (default) * * This hint should be set before a gamepad is opened. * @@ -1610,7 +1827,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" /** - * A variable controlling whether the ROG Chakram mice should show up as joysticks. + * A variable controlling whether the ROG Chakram mice should show up as + * joysticks. * * The variable can be set to the following values: * @@ -1624,12 +1842,13 @@ extern "C" { #define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" /** - * A variable controlling whether a separate thread should be used for handling joystick detection and raw input messages on Windows. + * A variable controlling whether a separate thread should be used for + * handling joystick detection and raw input messages on Windows. * - * The variable can be set to the following values: + * The variable can be set to the following values: * - * - "0": A separate thread is not used. (default) - * - "1": A separate thread is used for handling raw input messages. + * - "0": A separate thread is not used. (default) + * - "1": A separate thread is used for handling raw input messages. * * This hint should be set before SDL is initialized. * @@ -1640,26 +1859,34 @@ extern "C" { /** * A variable containing a list of throttle style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. - * + * * \since This hint is available since SDL 3.0.0. -*/ + */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES "SDL_JOYSTICK_THROTTLE_DEVICES" /** - * A variable containing a list of devices that are not throttle style controllers. This will override SDL_HINT_JOYSTICK_THROTTLE_DEVICES and the built in device list. + * A variable containing a list of devices that are not throttle style + * controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * This will override SDL_HINT_JOYSTICK_THROTTLE_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -1668,7 +1895,8 @@ extern "C" { #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" /** - * A variable controlling whether Windows.Gaming.Input should be used for controller handling. + * A variable controlling whether Windows.Gaming.Input should be used for + * controller handling. * * The variable can be set to the following values: * @@ -1684,11 +1912,13 @@ extern "C" { /** * A variable containing a list of wheel style controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -1697,13 +1927,19 @@ extern "C" { #define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" /** - * A variable containing a list of devices that are not wheel style controllers. This will override SDL_HINT_JOYSTICK_WHEEL_DEVICES and the built in device list. + * A variable containing a list of devices that are not wheel style + * controllers. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * This will override SDL_HINT_JOYSTICK_WHEEL_DEVICES and the built in device + * list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint can be set anytime. * @@ -1712,13 +1948,16 @@ extern "C" { #define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" /** - * A variable containing a list of devices known to have all axes centered at zero. + * A variable containing a list of devices known to have all axes centered at + * zero. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint should be set before a controller is opened. * @@ -1729,7 +1968,10 @@ extern "C" { /** * A variable that controls what KMSDRM device to use. * - * SDL might open something like "/dev/dri/cardNN" to access KMSDRM functionality, where "NN" is a device index number. SDL makes a guess at the best index to use (usually zero), but the app or user can set this hint to a number between 0 and 99 to force selection. + * SDL might open something like "/dev/dri/cardNN" to access KMSDRM + * functionality, where "NN" is a device index number. SDL makes a guess at + * the best index to use (usually zero), but the app or user can set this hint + * to a number between 0 and 99 to force selection. * * This hint should be set before SDL is initialized. * @@ -1738,18 +1980,21 @@ extern "C" { #define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" /** - * A variable that controls whether SDL requires DRM master access in order to initialize the KMSDRM video backend. + * A variable that controls whether SDL requires DRM master access in order to + * initialize the KMSDRM video backend. * - * The DRM subsystem has a concept of a "DRM master" which is a DRM client that - * has the ability to set planes, set cursor, etc. When SDL is DRM master, it - * can draw to the screen using the SDL rendering APIs. Without DRM master, SDL - * is still able to process input and query attributes of attached displays, - * but it cannot change display state or draw to the screen directly. + * The DRM subsystem has a concept of a "DRM master" which is a DRM client + * that has the ability to set planes, set cursor, etc. When SDL is DRM + * master, it can draw to the screen using the SDL rendering APIs. Without DRM + * master, SDL is still able to process input and query attributes of attached + * displays, but it cannot change display state or draw to the screen + * directly. * - * In some cases, it can be useful to have the KMSDRM backend even if it cannot - * be used for rendering. An app may want to use SDL for input processing while - * using another rendering API (such as an MMAL overlay on Raspberry Pi) or - * using its own code to render to DRM overlays that SDL doesn't support. + * In some cases, it can be useful to have the KMSDRM backend even if it + * cannot be used for rendering. An app may want to use SDL for input + * processing while using another rendering API (such as an MMAL overlay on + * Raspberry Pi) or using its own code to render to DRM overlays that SDL + * doesn't support. * * The variable can be set to the following values: * @@ -1765,13 +2010,18 @@ extern "C" { /** * A variable controlling the default SDL log levels. * - * This variable is a comma separated set of category=level tokens that define the default logging levels for SDL applications. + * This variable is a comma separated set of category=level tokens that define + * the default logging levels for SDL applications. * - * The category can be a numeric category, one of "app", "error", "assert", "system", "audio", "video", "render", "input", "test", or `*` for any unspecified category. + * The category can be a numeric category, one of "app", "error", "assert", + * "system", "audio", "video", "render", "input", "test", or `*` for any + * unspecified category. * - * The level can be a numeric level, one of "verbose", "debug", "info", "warn", "error", "critical", or "quiet" to disable that category. + * The level can be a numeric level, one of "verbose", "debug", "info", + * "warn", "error", "critical", or "quiet" to disable that category. * - * You can omit the category if you want to set the logging level for all categories. + * You can omit the category if you want to set the logging level for all + * categories. * * If this hint isn't set, the default log levels are equivalent to: * @@ -1784,11 +2034,13 @@ extern "C" { #define SDL_HINT_LOGGING "SDL_LOGGING" /** - * A variable controlling whether to force the application to become the foreground process when launched on macOS. + * A variable controlling whether to force the application to become the + * foreground process when launched on macOS. * * The variable can be set to the following values: * - * - "0": The application is brought to the foreground when launched. (default) + * - "0": The application is brought to the foreground when launched. + * (default) * - "1": The application may remain in the background when launched. * * This hint should be set before applicationDidFinishLaunching() is called. @@ -1798,11 +2050,13 @@ extern "C" { #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" /** - * A variable that determines whether Ctrl+Click should generate a right-click event on macOS. + * A variable that determines whether Ctrl+Click should generate a right-click + * event on macOS. * * The variable can be set to the following values: * - * - "0": Ctrl+Click does not generate a right mouse button click event. (default) + * - "0": Ctrl+Click does not generate a right mouse button click event. + * (default) * - "1": Ctrl+Click generated a right mouse button click event. * * This hint can be set anytime. @@ -1812,14 +2066,21 @@ extern "C" { #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" /** - * A variable controlling whether dispatching OpenGL context updates should block the dispatching thread until the main thread finishes processing on macOS. + * A variable controlling whether dispatching OpenGL context updates should + * block the dispatching thread until the main thread finishes processing on + * macOS. * * The variable can be set to the following values: * - * - "0": Dispatching OpenGL context updates will block the dispatching thread until the main thread finishes processing. (default) - * - "1": Dispatching OpenGL context updates will allow the dispatching thread to continue execution. + * - "0": Dispatching OpenGL context updates will block the dispatching thread + * until the main thread finishes processing. (default) + * - "1": Dispatching OpenGL context updates will allow the dispatching thread + * to continue execution. * - * Generally you want the default, but if you have OpenGL code in a background thread on a Mac, and the main thread hangs because it's waiting for that background thread, but that background thread is also hanging because it's waiting for the main thread to do an update, this might fix your issue. + * Generally you want the default, but if you have OpenGL code in a background + * thread on a Mac, and the main thread hangs because it's waiting for that + * background thread, but that background thread is also hanging because it's + * waiting for the main thread to do an update, this might fix your issue. * * This hint can be set anytime. * @@ -1846,14 +2107,17 @@ extern "C" { #define SDL_HINT_MAIN_CALLBACK_RATE "SDL_MAIN_CALLBACK_RATE" /** - * A variable controlling whether the mouse is captured while mouse buttons are pressed. + * A variable controlling whether the mouse is captured while mouse buttons + * are pressed. * * The variable can be set to the following values: * * - "0": The mouse is not captured while mouse buttons are pressed. * - "1": The mouse is captured while mouse buttons are pressed. * - * By default the mouse is captured while mouse buttons are pressed so if the mouse is dragged outside the window, the application continues to receive mouse events until the button is released. + * By default the mouse is captured while mouse buttons are pressed so if the + * mouse is dragged outside the window, the application continues to receive + * mouse events until the button is released. * * This hint can be set anytime. * @@ -1894,7 +2158,8 @@ extern "C" { #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" /** - * A variable setting the speed scale for mouse motion, in floating point, when the mouse is not in relative mode. + * A variable setting the speed scale for mouse motion, in floating point, + * when the mouse is not in relative mode. * * This hint can be set anytime. * @@ -1903,14 +2168,19 @@ extern "C" { #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" /** - * A variable controlling whether relative mouse mode constrains the mouse to the center of the window. + * A variable controlling whether relative mouse mode constrains the mouse to + * the center of the window. * - * Constraining to the center of the window works better for FPS games and when the application is running over RDP. Constraining to the whole window works better for 2D games and increases the chance that the mouse will be in the correct position when using high DPI mice. + * Constraining to the center of the window works better for FPS games and + * when the application is running over RDP. Constraining to the whole window + * works better for 2D games and increases the chance that the mouse will be + * in the correct position when using high DPI mice. * * The variable can be set to the following values: * * - "0": Relative mouse mode constrains the mouse to the window. - * - "1": Relative mouse mode constrains the mouse to the center of the window. (default) + * - "1": Relative mouse mode constrains the mouse to the center of the + * window. (default) * * This hint can be set anytime. * @@ -1919,7 +2189,8 @@ extern "C" { #define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" /** - * A variable controlling whether relative mouse mode is implemented using mouse warping. + * A variable controlling whether relative mouse mode is implemented using + * mouse warping. * * The variable can be set to the following values: * @@ -1933,7 +2204,8 @@ extern "C" { #define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" /** - * A variable setting the scale for mouse motion, in floating point, when the mouse is in relative mode. + * A variable setting the scale for mouse motion, in floating point, when the + * mouse is in relative mode. * * This hint can be set anytime. * @@ -1942,14 +2214,17 @@ extern "C" { #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" /** - * A variable controlling whether the system mouse acceleration curve is used for relative mouse motion. + * A variable controlling whether the system mouse acceleration curve is used + * for relative mouse motion. * * The variable can be set to the following values: * * - "0": Relative mouse motion will be unscaled. (default) - * - "1": Relative mouse motion will be scaled using the system mouse acceleration curve. + * - "1": Relative mouse motion will be scaled using the system mouse + * acceleration curve. * - * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the system speed scale. + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will override the + * system speed scale. * * This hint can be set anytime. * @@ -1958,14 +2233,17 @@ extern "C" { #define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" /** - * A variable controlling whether a motion event should be generated for mouse warping in relative mode. + * A variable controlling whether a motion event should be generated for mouse + * warping in relative mode. * * The variable can be set to the following values: * * - "0": Warping the mouse will not generate a motion event in relative mode * - "1": Warping the mouse will generate a motion event in relative mode * - * By default warping the mouse will not generate motion events in relative mode. This avoids the application having to filter out large relative motion due to warping. + * By default warping the mouse will not generate motion events in relative + * mode. This avoids the application having to filter out large relative + * motion due to warping. * * This hint can be set anytime. * @@ -1974,12 +2252,15 @@ extern "C" { #define SDL_HINT_MOUSE_RELATIVE_WARP_MOTION "SDL_MOUSE_RELATIVE_WARP_MOTION" /** - * A variable controlling whether mouse events should generate synthetic touch events. + * A variable controlling whether mouse events should generate synthetic touch + * events. * * The variable can be set to the following values: * - * - "0": Mouse events will not generate touch events. (default for desktop platforms) - * - "1": Mouse events will generate touch events. (default for mobile platforms, such as Android and iOS) + * - "0": Mouse events will not generate touch events. (default for desktop + * platforms) + * - "1": Mouse events will generate touch events. (default for mobile + * platforms, such as Android and iOS) * * This hint can be set anytime. * @@ -1992,7 +2273,8 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": SDL will install a SIGINT and SIGTERM handler, and when it catches a signal, convert it into an SDL_EVENT_QUIT event. (default) + * - "0": SDL will install a SIGINT and SIGTERM handler, and when it catches a + * signal, convert it into an SDL_EVENT_QUIT event. (default) * - "1": SDL will not install a signal handler at all. * * This hint should be set before SDL is initialized. @@ -2004,15 +2286,25 @@ extern "C" { /** * A variable controlling what driver to use for OpenGL ES contexts. * - * On some platforms, currently Windows and X11, OpenGL drivers may support creating contexts with an OpenGL ES profile. By default SDL uses these profiles, when available, otherwise it attempts to load an OpenGL ES library, e.g. that provided by the ANGLE project. This variable controls whether SDL follows this default behaviour or will always load an OpenGL ES library. + * On some platforms, currently Windows and X11, OpenGL drivers may support + * creating contexts with an OpenGL ES profile. By default SDL uses these + * profiles, when available, otherwise it attempts to load an OpenGL ES + * library, e.g. that provided by the ANGLE project. This variable controls + * whether SDL follows this default behaviour or will always load an OpenGL ES + * library. * - * Circumstances where this is useful include - * - Testing an app with a particular OpenGL ES implementation, e.g ANGLE, or emulator, e.g. those from ARM, Imagination or Qualcomm. - * - Resolving OpenGL ES function addresses at link time by linking with the OpenGL ES library instead of querying them at run time with SDL_GL_GetProcAddress(). + * Circumstances where this is useful include - Testing an app with a + * particular OpenGL ES implementation, e.g ANGLE, or emulator, e.g. those + * from ARM, Imagination or Qualcomm. - Resolving OpenGL ES function addresses + * at link time by linking with the OpenGL ES library instead of querying them + * at run time with SDL_GL_GetProcAddress(). * - * Caution: for an application to work with the default behaviour across different OpenGL drivers it must query the OpenGL ES function addresses at run time using SDL_GL_GetProcAddress(). + * Caution: for an application to work with the default behaviour across + * different OpenGL drivers it must query the OpenGL ES function addresses at + * run time using SDL_GL_GetProcAddress(). * - * This variable is ignored on most platforms because OpenGL ES is native or not supported. + * This variable is ignored on most platforms because OpenGL ES is native or + * not supported. * * The variable can be set to the following values: * @@ -2028,7 +2320,8 @@ extern "C" { /** * A variable controlling which orientations are allowed on iOS/Android. * - * In some circumstances it is necessary to be able to explicitly control which UI orientations are allowed. + * In some circumstances it is necessary to be able to explicitly control + * which UI orientations are allowed. * * This variable is a space delimited list of the following values: * @@ -2044,12 +2337,19 @@ extern "C" { #define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS" /** - * A variable controlling whether pen mouse button emulation triggers only when the pen touches the tablet surface. + * A variable controlling whether pen mouse button emulation triggers only + * when the pen touches the tablet surface. * * The variable can be set to the following values: * - * - "0": The pen reports mouse button press/release immediately when the pen button is pressed/released, and the pen tip touching the surface counts as left mouse button press. - * - "1": Mouse button presses are sent when the pen first touches the tablet (analogously for releases). Not pressing a pen button simulates mouse button 1, pressing the first pen button simulates mouse button 2 etc.; it is not possible to report multiple buttons as pressed at the same time. (default) + * - "0": The pen reports mouse button press/release immediately when the pen + * button is pressed/released, and the pen tip touching the surface counts + * as left mouse button press. + * - "1": Mouse button presses are sent when the pen first touches the tablet + * (analogously for releases). Not pressing a pen button simulates mouse + * button 1, pressing the first pen button simulates mouse button 2 etc.; it + * is not possible to report multiple buttons as pressed at the same time. + * (default) * * This hint can be set anytime. * @@ -2058,18 +2358,25 @@ extern "C" { #define SDL_HINT_PEN_DELAY_MOUSE_BUTTON "SDL_PEN_DELAY_MOUSE_BUTTON" /** - * A variable controlling whether to treat pen movement as separate from mouse movement. + * A variable controlling whether to treat pen movement as separate from mouse + * movement. * - * By default, pens report both SDL_MouseMotionEvent and SDL_PenMotionEvent updates (analogously for button presses). This hint allows decoupling mouse and pen updates. + * By default, pens report both SDL_MouseMotionEvent and SDL_PenMotionEvent + * updates (analogously for button presses). This hint allows decoupling mouse + * and pen updates. * * This variable toggles between the following behaviour: * - * - "0": Pen acts as a mouse with mouse ID SDL_PEN_MOUSEID. (default) - * Use case: client application is not pen aware, user wants to use pen instead of mouse to interact. - * - "1": Pen reports mouse clicks and movement events but does not update SDL-internal mouse state (buttons pressed, current mouse location). - * Use case: client application is not pen aware, user frequently alternates between pen and "real" mouse. - * - "2": Pen reports no mouse events. - * Use case: pen-aware client application uses this hint to allow user to toggle between pen+mouse mode ("2") and pen-only mode ("1" or "0"). + * - "0": Pen acts as a mouse with mouse ID SDL_PEN_MOUSEID. (default) Use + * case: client application is not pen aware, user wants to use pen instead + * of mouse to interact. + * - "1": Pen reports mouse clicks and movement events but does not update + * SDL-internal mouse state (buttons pressed, current mouse location). Use + * case: client application is not pen aware, user frequently alternates + * between pen and "real" mouse. + * - "2": Pen reports no mouse events. Use case: pen-aware client application + * uses this hint to allow user to toggle between pen+mouse mode ("2") and + * pen-only mode ("1" or "0"). * * This hint can be set anytime. * @@ -2078,9 +2385,13 @@ extern "C" { #define SDL_HINT_PEN_NOT_MOUSE "SDL_PEN_NOT_MOUSE" /** - * A variable controlling the use of a sentinel event when polling the event queue. + * A variable controlling the use of a sentinel event when polling the event + * queue. * - * When polling for events, SDL_PumpEvents is used to gather new events from devices. If a device keeps producing new events between calls to SDL_PumpEvents, a poll loop will become stuck until the new events stop. This is most noticeable when moving a high frequency mouse. + * When polling for events, SDL_PumpEvents is used to gather new events from + * devices. If a device keeps producing new events between calls to + * SDL_PumpEvents, a poll loop will become stuck until the new events stop. + * This is most noticeable when moving a high frequency mouse. * * The variable can be set to the following values: * @@ -2096,9 +2407,14 @@ extern "C" { /** * Override for SDL_GetPreferredLocales(). * - * If set, this will be favored over anything the OS might report for the user's preferred locales. Changing this hint at runtime will not generate a SDL_EVENT_LOCALE_CHANGED event (but if you can change the hint, you can push your own event, if you want). + * If set, this will be favored over anything the OS might report for the + * user's preferred locales. Changing this hint at runtime will not generate a + * SDL_EVENT_LOCALE_CHANGED event (but if you can change the hint, you can + * push your own event, if you want). * - * The format of this hint is a comma-separated list of language and locale, combined with an underscore, as is a common format: "en_GB". Locale is optional: "en". So you might have a list like this: "en_GB,jp,es_PT" + * The format of this hint is a comma-separated list of language and locale, + * combined with an underscore, as is a common format: "en_GB". Locale is + * optional: "en". So you might have a list like this: "en_GB,jp,es_PT" * * This hint can be set anytime. * @@ -2107,12 +2423,17 @@ extern "C" { #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" /** - * A variable that decides whether to send SDL_EVENT_QUIT when closing the last window. + * A variable that decides whether to send SDL_EVENT_QUIT when closing the + * last window. * * The variable can be set to the following values: * - * - "0": SDL will not send an SDL_EVENT_QUIT event when the last window is requesting to close. Note that in this case, there are still other legitimate reasons one might get an SDL_EVENT_QUIT event: choosing "Quit" from the macOS menu bar, sending a SIGINT (ctrl-c) on Unix, etc. - * - "1": SDL will send a quit event when the last window is requesting to close. (default) + * - "0": SDL will not send an SDL_EVENT_QUIT event when the last window is + * requesting to close. Note that in this case, there are still other + * legitimate reasons one might get an SDL_EVENT_QUIT event: choosing "Quit" + * from the macOS menu bar, sending a SIGINT (ctrl-c) on Unix, etc. + * - "1": SDL will send a quit event when the last window is requesting to + * close. (default) * * This hint can be set anytime. * @@ -2121,7 +2442,8 @@ extern "C" { #define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" /** - * A variable controlling whether the Direct3D device is initialized for thread-safe operations. + * A variable controlling whether the Direct3D device is initialized for + * thread-safe operations. * * The variable can be set to the following values: * @@ -2151,14 +2473,14 @@ extern "C" { #define SDL_HINT_RENDER_DIRECT3D11_DEBUG "SDL_RENDER_DIRECT3D11_DEBUG" /** - * A variable controlling whether to enable Vulkan Validation Layers. + * A variable controlling whether to enable Vulkan Validation Layers. * - * This variable can be set to the following values: + * This variable can be set to the following values: * - * - "0": Disable Validation Layer use - * - "1": Enable Validation Layer use + * - "0": Disable Validation Layer use + * - "1": Enable Validation Layer use * - * By default, SDL does not use Vulkan Validation Layers. + * By default, SDL does not use Vulkan Validation Layers. * * \since This hint is available since SDL 3.0.0. */ @@ -2167,7 +2489,9 @@ extern "C" { /** * A variable specifying which render driver to use. * - * If the application doesn't pick a specific renderer to use, this variable specifies the name of the preferred renderer. If the preferred renderer can't be initialized, the normal default renderer is used. + * If the application doesn't pick a specific renderer to use, this variable + * specifies the name of the preferred renderer. If the preferred renderer + * can't be initialized, the normal default renderer is used. * * This variable is case insensitive and can be set to the following values: * @@ -2181,7 +2505,8 @@ extern "C" { * - "vulkan" * - "software" * - * The default varies by platform, but it's the first one in the list that is available on the current platform. + * The default varies by platform, but it's the first one in the list that is + * available on the current platform. * * This hint should be set before creating a renderer. * @@ -2195,8 +2520,10 @@ extern "C" { * The variable can be set to the following values: * * - "0": Use the default line drawing method (Bresenham's line algorithm) - * - "1": Use the driver point API using Bresenham's line algorithm (correct, draws many points) - * - "2": Use the driver line API (occasionally misses line endpoints based on hardware driver quirks + * - "1": Use the driver point API using Bresenham's line algorithm (correct, + * draws many points) + * - "2": Use the driver line API (occasionally misses line endpoints based on + * hardware driver quirks * - "3": Use the driver geometry API (correct, draws thicker diagonal lines) * * This hint should be set before creating a renderer. @@ -2206,7 +2533,8 @@ extern "C" { #define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" /** - * A variable controlling whether the Metal render driver select low power device over default one. + * A variable controlling whether the Metal render driver select low power + * device over default one. * * The variable can be set to the following values: * @@ -2220,12 +2548,14 @@ extern "C" { #define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" /** - * A variable controlling whether vsync is automatically disabled if doesn't reach enough FPS. + * A variable controlling whether vsync is automatically disabled if doesn't + * reach enough FPS. * * The variable can be set to the following values: * * - "0": It will be using VSYNC as defined in the main flag. (default) - * - "1": If VSYNC was previously enabled, then it will disable VSYNC if doesn't reach enough speed + * - "1": If VSYNC was previously enabled, then it will disable VSYNC if + * doesn't reach enough speed * * This hint should be set before creating a renderer. * @@ -2234,7 +2564,8 @@ extern "C" { #define SDL_HINT_RENDER_PS2_DYNAMIC_VSYNC "SDL_RENDER_PS2_DYNAMIC_VSYNC" /** - * A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing. + * A variable controlling whether updates to the SDL screen surface should be + * synchronized with the vertical refresh, to avoid tearing. * * This hint overrides the application preference when creating a renderer. * @@ -2250,7 +2581,8 @@ extern "C" { #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" /** - * A variable to control whether the return key on the soft keyboard should hide the soft keyboard on Android and iOS. + * A variable to control whether the return key on the soft keyboard should + * hide the soft keyboard on Android and iOS. * * The variable can be set to the following values: * @@ -2266,11 +2598,13 @@ extern "C" { /** * A variable containing a list of ROG gamepad capable mice. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint should be set before SDL is initialized. * @@ -2279,13 +2613,18 @@ extern "C" { #define SDL_HINT_ROG_GAMEPAD_MICE "SDL_ROG_GAMEPAD_MICE" /** - * A variable containing a list of devices that are not ROG gamepad capable mice. This will override SDL_HINT_ROG_GAMEPAD_MICE and the built in device list. + * A variable containing a list of devices that are not ROG gamepad capable + * mice. * - * The format of the string is a comma separated list of USB VID/PID pairs in hexadecimal form, e.g. + * This will override SDL_HINT_ROG_GAMEPAD_MICE and the built in device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. * * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` * - * The variable can also take the form of "@file", in which case the named file will be loaded and interpreted as the value of the variable. + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. * * This hint should be set before SDL is initialized. * @@ -2308,11 +2647,18 @@ extern "C" { /** * Specify an "activity name" for screensaver inhibition. * - * Some platforms, notably Linux desktops, list the applications which are inhibiting the screensaver or other power-saving features. + * Some platforms, notably Linux desktops, list the applications which are + * inhibiting the screensaver or other power-saving features. * - * This hint lets you specify the "activity name" sent to the OS when SDL_DisableScreenSaver() is used (or the screensaver is automatically disabled). The contents of this hint are used when the screensaver is disabled. You should use a string that describes what your program is doing (and, therefore, why the screensaver is disabled). For example, "Playing a game" or "Watching a video". + * This hint lets you specify the "activity name" sent to the OS when + * SDL_DisableScreenSaver() is used (or the screensaver is automatically + * disabled). The contents of this hint are used when the screensaver is + * disabled. You should use a string that describes what your program is doing + * (and, therefore, why the screensaver is disabled). For example, "Playing a + * game" or "Watching a video". * - * Setting this to "" or leaving it unset will have SDL use a reasonable default: "Playing a game" or something similar. + * Setting this to "" or leaving it unset will have SDL use a reasonable + * default: "Playing a game" or something similar. * * This hint should be set before calling SDL_DisableScreenSaver() * @@ -2323,7 +2669,10 @@ extern "C" { /** * A variable controlling whether SDL calls dbus_shutdown() on quit. * - * This is useful as a debug tool to validate memory leaks, but shouldn't ever be set in production applications, as other libraries used by the application might use dbus under the hood and this cause cause crashes if they continue after SDL_Quit(). + * This is useful as a debug tool to validate memory leaks, but shouldn't ever + * be set in production applications, as other libraries used by the + * application might use dbus under the hood and this cause cause crashes if + * they continue after SDL_Quit(). * * The variable can be set to the following values: * @@ -2339,7 +2688,10 @@ extern "C" { /** * A variable that specifies a backend to use for title storage. * - * By default, SDL will try all available storage backends in a reasonable order until it finds one that can work, but this hint allows the app or user to force a specific target, such as "pc" if, say, you are on Steam but want to avoid SteamRemoteStorage for title data. + * By default, SDL will try all available storage backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target, such as "pc" if, say, you are on Steam but + * want to avoid SteamRemoteStorage for title data. * * This hint should be set before SDL is initialized. * @@ -2350,7 +2702,10 @@ extern "C" { /** * A variable that specifies a backend to use for user storage. * - * By default, SDL will try all available storage backends in a reasonable order until it finds one that can work, but this hint allows the app or user to force a specific target, such as "pc" if, say, you are on Steam but want to avoid SteamRemoteStorage for user data. + * By default, SDL will try all available storage backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target, such as "pc" if, say, you are on Steam but + * want to avoid SteamRemoteStorage for user data. * * This hint should be set before SDL is initialized. * @@ -2359,20 +2714,27 @@ extern "C" { #define SDL_HINT_STORAGE_USER_DRIVER "SDL_STORAGE_USER_DRIVER" /** - * Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as realtime. + * Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as + * realtime. * - * On some platforms, like Linux, a realtime priority thread may be subject to restrictions that require special handling by the application. This hint exists to let SDL know that the app is prepared to handle said restrictions. + * On some platforms, like Linux, a realtime priority thread may be subject to + * restrictions that require special handling by the application. This hint + * exists to let SDL know that the app is prepared to handle said + * restrictions. * - * On Linux, SDL will apply the following configuration to any thread that becomes realtime: + * On Linux, SDL will apply the following configuration to any thread that + * becomes realtime: * - * - The SCHED_RESET_ON_FORK bit will be set on the scheduling policy, - * - An RLIMIT_RTTIME budget will be configured to the rtkit specified limit. - * - Exceeding this limit will result in the kernel sending SIGKILL to the app, refer to the man pages for more information. + * - The SCHED_RESET_ON_FORK bit will be set on the scheduling policy, + * - An RLIMIT_RTTIME budget will be configured to the rtkit specified limit. + * - Exceeding this limit will result in the kernel sending SIGKILL to the + * app, refer to the man pages for more information. * * The variable can be set to the following values: * * - "0": default platform specific behaviour - * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling policy + * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling + * policy * * This hint should be set before calling SDL_SetThreadPriority() * @@ -2381,14 +2743,21 @@ extern "C" { #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" /** - * A string specifying additional information to use with SDL_SetThreadPriority. + * A string specifying additional information to use with + * SDL_SetThreadPriority. * - * By default SDL_SetThreadPriority will make appropriate system changes in order to apply a thread priority. For example on systems using pthreads the scheduler policy is changed automatically to a policy that works well with a given priority. Code which has specific requirements can override SDL's default behavior with this hint. + * By default SDL_SetThreadPriority will make appropriate system changes in + * order to apply a thread priority. For example on systems using pthreads the + * scheduler policy is changed automatically to a policy that works well with + * a given priority. Code which has specific requirements can override SDL's + * default behavior with this hint. * - * pthread hint values are "current", "other", "fifo" and "rr". - * Currently no other platform hint values are defined but may be in the future. + * pthread hint values are "current", "other", "fifo" and "rr". Currently no + * other platform hint values are defined but may be in the future. * - * On Linux, the kernel may send SIGKILL to realtime tasks which exceed the distro configured execution budget for rtkit. This budget can be queried through RLIMIT_RTTIME after calling SDL_SetThreadPriority(). + * On Linux, the kernel may send SIGKILL to realtime tasks which exceed the + * distro configured execution budget for rtkit. This budget can be queried + * through RLIMIT_RTTIME after calling SDL_SetThreadPriority(). * * This hint should be set before calling SDL_SetThreadPriority() * @@ -2399,7 +2768,9 @@ extern "C" { /** * A variable that controls the timer resolution, in milliseconds. * - * The higher resolution the timer, the more frequently the CPU services timer interrupts, and the more precise delays are, but this takes up power and CPU time. This hint is only used on Windows. + * The higher resolution the timer, the more frequently the CPU services timer + * interrupts, and the more precise delays are, but this takes up power and + * CPU time. This hint is only used on Windows. * * See this blog post for more information: * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ @@ -2415,7 +2786,8 @@ extern "C" { #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" /** - * A variable controlling whether touch events should generate synthetic mouse events. + * A variable controlling whether touch events should generate synthetic mouse + * events. * * The variable can be set to the following values: * @@ -2429,9 +2801,14 @@ extern "C" { #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" /** - * A variable controlling whether trackpads should be treated as touch devices. + * A variable controlling whether trackpads should be treated as touch + * devices. * - * On macOS (and possibly other platforms in the future), SDL will report touches on a trackpad as mouse input, which is generally what users expect from this device; however, these are often actually full multitouch-capable touch devices, so it might be preferable to some apps to treat them as such. + * On macOS (and possibly other platforms in the future), SDL will report + * touches on a trackpad as mouse input, which is generally what users expect + * from this device; however, these are often actually full multitouch-capable + * touch devices, so it might be preferable to some apps to treat them as + * such. * * The variable can be set to the following values: * @@ -2445,7 +2822,8 @@ extern "C" { #define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" /** - * A variable controlling whether the Android / tvOS remotes should be listed as joystick devices, instead of sending keyboard events. + * A variable controlling whether the Android / tvOS remotes should be listed + * as joystick devices, instead of sending keyboard events. * * The variable can be set to the following values: * @@ -2475,9 +2853,14 @@ extern "C" { /** * Tell the video driver that we only want a double buffer. * - * By default, most lowlevel 2D APIs will use a triple buffer scheme that wastes no CPU time on waiting for vsync after issuing a flip, but introduces a frame of latency. On the other hand, using a double buffer scheme instead is recommended for cases where low latency is an important factor because we save a whole frame of latency. + * By default, most lowlevel 2D APIs will use a triple buffer scheme that + * wastes no CPU time on waiting for vsync after issuing a flip, but + * introduces a frame of latency. On the other hand, using a double buffer + * scheme instead is recommended for cases where low latency is an important + * factor because we save a whole frame of latency. * - * We do so by waiting for vsync immediately after issuing a flip, usually just after eglSwapBuffers call in the backend's *_SwapWindow function. + * We do so by waiting for vsync immediately after issuing a flip, usually + * just after eglSwapBuffers call in the backend's *_SwapWindow function. * * This hint is currently supported on the following drivers: * @@ -2492,7 +2875,10 @@ extern "C" { /** * A variable that specifies a video backend to use. * - * By default, SDL will try all available video backends in a reasonable order until it finds one that can work, but this hint allows the app or user to force a specific target, such as "x11" if, say, you are on Wayland but want to try talking to the X server instead. + * By default, SDL will try all available video backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific target, such as "x11" if, say, you are on Wayland but want + * to try talking to the X server instead. * * This hint should be set before SDL is initialized. * @@ -2515,11 +2901,13 @@ extern "C" { #define SDL_HINT_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK "SDL_VIDEO_EGL_GETDISPLAY_FALLBACK" /** - * A variable controlling whether the OpenGL context should be created with EGL. + * A variable controlling whether the OpenGL context should be created with + * EGL. * * The variable can be set to the following values: * - * - "0": Use platform-specific GL context creation API (GLX, WGL, CGL, etc). (default) + * - "0": Use platform-specific GL context creation API (GLX, WGL, CGL, etc). + * (default) * - "1": Use EGL * * This hint should be set before SDL is initialized. @@ -2533,8 +2921,12 @@ extern "C" { * * The variable can be set to the following values: * - * - "0": Disable Spaces support (FULLSCREEN_DESKTOP won't use them and SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" button on their titlebars). - * - "1": Enable Spaces support (FULLSCREEN_DESKTOP will use them and SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" button on their titlebars). (default) + * - "0": Disable Spaces support (FULLSCREEN_DESKTOP won't use them and + * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" button on their + * titlebars). + * - "1": Enable Spaces support (FULLSCREEN_DESKTOP will use them and + * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" button on their + * titlebars). (default) * * This hint should be set before creating a window. * @@ -2543,11 +2935,13 @@ extern "C" { #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" /** - * A variable controlling whether fullscreen windows are minimized when they lose focus. + * A variable controlling whether fullscreen windows are minimized when they + * lose focus. * * The variable can be set to the following values: * - * - "0": Fullscreen windows will not be minimized when they lose focus. (default) + * - "0": Fullscreen windows will not be minimized when they lose focus. + * (default) * - "1": Fullscreen windows are minimized when they lose focus. * * This hint can be set anytime. @@ -2557,11 +2951,19 @@ extern "C" { #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" /** - * A variable controlling whether all window operations will block until complete. + * A variable controlling whether all window operations will block until + * complete. * - * Window systems that run asynchronously may not have the results of window operations that resize or move the window applied immediately upon the return of the requesting function. Setting this hint will cause such operations to block after every call until the pending operation has completed. Setting this to '1' is the equivalent of calling SDL_SyncWindow() after every function call. + * Window systems that run asynchronously may not have the results of window + * operations that resize or move the window applied immediately upon the + * return of the requesting function. Setting this hint will cause such + * operations to block after every call until the pending operation has + * completed. Setting this to '1' is the equivalent of calling + * SDL_SyncWindow() after every function call. * - * Be aware that amount of time spent blocking while waiting for window operations to complete can be quite lengthy, as animations may have to complete, which can take upwards of multiple seconds in some cases. + * Be aware that amount of time spent blocking while waiting for window + * operations to complete can be quite lengthy, as animations may have to + * complete, which can take upwards of multiple seconds in some cases. * * The variable can be set to the following values: * @@ -2575,9 +2977,11 @@ extern "C" { #define SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS "SDL_VIDEO_SYNC_WINDOW_OPERATIONS" /** - * A variable controlling whether the libdecor Wayland backend is allowed to be used. + * A variable controlling whether the libdecor Wayland backend is allowed to + * be used. * - * libdecor is used over xdg-shell when xdg-decoration protocol is unavailable. + * libdecor is used over xdg-shell when xdg-decoration protocol is + * unavailable. * * The variable can be set to the following values: * @@ -2593,14 +2997,21 @@ extern "C" { /** * Enable or disable mouse pointer warp emulation, needed by some older games. * - * Wayland does not directly support warping the mouse. When this hint is set, any SDL will emulate mouse warps using relative mouse mode. This is required for some older games (such as Source engine games), which warp the mouse to the centre of the screen rather than using relative mouse motion. Note that relative mouse mode may have different mouse acceleration behaviour than pointer warps. + * Wayland does not directly support warping the mouse. When this hint is set, + * any SDL will emulate mouse warps using relative mouse mode. This is + * required for some older games (such as Source engine games), which warp the + * mouse to the centre of the screen rather than using relative mouse motion. + * Note that relative mouse mode may have different mouse acceleration + * behaviour than pointer warps. * * The variable can be set to the following values: * - * - "0": All mouse warps fail, as mouse warping is not available under wayland. + * - "0": All mouse warps fail, as mouse warping is not available under + * wayland. * - "1": Some mouse warps will be emulated by forcing relative mouse mode. * - * If not set, this is automatically enabled unless an application uses relative mouse mode directly. + * If not set, this is automatically enabled unless an application uses + * relative mouse mode directly. * * This hint can be set anytime. * @@ -2609,9 +3020,13 @@ extern "C" { #define SDL_HINT_VIDEO_WAYLAND_EMULATE_MOUSE_WARP "SDL_VIDEO_WAYLAND_EMULATE_MOUSE_WARP" /** - * A variable controlling whether video mode emulation is enabled under Wayland. + * A variable controlling whether video mode emulation is enabled under + * Wayland. * - * When this hint is set, a standard set of emulated CVT video modes will be exposed for use by the application. If it is disabled, the only modes exposed will be the logical desktop size and, in the case of a scaled desktop, the native display resolution. + * When this hint is set, a standard set of emulated CVT video modes will be + * exposed for use by the application. If it is disabled, the only modes + * exposed will be the logical desktop size and, in the case of a scaled + * desktop, the native display resolution. * * The variable can be set to the following values: * @@ -2625,15 +3040,20 @@ extern "C" { #define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" /** - * A variable controlling how modes with a non-native aspect ratio are displayed under Wayland. + * A variable controlling how modes with a non-native aspect ratio are + * displayed under Wayland. * - * When this hint is set, the requested scaling will be used when displaying fullscreen video modes that don't match the display's native aspect ratio. This is contingent on compositor viewport support. + * When this hint is set, the requested scaling will be used when displaying + * fullscreen video modes that don't match the display's native aspect ratio. + * This is contingent on compositor viewport support. * * The variable can be set to the following values: * - * - "aspect" - Video modes will be displayed scaled, in their proper aspect ratio, with black bars. - * - "stretch" - Video modes will be scaled to fill the entire display. (default) - * - "none" - Video modes will be displayed as 1:1 with no scaling. + * - "aspect" - Video modes will be displayed scaled, in their proper aspect + * ratio, with black bars. + * - "stretch" - Video modes will be scaled to fill the entire display. + * (default) + * - "none" - Video modes will be displayed as 1:1 with no scaling. * * This hint should be set before creating a window. * @@ -2642,13 +3062,17 @@ extern "C" { #define SDL_HINT_VIDEO_WAYLAND_MODE_SCALING "SDL_VIDEO_WAYLAND_MODE_SCALING" /** - * A variable controlling whether the libdecor Wayland backend is preferred over native decrations. + * A variable controlling whether the libdecor Wayland backend is preferred + * over native decrations. * - * When this hint is set, libdecor will be used to provide window decorations, even if xdg-decoration is available. (Note that, by default, libdecor will use xdg-decoration itself if available). + * When this hint is set, libdecor will be used to provide window decorations, + * even if xdg-decoration is available. (Note that, by default, libdecor will + * use xdg-decoration itself if available). * * The variable can be set to the following values: * - * - "0": libdecor is enabled only if server-side decorations are unavailable. (default) + * - "0": libdecor is enabled only if server-side decorations are unavailable. + * (default) * - "1": libdecor is always enabled if available. * * This hint should be set before SDL is initialized. @@ -2660,17 +3084,23 @@ extern "C" { /** * A variable forcing non-DPI-aware Wayland windows to output at 1:1 scaling. * - * When this hint is set, Wayland windows that are not flagged as being DPI-aware will be output with scaling designed to force 1:1 pixel mapping. + * When this hint is set, Wayland windows that are not flagged as being + * DPI-aware will be output with scaling designed to force 1:1 pixel mapping. * - * This is intended to allow legacy applications to be displayed without desktop scaling being applied, and has issues with certain display configurations, as this forces the window to behave in a way that Wayland desktops were not designed to accommodate: + * This is intended to allow legacy applications to be displayed without + * desktop scaling being applied, and has issues with certain display + * configurations, as this forces the window to behave in a way that Wayland + * desktops were not designed to accommodate: * - * - Rounding errors can result with odd window sizes and/or desktop scales. - * - The window may be unusably small. - * - The window may jump in size at times. - * - The window may appear to be larger than the desktop size to the application. - * - Possible loss of cursor precision. + * - Rounding errors can result with odd window sizes and/or desktop scales. + * - The window may be unusably small. + * - The window may jump in size at times. + * - The window may appear to be larger than the desktop size to the + * application. + * - Possible loss of cursor precision. * - * New applications should be designed with proper DPI awareness handling instead of enabling this. + * New applications should be designed with proper DPI awareness handling + * instead of enabling this. * * The variable can be set to the following values: * @@ -2684,15 +3114,20 @@ extern "C" { #define SDL_HINT_VIDEO_WAYLAND_SCALE_TO_DISPLAY "SDL_VIDEO_WAYLAND_SCALE_TO_DISPLAY" /** - * A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries. + * A variable specifying which shader compiler to preload when using the + * Chrome ANGLE binaries. * - * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It can use two different sets of binaries, those compiled by the user from source or those provided by the Chrome browser. In the later case, these binaries require that SDL loads a DLL providing the shader compiler. + * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It can + * use two different sets of binaries, those compiled by the user from source + * or those provided by the Chrome browser. In the later case, these binaries + * require that SDL loads a DLL providing the shader compiler. * * The variable can be set to the following values: * * - "d3dcompiler_46.dll" - best for Vista or later. (default) * - "d3dcompiler_43.dll" - for XP support. - * - "none" - do not load any library, useful if you compiled ANGLE from source and included the compiler in your binaries. + * - "none" - do not load any library, useful if you compiled ANGLE from + * source and included the compiler in your binaries. * * This hint should be set before SDL is initialized. * @@ -2701,7 +3136,8 @@ extern "C" { #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" /** - * A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used. + * A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint + * should be used. * * The variable can be set to the following values: * @@ -2715,9 +3151,12 @@ extern "C" { #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" /** - * A variable controlling whether the X11 _NET_WM_PING protocol should be supported. + * A variable controlling whether the X11 _NET_WM_PING protocol should be + * supported. * - * By default SDL will use _NET_WM_PING, but for applications that know they will not always be able to respond to ping requests in a timely manner they can turn it off to avoid the window manager thinking the app is hung. + * By default SDL will use _NET_WM_PING, but for applications that know they + * will not always be able to respond to ping requests in a timely manner they + * can turn it off to avoid the window manager thinking the app is hung. * * The variable can be set to the following values: * @@ -2765,7 +3204,8 @@ extern "C" { #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" /** - * A variable controlling which touchpad should generate synthetic mouse events. + * A variable controlling which touchpad should generate synthetic mouse + * events. * * The variable can be set to the following values: * @@ -2780,18 +3220,30 @@ extern "C" { #define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_VITA_TOUCH_MOUSE_DEVICE" /** - * A variable controlling how the fact chunk affects the loading of a WAVE file. + * A variable controlling how the fact chunk affects the loading of a WAVE + * file. * - * The fact chunk stores information about the number of samples of a WAVE file. The Standards Update from Microsoft notes that this value can be used to 'determine the length of the data in seconds'. This is especially useful for compressed formats (for which this is a mandatory chunk) if they produce multiple sample frames per block and truncating the block is not allowed. The fact chunk can exactly specify how many sample frames there should be in this case. + * The fact chunk stores information about the number of samples of a WAVE + * file. The Standards Update from Microsoft notes that this value can be used + * to 'determine the length of the data in seconds'. This is especially useful + * for compressed formats (for which this is a mandatory chunk) if they + * produce multiple sample frames per block and truncating the block is not + * allowed. The fact chunk can exactly specify how many sample frames there + * should be in this case. * - * Unfortunately, most application seem to ignore the fact chunk and so SDL ignores it by default as well. + * Unfortunately, most application seem to ignore the fact chunk and so SDL + * ignores it by default as well. * * The variable can be set to the following values: * - * - "truncate" - Use the number of samples to truncate the wave data if the fact chunk is present and valid. - * - "strict" - Like "truncate", but raise an error if the fact chunk is invalid, not present for non-PCM formats, or if the data chunk doesn't have that many samples. - * - "ignorezero" - Like "truncate", but ignore fact chunk if the number of samples is zero. - * - "ignore" - Ignore fact chunk entirely. (default) + * - "truncate" - Use the number of samples to truncate the wave data if the + * fact chunk is present and valid. + * - "strict" - Like "truncate", but raise an error if the fact chunk is + * invalid, not present for non-PCM formats, or if the data chunk doesn't + * have that many samples. + * - "ignorezero" - Like "truncate", but ignore fact chunk if the number of + * samples is zero. + * - "ignore" - Ignore fact chunk entirely. (default) * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * @@ -2800,18 +3252,26 @@ extern "C" { #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" /** - * A variable controlling how the size of the RIFF chunk affects the loading of a WAVE file. + * A variable controlling how the size of the RIFF chunk affects the loading + * of a WAVE file. * - * The size of the RIFF chunk (which includes all the sub-chunks of the WAVE file) is not always reliable. In case the size is wrong, it's possible to just ignore it and step through the chunks until a fixed limit is reached. + * The size of the RIFF chunk (which includes all the sub-chunks of the WAVE + * file) is not always reliable. In case the size is wrong, it's possible to + * just ignore it and step through the chunks until a fixed limit is reached. * - * Note that files that have trailing data unrelated to the WAVE file or corrupt files may slow down the loading process without a reliable boundary. By default, SDL stops after 10000 chunks to prevent wasting time. Use the environment variable SDL_WAVE_CHUNK_LIMIT to adjust this value. + * Note that files that have trailing data unrelated to the WAVE file or + * corrupt files may slow down the loading process without a reliable + * boundary. By default, SDL stops after 10000 chunks to prevent wasting time. + * Use the environment variable SDL_WAVE_CHUNK_LIMIT to adjust this value. * * The variable can be set to the following values: * - * - "force" - Always use the RIFF chunk size as a boundary for the chunk search. - * - "ignorezero" - Like "force", but a zero size searches up to 4 GiB. (default) - * - "ignore" - Ignore the RIFF chunk size and always search up to 4 GiB. - * - "maximum" - Search for chunks until the end of file. (not recommended) + * - "force" - Always use the RIFF chunk size as a boundary for the chunk + * search. + * - "ignorezero" - Like "force", but a zero size searches up to 4 GiB. + * (default) + * - "ignore" - Ignore the RIFF chunk size and always search up to 4 GiB. + * - "maximum" - Search for chunks until the end of file. (not recommended) * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * @@ -2822,14 +3282,16 @@ extern "C" { /** * A variable controlling how a truncated WAVE file is handled. * - * A WAVE file is considered truncated if any of the chunks are incomplete or the data chunk size is not a multiple of the block size. By default, SDL decodes until the first incomplete block, as most applications seem to do. + * A WAVE file is considered truncated if any of the chunks are incomplete or + * the data chunk size is not a multiple of the block size. By default, SDL + * decodes until the first incomplete block, as most applications seem to do. * * The variable can be set to the following values: * * - "verystrict" - Raise an error if the file is truncated. - * - "strict" - Like "verystrict", but the size of the RIFF chunk is ignored. - * - "dropframe" - Decode until the first incomplete sample frame. - * - "dropblock" - Decode until the first incomplete block. (default) + * - "strict" - Like "verystrict", but the size of the RIFF chunk is ignored. + * - "dropframe" - Decode until the first incomplete sample frame. + * - "dropblock" - Decode until the first incomplete block. (default) * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() * @@ -2838,12 +3300,15 @@ extern "C" { #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" /** - * A variable controlling whether the window is activated when the SDL_RaiseWindow function is called. + * A variable controlling whether the window is activated when the + * SDL_RaiseWindow function is called. * * The variable can be set to the following values: * - * - "0": The window is not activated when the SDL_RaiseWindow function is called. - * - "1": The window is activated when the SDL_RaiseWindow function is called. (default) + * - "0": The window is not activated when the SDL_RaiseWindow function is + * called. + * - "1": The window is activated when the SDL_RaiseWindow function is called. + * (default) * * This hint can be set anytime. * @@ -2852,12 +3317,15 @@ extern "C" { #define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED "SDL_WINDOW_ACTIVATE_WHEN_RAISED" /** - * A variable controlling whether the window is activated when the SDL_ShowWindow function is called. + * A variable controlling whether the window is activated when the + * SDL_ShowWindow function is called. * * The variable can be set to the following values: * - * - "0": The window is not activated when the SDL_ShowWindow function is called. - * - "1": The window is activated when the SDL_ShowWindow function is called. (default) + * - "0": The window is not activated when the SDL_ShowWindow function is + * called. + * - "1": The window is activated when the SDL_ShowWindow function is called. + * (default) * * This hint can be set anytime. * @@ -2866,9 +3334,11 @@ extern "C" { #define SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN "SDL_WINDOW_ACTIVATE_WHEN_SHOWN" /** - * If set to "0" then never set the top-most flag on an SDL Window even if the application requests it. + * If set to "0" then never set the top-most flag on an SDL Window even if the + * application requests it. * - * This is a debugging aid for developers and not expected to be used by end users. + * This is a debugging aid for developers and not expected to be used by end + * users. * * The variable can be set to the following values: * @@ -2882,11 +3352,13 @@ extern "C" { #define SDL_HINT_WINDOW_ALLOW_TOPMOST "SDL_WINDOW_ALLOW_TOPMOST" /** - * A variable controlling whether the window frame and title bar are interactive when the cursor is hidden. + * A variable controlling whether the window frame and title bar are + * interactive when the cursor is hidden. * * The variable can be set to the following values: * - * - "0": The window frame is not interactive when the cursor is hidden (no move, resize, etc). + * - "0": The window frame is not interactive when the cursor is hidden (no + * move, resize, etc). * - "1": The window frame is interactive when the cursor is hidden. (default) * * This hint can be set anytime. @@ -2896,12 +3368,14 @@ extern "C" { #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" /** - * A variable controlling whether SDL generates window-close events for Alt+F4 on Windows. + * A variable controlling whether SDL generates window-close events for Alt+F4 + * on Windows. * * The variable can be set to the following values: * * - "0": SDL will only do normal key handling for Alt+F4. - * - "1": SDL will generate a window-close event when it sees Alt+F4. (default) + * - "1": SDL will generate a window-close event when it sees Alt+F4. + * (default) * * This hint can be set anytime. * @@ -2910,13 +3384,22 @@ extern "C" { #define SDL_HINT_WINDOWS_CLOSE_ON_ALT_F4 "SDL_WINDOWS_CLOSE_ON_ALT_F4" /** - * A variable controlling whether menus can be opened with their keyboard shortcut (Alt+mnemonic). + * A variable controlling whether menus can be opened with their keyboard + * shortcut (Alt+mnemonic). * - * If the mnemonics are enabled, then menus can be opened by pressing the Alt key and the corresponding mnemonic (for example, Alt+F opens the File menu). However, in case an invalid mnemonic is pressed, Windows makes an audible beep to convey that nothing happened. This is true even if the window has no menu at all! + * If the mnemonics are enabled, then menus can be opened by pressing the Alt + * key and the corresponding mnemonic (for example, Alt+F opens the File + * menu). However, in case an invalid mnemonic is pressed, Windows makes an + * audible beep to convey that nothing happened. This is true even if the + * window has no menu at all! * - * Because most SDL applications don't have menus, and some want to use the Alt key for other purposes, SDL disables mnemonics (and the beeping) by default. + * Because most SDL applications don't have menus, and some want to use the + * Alt key for other purposes, SDL disables mnemonics (and the beeping) by + * default. * - * Note: This also affects keyboard events: with mnemonics enabled, when a menu is opened from the keyboard, you will not receive a KEYUP event for the mnemonic key, and *might* not receive one for Alt. + * Note: This also affects keyboard events: with mnemonics enabled, when a + * menu is opened from the keyboard, you will not receive a KEYUP event for + * the mnemonic key, and *might* not receive one for Alt. * * The variable can be set to the following values: * @@ -2930,7 +3413,8 @@ extern "C" { #define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" /** - * A variable controlling whether the windows message loop is processed by SDL. + * A variable controlling whether the windows message loop is processed by + * SDL. * * The variable can be set to the following values: * @@ -2958,13 +3442,18 @@ extern "C" { #define SDL_HINT_WINDOWS_RAW_KEYBOARD "SDL_WINDOWS_RAW_KEYBOARD" /** - * A variable controlling whether SDL uses Critical Sections for mutexes on Windows. + * A variable controlling whether SDL uses Critical Sections for mutexes on + * Windows. * - * On Windows 7 and newer, Slim Reader/Writer Locks are available. They offer better performance, allocate no kernel resources and use less memory. SDL will fall back to Critical Sections on older OS versions or if forced to by this hint. + * On Windows 7 and newer, Slim Reader/Writer Locks are available. They offer + * better performance, allocate no kernel resources and use less memory. SDL + * will fall back to Critical Sections on older OS versions or if forced to by + * this hint. * * The variable can be set to the following values: * - * - "0": Use SRW Locks when available, otherwise fall back to Critical Sections. (default) + * - "0": Use SRW Locks when available, otherwise fall back to Critical + * Sections. (default) * - "1": Force the use of Critical Sections in all cases. * * This hint should be set before SDL is initialized. @@ -2976,11 +3465,16 @@ extern "C" { /** * A variable controlling whether SDL uses Kernel Semaphores on Windows. * - * Kernel Semaphores are inter-process and require a context switch on every interaction. On Windows 8 and newer, the WaitOnAddress API is available. Using that and atomics to implement semaphores increases performance. SDL will fall back to Kernel Objects on older OS versions or if forced to by this hint. + * Kernel Semaphores are inter-process and require a context switch on every + * interaction. On Windows 8 and newer, the WaitOnAddress API is available. + * Using that and atomics to implement semaphores increases performance. SDL + * will fall back to Kernel Objects on older OS versions or if forced to by + * this hint. * * The variable can be set to the following values: * - * - "0": Use Atomics and WaitOnAddress API when available, otherwise fall back to Kernel Objects. (default) + * - "0": Use Atomics and WaitOnAddress API when available, otherwise fall + * back to Kernel Objects. (default) * - "1": Force the use of Kernel Objects in all cases. * * This hint should be set before SDL is initialized. @@ -2990,7 +3484,8 @@ extern "C" { #define SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL "SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL" /** - * A variable to specify custom icon resource id from RC file on Windows platform. + * A variable to specify custom icon resource id from RC file on Windows + * platform. * * This hint should be set before SDL is initialized. * @@ -3000,19 +3495,24 @@ extern "C" { #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" /** - * A variable controlling whether SDL uses the D3D9Ex API introduced in Windows Vista, instead of normal D3D9. + * A variable controlling whether SDL uses the D3D9Ex API introduced in + * Windows Vista, instead of normal D3D9. * - * Direct3D 9Ex contains changes to state management that can eliminate device loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may require some changes to your application to cope with the new behavior, so this is disabled by default. + * Direct3D 9Ex contains changes to state management that can eliminate device + * loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may + * require some changes to your application to cope with the new behavior, so + * this is disabled by default. * * For more information on Direct3D 9Ex, see: * - * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex - * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements + * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex + * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements * * The variable can be set to the following values: * * - "0": Use the original Direct3D 9 API. (default) - * - "1": Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex is unavailable) + * - "1": Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex + * is unavailable) * * This hint should be set before SDL is initialized. * @@ -3021,21 +3521,55 @@ extern "C" { #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" /** - * A variable controlling whether back-button-press events on Windows Phone to be marked as handled. + * A variable controlling whether back-button-press events on Windows Phone to + * be marked as handled. * - * Windows Phone devices typically feature a Back button. When pressed, the OS will emit back-button-press events, which apps are expected to handle in an appropriate manner. If apps do not explicitly mark these events as 'Handled', then the OS will invoke its default behavior for unhandled back-button-press events, which on Windows Phone 8 and 8.1 is to terminate the app (and attempt to switch to the previous app, or to the device's home screen). + * Windows Phone devices typically feature a Back button. When pressed, the OS + * will emit back-button-press events, which apps are expected to handle in an + * appropriate manner. If apps do not explicitly mark these events as + * 'Handled', then the OS will invoke its default behavior for unhandled + * back-button-press events, which on Windows Phone 8 and 8.1 is to terminate + * the app (and attempt to switch to the previous app, or to the device's home + * screen). * - * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL to mark back-button-press events as Handled, if and when one is sent to the app. + * Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL to + * mark back-button-press events as Handled, if and when one is sent to the + * app. * - * Internally, Windows Phone sends back button events as parameters to special back-button-press callback functions. Apps that need to respond to back-button-press events are expected to register one or more callback functions for such, shortly after being launched (during the app's initialization phase). After the back button is pressed, the OS will invoke these callbacks. If the app's callback(s) do not explicitly mark the event as handled by the time they return, or if the app never registers one of these callback, the OS will consider the event un-handled, and it will apply its default back button behavior (terminate the app). + * Internally, Windows Phone sends back button events as parameters to special + * back-button-press callback functions. Apps that need to respond to + * back-button-press events are expected to register one or more callback + * functions for such, shortly after being launched (during the app's + * initialization phase). After the back button is pressed, the OS will invoke + * these callbacks. If the app's callback(s) do not explicitly mark the event + * as handled by the time they return, or if the app never registers one of + * these callback, the OS will consider the event un-handled, and it will + * apply its default back button behavior (terminate the app). * - * SDL registers its own back-button-press callback with the Windows Phone OS. This callback will emit a pair of SDL key-press events (SDL_EVENT_KEY_DOWN and SDL_EVENT_KEY_UP), each with a scancode of SDL_SCANCODE_AC_BACK, after which it will check the contents of the hint, SDL_HINT_WINRT_HANDLE_BACK_BUTTON. If the hint's value is set to "1", the back button event's Handled property will get set to 'true'. If the hint's value is set to something else, or if it is unset, SDL will leave the event's Handled property alone. (By default, the OS sets this property to 'false', to note.) + * SDL registers its own back-button-press callback with the Windows Phone OS. + * This callback will emit a pair of SDL key-press events (SDL_EVENT_KEY_DOWN + * and SDL_EVENT_KEY_UP), each with a scancode of SDL_SCANCODE_AC_BACK, after + * which it will check the contents of the hint, + * SDL_HINT_WINRT_HANDLE_BACK_BUTTON. If the hint's value is set to "1", the + * back button event's Handled property will get set to 'true'. If the hint's + * value is set to something else, or if it is unset, SDL will leave the + * event's Handled property alone. (By default, the OS sets this property to + * 'false', to note.) * - * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a back button is pressed, or can set it in direct-response to a back button being pressed. + * SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a + * back button is pressed, or can set it in direct-response to a back button + * being pressed. * - * In order to get notified when a back button is pressed, SDL apps should register a callback function with SDL_AddEventWatch(), and have it listen for SDL_EVENT_KEY_DOWN events that have a scancode of SDL_SCANCODE_AC_BACK. (Alternatively, SDL_EVENT_KEY_UP events can be listened-for. Listening for either event type is suitable.) Any value of SDL_HINT_WINRT_HANDLE_BACK_BUTTON set by such a callback, will be applied to the OS' current back-button-press event. + * In order to get notified when a back button is pressed, SDL apps should + * register a callback function with SDL_AddEventWatch(), and have it listen + * for SDL_EVENT_KEY_DOWN events that have a scancode of SDL_SCANCODE_AC_BACK. + * (Alternatively, SDL_EVENT_KEY_UP events can be listened-for. Listening for + * either event type is suitable.) Any value of + * SDL_HINT_WINRT_HANDLE_BACK_BUTTON set by such a callback, will be applied + * to the OS' current back-button-press event. * - * More details on back button behavior in Windows Phone apps can be found at the following page, on Microsoft's developer site: + * More details on back button behavior in Windows Phone apps can be found at + * the following page, on Microsoft's developer site: * http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx * * \since This hint is available since SDL 3.0.0. @@ -3045,15 +3579,22 @@ extern "C" { /** * A variable specifying the label text for a WinRT app's privacy policy link. * - * Network-enabled WinRT apps must include a privacy policy. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be available via the Windows Settings charm. SDL provides code to add a link there, with its label text being set via the optional hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. + * Network-enabled WinRT apps must include a privacy policy. On Windows 8, + * 8.1, and RT, Microsoft mandates that this policy be available via the + * Windows Settings charm. SDL provides code to add a link there, with its + * label text being set via the optional hint, + * SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. * - * Please note that a privacy policy's contents are not set via this hint. A separate hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the actual text of the policy. + * Please note that a privacy policy's contents are not set via this hint. A + * separate hint, SDL_HINT_WINRT_PRIVACY_POLICY_URL, is used to link to the + * actual text of the policy. * * The contents of this hint should be encoded as a UTF8 string. * * The default value is "Privacy Policy". * - * For additional information on linking to a privacy policy, see the documentation for SDL_HINT_WINRT_PRIVACY_POLICY_URL. + * For additional information on linking to a privacy policy, see the + * documentation for SDL_HINT_WINRT_PRIVACY_POLICY_URL. * * This hint should be set before SDL is initialized. * @@ -3064,15 +3605,29 @@ extern "C" { /** * A variable specifying the URL to a WinRT app's privacy policy. * - * All network-enabled WinRT apps must make a privacy policy available to its users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be be available in the Windows Settings charm, as accessed from within the app. SDL provides code to add a URL-based link there, which can point to the app's privacy policy. + * All network-enabled WinRT apps must make a privacy policy available to its + * users. On Windows 8, 8.1, and RT, Microsoft mandates that this policy be be + * available in the Windows Settings charm, as accessed from within the app. + * SDL provides code to add a URL-based link there, which can point to the + * app's privacy policy. * - * To setup a URL to an app's privacy policy, set SDL_HINT_WINRT_PRIVACY_POLICY_URL before calling any SDL_Init() functions. The contents of the hint should be a valid URL. For example, "http://www.example.com". + * To setup a URL to an app's privacy policy, set + * SDL_HINT_WINRT_PRIVACY_POLICY_URL before calling any SDL_Init() functions. + * The contents of the hint should be a valid URL. For example, + * "http://www.example.com". * - * The default value is "", which will prevent SDL from adding a privacy policy link to the Settings charm. This hint should only be set during app init. + * The default value is "", which will prevent SDL from adding a privacy + * policy link to the Settings charm. This hint should only be set during app + * init. * - * The label text of an app's "Privacy Policy" link may be customized via another hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. + * The label text of an app's "Privacy Policy" link may be customized via + * another hint, SDL_HINT_WINRT_PRIVACY_POLICY_LABEL. * - * Please note that on Windows Phone, Microsoft does not provide standard UI for displaying a privacy policy link, and as such, SDL_HINT_WINRT_PRIVACY_POLICY_URL will not get used on that platform. Network-enabled phone apps should display their privacy policy through some other, in-app means. + * Please note that on Windows Phone, Microsoft does not provide standard UI + * for displaying a privacy policy link, and as such, + * SDL_HINT_WINRT_PRIVACY_POLICY_URL will not get used on that platform. + * Network-enabled phone apps should display their privacy policy through some + * other, in-app means. * * \since This hint is available since SDL 3.0.0. */ @@ -3081,9 +3636,12 @@ extern "C" { /** * A variable controlling whether X11 windows are marked as override-redirect. * - * If set, this _might_ increase framerate at the expense of the desktop not working as expected. Override-redirect windows aren't noticed by the window manager at all. + * If set, this _might_ increase framerate at the expense of the desktop not + * working as expected. Override-redirect windows aren't noticed by the window + * manager at all. * - * You should probably only use this for fullscreen windows, and you probably shouldn't even use it for that. But it's here if you want to try! + * You should probably only use this for fullscreen windows, and you probably + * shouldn't even use it for that. But it's here if you want to try! * * The variable can be set to the following values: * @@ -3099,7 +3657,13 @@ extern "C" { /** * A variable specifying the type of an X11 window. * - * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property to report to the window manager the type of window it wants to create. This might be set to various things if SDL_WINDOW_TOOLTIP or SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that haven't set a specific type, this hint can be used to specify a custom type. For example, a dock window might set this to "_NET_WM_WINDOW_TYPE_DOCK". + * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property to + * report to the window manager the type of window it wants to create. This + * might be set to various things if SDL_WINDOW_TOOLTIP or + * SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that + * haven't set a specific type, this hint can be used to specify a custom + * type. For example, a dock window might set this to + * "_NET_WM_WINDOW_TYPE_DOCK". * * This hint should be set before creating a window. * @@ -3108,7 +3672,8 @@ extern "C" { #define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" /** - * A variable controlling whether XInput should be used for controller handling. + * A variable controlling whether XInput should be used for controller + * handling. * * The variable can be set to the following values: * @@ -3122,7 +3687,7 @@ extern "C" { #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" /** - * An enumeration of hint priorities. + * An enumeration of hint priorities. * * \since This enum is available since SDL 3.0.0. */ diff --git a/include/SDL3/SDL_init.h b/include/SDL3/SDL_init.h index 4a03b4012..b812fce17 100644 --- a/include/SDL3/SDL_init.h +++ b/include/SDL3/SDL_init.h @@ -40,10 +40,10 @@ extern "C" { /* As of version 0.5, SDL is loaded dynamically into the application */ /** - * Initialization flags for SDL_Init and/or SDL_InitSubSystem + * Initialization flags for SDL_Init and/or SDL_InitSubSystem * - * These are the flags which may be passed to SDL_Init(). You should - * specify the subsystems which you will be using in your application. + * These are the flags which may be passed to SDL_Init(). You should specify + * the subsystems which you will be using in your application. * * \sa SDL_Init * \sa SDL_Quit diff --git a/include/SDL3/SDL_iostream.h b/include/SDL3/SDL_iostream.h index fb5e6e027..0d4a7c3af 100644 --- a/include/SDL3/SDL_iostream.h +++ b/include/SDL3/SDL_iostream.h @@ -56,11 +56,10 @@ typedef enum SDL_IOStatus /** * The function pointers that drive an SDL_IOStream. * - * Applications can provide this struct to SDL_OpenIO() to - * create their own implementation of SDL_IOStream. This is - * not necessarily required, as SDL already offers several - * common types of I/O streams, via functions like SDL_IOFromFile() - * and SDL_IOFromMem(). + * Applications can provide this struct to SDL_OpenIO() to create their own + * implementation of SDL_IOStream. This is not necessarily required, as SDL + * already offers several common types of I/O streams, via functions like + * SDL_IOFromFile() and SDL_IOFromMem(). * * \since This struct is available since SDL 3.0.0. */ @@ -120,10 +119,10 @@ typedef struct SDL_IOStreamInterface /** * The read/write operation structure. * - * This operates as an opaque handle. There are several APIs to create - * various types of I/O streams, or an app can supply an - * SDL_IOStreamInterface to SDL_OpenIO() to provide their own stream - * implementation behind this struct's abstract interface. + * This operates as an opaque handle. There are several APIs to create various + * types of I/O streams, or an app can supply an SDL_IOStreamInterface to + * SDL_OpenIO() to provide their own stream implementation behind this + * struct's abstract interface. * * \since This struct is available since SDL 3.0.0. */ @@ -323,8 +322,8 @@ extern DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromDynamicMem(void); * * You must free the returned pointer with SDL_CloseIO(). * - * This function makes a copy of `iface` and the caller does not need to - * keep this data around after this call. + * This function makes a copy of `iface` and the caller does not need to keep + * this data around after this call. * * \param iface The function pointers that implement this SDL_IOStream. * \param userdata The app-controlled pointer that is passed to iface's diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h index 97a9835ce..9791c8283 100644 --- a/include/SDL3/SDL_joystick.h +++ b/include/SDL3/SDL_joystick.h @@ -356,8 +356,10 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(SDL_JoystickTyp /** * The structure that defines an extended virtual joystick description * - * The caller must zero the structure and then initialize the version with `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to SDL_AttachVirtualJoystickEx() - * All other elements of this structure are optional and can be left 0. + * The caller must zero the structure and then initialize the version with + * `SDL_VIRTUAL_JOYSTICK_DESC_VERSION` before passing it to + * SDL_AttachVirtualJoystickEx() All other elements of this structure are + * optional and can be left 0. * * \sa SDL_AttachVirtualJoystickEx */ diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h index 9ece2a1d7..fc70b229b 100644 --- a/include/SDL3/SDL_keyboard.h +++ b/include/SDL3/SDL_keyboard.h @@ -42,9 +42,10 @@ extern "C" { typedef Uint32 SDL_KeyboardID; /** - * The SDL keysym structure, used in key events. + * The SDL keysym structure, used in key events. * - * If you are looking for translated character input, see the ::SDL_EVENT_TEXT_INPUT event. + * If you are looking for translated character input, see the + * ::SDL_EVENT_TEXT_INPUT event. */ typedef struct SDL_Keysym { diff --git a/include/SDL3/SDL_locale.h b/include/SDL3/SDL_locale.h index 4b6faf86d..16caf2096 100644 --- a/include/SDL3/SDL_locale.h +++ b/include/SDL3/SDL_locale.h @@ -42,10 +42,10 @@ extern "C" { /** * A struct to provide locale data. * - * Locale data is split into a spoken language, like English, and an - * optional country, like Canada. The language will be in ISO-639 format - * (so English would be "en"), and the country, if not NULL, will be an - * ISO-3166 country code (so Canada would be "CA"). + * Locale data is split into a spoken language, like English, and an optional + * country, like Canada. The language will be in ISO-639 format (so English + * would be "en"), and the country, if not NULL, will be an ISO-3166 country + * code (so Canada would be "CA"). * * \since This function is available since SDL 3.0.0. * diff --git a/include/SDL3/SDL_log.h b/include/SDL3/SDL_log.h index 2d8ecded7..be611e3f3 100644 --- a/include/SDL3/SDL_log.h +++ b/include/SDL3/SDL_log.h @@ -47,19 +47,18 @@ extern "C" { /** - * The maximum size of a log message prior to SDL 2.0.24. + * The maximum size of a log message prior to SDL 2.0.24. * - * As of 2.0.24 there is no limit to the length of SDL log messages. + * As of 2.0.24 there is no limit to the length of SDL log messages. */ #define SDL_MAX_LOG_MESSAGE 4096 /** - * The predefined log categories + * The predefined log categories * - * By default the application category is enabled at the INFO level, - * the assert category is enabled at the WARN level, test is enabled - * at the VERBOSE level and all other categories are enabled at the - * ERROR level. + * By default the application category is enabled at the INFO level, the + * assert category is enabled at the WARN level, test is enabled at the + * VERBOSE level and all other categories are enabled at the ERROR level. */ typedef enum SDL_LogCategory { @@ -97,7 +96,7 @@ typedef enum SDL_LogCategory } SDL_LogCategory; /** - * The predefined log priorities + * The predefined log priorities */ typedef enum SDL_LogPriority { diff --git a/include/SDL3/SDL_messagebox.h b/include/SDL3/SDL_messagebox.h index 59e3203e7..2e97dba28 100644 --- a/include/SDL3/SDL_messagebox.h +++ b/include/SDL3/SDL_messagebox.h @@ -33,7 +33,9 @@ extern "C" { #endif /** - * SDL_MessageBox flags. If supported will display warning icon, etc. + * SDL_MessageBox flags. + * + * If supported will display warning icon, etc. */ typedef enum SDL_MessageBoxFlags { diff --git a/include/SDL3/SDL_mouse.h b/include/SDL3/SDL_mouse.h index 89f54dbc6..0451b131d 100644 --- a/include/SDL3/SDL_mouse.h +++ b/include/SDL3/SDL_mouse.h @@ -509,9 +509,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_CursorVisible(void); /** * Used as a mask when testing buttons in buttonstate. * - * - Button 1: Left mouse button - * - Button 2: Middle mouse button - * - Button 3: Right mouse button + * - Button 1: Left mouse button + * - Button 2: Middle mouse button + * - Button 3: Right mouse button */ #define SDL_BUTTON(X) (1 << ((X)-1)) #define SDL_BUTTON_LEFT 1 diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h index 8c6c5a6da..8b4ad5fab 100644 --- a/include/SDL3/SDL_mutex.h +++ b/include/SDL3/SDL_mutex.h @@ -116,8 +116,8 @@ extern "C" { #endif /** - * Synchronization functions which can time out return this value - * if they time out. + * Synchronization functions which can time out return this value if they time + * out. */ #define SDL_MUTEX_TIMEDOUT 1 diff --git a/include/SDL3/SDL_pen.h b/include/SDL3/SDL_pen.h index a20e1f67f..f275171e2 100644 --- a/include/SDL3/SDL_pen.h +++ b/include/SDL3/SDL_pen.h @@ -66,11 +66,12 @@ typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a sessio /** * Pen axis indices * - * Below are the valid indices to the "axis" array from SDL_PenMotionEvent and SDL_PenButtonEvent. - * The axis indices form a contiguous range of ints from 0 to SDL_PEN_AXIS_LAST, inclusive. - * All "axis[]" entries are either normalised to 0..1 or report a (positive or negative) - * angle in degrees, with 0.0 representing the centre. - * Not all pens/backends support all axes: unsupported entries are always "0.0f". + * Below are the valid indices to the "axis" array from SDL_PenMotionEvent and + * SDL_PenButtonEvent. The axis indices form a contiguous range of ints from 0 + * to SDL_PEN_AXIS_LAST, inclusive. All "axis[]" entries are either normalised + * to 0..1 or report a (positive or negative) angle in degrees, with 0.0 + * representing the centre. Not all pens/backends support all axes: + * unsupported entries are always "0.0f". * * To convert angles for tilt and rotation into vector representation, use * SDL_sinf on the XTILT, YTILT, or ROTATION component, for example: @@ -122,7 +123,8 @@ typedef enum SDL_PenAxis /** * Pen types * - * Some pens identify as a particular type of drawing device (e.g., an airbrush or a pencil). + * Some pens identify as a particular type of drawing device (e.g., an + * airbrush or a pencil). * * \since This enum is available since SDL 3.0.0 */ @@ -221,10 +223,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id); * \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()) + * 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.0.0 */ @@ -258,10 +260,10 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL * \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. + * 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.0.0 */ diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h index e12eeef1d..209a0831c 100644 --- a/include/SDL3/SDL_pixels.h +++ b/include/SDL3/SDL_pixels.h @@ -457,7 +457,8 @@ typedef enum SDL_ColorType } SDL_ColorType; /** - * The color range, as described by https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en + * The color range, as described by + * https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en */ typedef enum SDL_ColorRange { @@ -467,7 +468,8 @@ typedef enum SDL_ColorRange } SDL_ColorRange; /** - * The color primaries, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en + * The color primaries, as described by + * https://www.itu.int/rec/T-REC-H.273-201612-S/en */ typedef enum SDL_ColorPrimaries { @@ -488,7 +490,8 @@ typedef enum SDL_ColorPrimaries } SDL_ColorPrimaries; /** - * The transfer characteristics, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en + * The transfer characteristics, as described by + * https://www.itu.int/rec/T-REC-H.273-201612-S/en */ typedef enum SDL_TransferCharacteristics { @@ -514,7 +517,8 @@ typedef enum SDL_TransferCharacteristics } SDL_TransferCharacteristics; /** - * The matrix coefficients, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en + * The matrix coefficients, as described by + * https://www.itu.int/rec/T-REC-H.273-201612-S/en */ typedef enum SDL_MatrixCoefficients { @@ -663,9 +667,10 @@ typedef enum SDL_Colorspace /** * A structure that represents a color as RGBA components. * - * The bits of this structure can be directly reinterpreted as an integer-packed - * color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888 - * on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems). + * The bits of this structure can be directly reinterpreted as an + * integer-packed color which uses the SDL_PIXELFORMAT_RGBA32 format + * (SDL_PIXELFORMAT_ABGR8888 on little-endian systems and + * SDL_PIXELFORMAT_RGBA8888 on big-endian systems). * * \since This struct is available since SDL 3.0.0. */ @@ -712,9 +717,8 @@ typedef struct SDL_Palette /** * Details about the format of a pixel. * - * Generally this is used with SDL_Surface, and covers many - * possible configurations, including paletted data and various - * bit patterns. + * Generally this is used with SDL_Surface, and covers many possible + * configurations, including paletted data and various bit patterns. * * \since This struct is available since SDL 3.0.0. */ diff --git a/include/SDL3/SDL_rect.h b/include/SDL3/SDL_rect.h index b96802f81..fd9aabfa0 100644 --- a/include/SDL3/SDL_rect.h +++ b/include/SDL3/SDL_rect.h @@ -40,10 +40,10 @@ extern "C" { /** * The structure that defines a point (using integers). * + * \since This struct is available since SDL 3.0.0. + * * \sa SDL_GetRectEnclosingPoints * \sa SDL_PointInRect - * - * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_Point { @@ -54,10 +54,10 @@ typedef struct SDL_Point /** * The structure that defines a point (using floating point values). * + * \since This struct is available since SDL 3.0.0. + * * \sa SDL_GetRectEnclosingPointsFloat * \sa SDL_PointInRectFloat - * - * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_FPoint { @@ -69,6 +69,8 @@ typedef struct SDL_FPoint /** * A rectangle, with the origin at the upper left (using integers). * + * \since This struct is available since SDL 3.0.0. + * * \sa SDL_RectEmpty * \sa SDL_RectsEqual * \sa SDL_HasRectIntersection @@ -76,8 +78,6 @@ typedef struct SDL_FPoint * \sa SDL_GetRectAndLineIntersection * \sa SDL_GetRectUnion * \sa SDL_GetRectEnclosingPoints - * - * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_Rect { @@ -87,7 +87,10 @@ typedef struct SDL_Rect /** - * A rectangle, with the origin at the upper left (using floating point values). + * A rectangle, with the origin at the upper left (using floating point + * values). + * + * \since This struct is available since SDL 3.0.0. * * \sa SDL_RectEmptyFloat * \sa SDL_RectsEqualFloat @@ -98,8 +101,6 @@ typedef struct SDL_Rect * \sa SDL_GetRectUnionFloat * \sa SDL_GetRectEnclosingPointsFloat * \sa SDL_PointInRectFloat - * - * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_FRect { diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h index 8efd80dee..3fdcb8a70 100644 --- a/include/SDL3/SDL_render.h +++ b/include/SDL3/SDL_render.h @@ -88,7 +88,7 @@ typedef struct SDL_RendererInfo } SDL_RendererInfo; /** - * Vertex structure. + * Vertex structure. */ typedef struct SDL_Vertex { diff --git a/include/SDL3/SDL_sensor.h b/include/SDL3/SDL_sensor.h index fa347a0c3..dded4c36a 100644 --- a/include/SDL3/SDL_sensor.h +++ b/include/SDL3/SDL_sensor.h @@ -81,16 +81,16 @@ typedef enum /** * Accelerometer sensor. * - * The accelerometer returns the current acceleration in SI meters per - * second squared. This measurement includes the force of gravity, so - * a device at rest will have an value of SDL_STANDARD_GRAVITY away - * from the center of the earth, which is a positive Y value. + * The accelerometer returns the current acceleration in SI meters per second + * squared. This measurement includes the force of gravity, so a device at + * rest will have an value of SDL_STANDARD_GRAVITY away from the center of the + * earth, which is a positive Y value. * - * values[0]: Acceleration on the x axis - * values[1]: Acceleration on the y axis + * values[0]: Acceleration on the x axis values[1]: Acceleration on the y axis * values[2]: Acceleration on the z axis * - * For phones and tablets held in natural orientation and game controllers held in front of you, the axes are defined as follows: + * For phones and tablets held in natural orientation and game controllers + * held in front of you, the axes are defined as follows: * * - -X ... +X : left ... right * - -Y ... +Y : bottom ... top @@ -98,7 +98,7 @@ typedef enum * * The axis data is not changed when the device is rotated. * - * \sa SDL_GetCurrentDisplayOrientation() + * \sa SDL_GetCurrentDisplayOrientation */ #define SDL_STANDARD_GRAVITY 9.80665f diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h index c2f708fc8..111b27b09 100644 --- a/include/SDL3/SDL_stdinc.h +++ b/include/SDL3/SDL_stdinc.h @@ -87,15 +87,15 @@ char *alloca(); #endif /** - * The number of elements in an array. + * The number of elements in an array. */ #define SDL_arraysize(array) (sizeof(array)/sizeof(array[0])) #define SDL_TABLESIZE(table) SDL_arraysize(table) /** - * Macro useful for building other macros with strings in them. + * Macro useful for building other macros with strings in them. * - * For example: + * For example: * * ```c * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` @@ -146,30 +146,35 @@ typedef int SDL_bool; #define SDL_MAX_SINT8 ((Sint8)0x7F) /* 127 */ #define SDL_MIN_SINT8 ((Sint8)(~0x7F)) /* -128 */ typedef int8_t Sint8; + /** * An unsigned 8-bit integer type. */ #define SDL_MAX_UINT8 ((Uint8)0xFF) /* 255 */ #define SDL_MIN_UINT8 ((Uint8)0x00) /* 0 */ typedef uint8_t Uint8; + /** * A signed 16-bit integer type. */ #define SDL_MAX_SINT16 ((Sint16)0x7FFF) /* 32767 */ #define SDL_MIN_SINT16 ((Sint16)(~0x7FFF)) /* -32768 */ typedef int16_t Sint16; + /** * An unsigned 16-bit integer type. */ #define SDL_MAX_UINT16 ((Uint16)0xFFFF) /* 65535 */ #define SDL_MIN_UINT16 ((Uint16)0x0000) /* 0 */ typedef uint16_t Uint16; + /** * A signed 32-bit integer type. */ #define SDL_MAX_SINT32 ((Sint32)0x7FFFFFFF) /* 2147483647 */ #define SDL_MIN_SINT32 ((Sint32)(~0x7FFFFFFF)) /* -2147483648 */ typedef int32_t Sint32; + /** * An unsigned 32-bit integer type. */ @@ -183,6 +188,7 @@ typedef uint32_t Uint32; #define SDL_MAX_SINT64 ((Sint64)0x7FFFFFFFFFFFFFFFll) /* 9223372036854775807 */ #define SDL_MIN_SINT64 ((Sint64)(~0x7FFFFFFFFFFFFFFFll)) /* -9223372036854775808 */ typedef int64_t Sint64; + /** * An unsigned 64-bit integer type. */ @@ -191,10 +197,12 @@ typedef int64_t Sint64; typedef uint64_t Uint64; /** - * SDL times are signed, 64-bit integers representing nanoseconds since the Unix epoch (Jan 1, 1970). + * SDL times are signed, 64-bit integers representing nanoseconds since the + * Unix epoch (Jan 1, 1970). * - * They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS() and SDL_SECONDS_TO_NS(), - * and between Windows FILETIME values with SDL_TimeToWindows() and SDL_TimeFromWindows(). + * They can be converted between POSIX time_t values with SDL_NS_TO_SECONDS() + * and SDL_SECONDS_TO_NS(), and between Windows FILETIME values with + * SDL_TimeToWindows() and SDL_TimeFromWindows(). */ #define SDL_MAX_TIME SDL_MAX_SINT64 #define SDL_MIN_TIME SDL_MIN_SINT64 diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h index 779b11f29..b106ea71c 100644 --- a/include/SDL3/SDL_surface.h +++ b/include/SDL3/SDL_surface.h @@ -60,7 +60,7 @@ extern "C" { /* @} *//* Surface flags */ /** - * Evaluates to true if the surface needs to be locked before access. + * Evaluates to true if the surface needs to be locked before access. */ #define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0) @@ -89,21 +89,17 @@ typedef enum SDL_FlipMode /** * A collection of pixels used in software blitting. * - * Pixels are arranged in memory in rows, with the top row first. - * Each row occupies an amount of memory given by the pitch (sometimes - * known as the row stride in non-SDL APIs). + * Pixels are arranged in memory in rows, with the top row first. Each row + * occupies an amount of memory given by the pitch (sometimes known as the row + * stride in non-SDL APIs). * - * Within each row, pixels are arranged from left to right until the - * width is reached. - * Each pixel occupies a number of bits appropriate for its format, with - * most formats representing each pixel as one or more whole bytes - * (in some indexed formats, instead multiple pixels are packed into - * each byte), and a byte order given by the format. - * After encoding all pixels, any remaining bytes to reach the pitch are - * used as padding to reach a desired alignment, and have undefined contents. - * - * \note This structure should be treated as read-only, except for \c pixels, - * which, if not NULL, contains the raw pixel data for the surface. + * Within each row, pixels are arranged from left to right until the width is + * reached. Each pixel occupies a number of bits appropriate for its format, + * with most formats representing each pixel as one or more whole bytes (in + * some indexed formats, instead multiple pixels are packed into each byte), + * and a byte order given by the format. After encoding all pixels, any + * remaining bytes to reach the pitch are used as padding to reach a desired + * alignment, and have undefined contents. */ typedef struct SDL_Surface { diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h index fa1272eef..95fd640a5 100644 --- a/include/SDL3/SDL_system.h +++ b/include/SDL3/SDL_system.h @@ -337,9 +337,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void); extern DECLSPEC void SDLCALL SDL_AndroidBackButton(void); /** - See the official Android developer guide for more information: - http://developer.android.com/guide/topics/data/data-storage.html -*/ + * See the official Android developer guide for more information: + * http://developer.android.com/guide/topics/data/data-storage.html + */ #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 @@ -479,7 +479,7 @@ extern DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param); #ifdef SDL_PLATFORM_WINRT /** - * WinRT / Windows Phone path types + * WinRT / Windows Phone path types */ typedef enum SDL_WinRT_Path { @@ -503,7 +503,7 @@ typedef enum SDL_WinRT_Path /** - * WinRT Device Family + * WinRT Device Family */ typedef enum SDL_WinRT_DeviceFamily { diff --git a/include/SDL3/SDL_thread.h b/include/SDL3/SDL_thread.h index 1dd4bb806..40e8b4c15 100644 --- a/include/SDL3/SDL_thread.h +++ b/include/SDL3/SDL_thread.h @@ -56,14 +56,13 @@ typedef Uint64 SDL_ThreadID; typedef Uint32 SDL_TLSID; /** - * The SDL thread priority. + * The SDL thread priority. * - * SDL will make system changes as necessary in order to apply the thread priority. - * Code which attempts to control thread state related to priority should be aware - * that calling SDL_SetThreadPriority may alter such state. - * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this behavior. - * - * \note On many systems you require special privileges to set high or time critical priority. + * SDL will make system changes as necessary in order to apply the thread + * priority. Code which attempts to control thread state related to priority + * should be aware that calling SDL_SetThreadPriority may alter such state. + * SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of this + * behavior. */ typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_LOW, diff --git a/include/SDL3/SDL_time.h b/include/SDL3/SDL_time.h index ff04fa5bf..673d150ce 100644 --- a/include/SDL3/SDL_time.h +++ b/include/SDL3/SDL_time.h @@ -38,7 +38,8 @@ extern "C" { #endif /** - * A structure holding a calendar date and time broken down into its components. + * A structure holding a calendar date and time broken down into its + * components. */ typedef struct SDL_DateTime { diff --git a/include/SDL3/SDL_version.h b/include/SDL3/SDL_version.h index 24c141166..9f6394c2f 100644 --- a/include/SDL3/SDL_version.h +++ b/include/SDL3/SDL_version.h @@ -41,15 +41,14 @@ extern "C" { * Information about the version of SDL in use. * * Represents the library's version as three levels: major revision - * (increments with massive changes, additions, and enhancements), - * minor revision (increments with backwards-compatible changes to the - * major revision), and patchlevel (increments with fixes to the minor - * revision). + * (increments with massive changes, additions, and enhancements), minor + * revision (increments with backwards-compatible changes to the major + * revision), and patchlevel (increments with fixes to the minor revision). + * + * \since This struct is available since SDL 3.0.0. * * \sa SDL_VERSION * \sa SDL_GetVersion - * - * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_Version { @@ -70,15 +69,15 @@ typedef struct SDL_Version * library you compiled against. This is determined by what header the * compiler uses. Note that if you dynamically linked the library, you might * have a slightly newer or older version at runtime. That version can be - * determined with SDL_GetVersion(), which, unlike SDL_VERSION(), - * is not a macro. + * determined with SDL_GetVersion(), which, unlike SDL_VERSION(), is not a + * macro. * * \param x A pointer to an SDL_Version struct to initialize. * + * \since This macro is available since SDL 3.0.0. + * * \sa SDL_Version * \sa SDL_GetVersion - * - * \since This macro is available since SDL 3.0.0. */ #define SDL_VERSION(x) \ { \ @@ -102,7 +101,7 @@ typedef struct SDL_Version ((major) << 24 | (minor) << 8 | (patch) << 0) /** - * This is the version number macro for the current SDL version. + * This is the version number macro for the current SDL version. * * \since This macro is available since SDL 3.0.0. */ @@ -110,7 +109,7 @@ typedef struct SDL_Version SDL_VERSIONNUM(SDL_MAJOR_VERSION, SDL_MINOR_VERSION, SDL_PATCHLEVEL) /** - * This macro will evaluate to true if compiled with SDL at least X.Y.Z. + * This macro will evaluate to true if compiled with SDL at least X.Y.Z. * * \since This macro is available since SDL 3.0.0. */ diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index 770210e73..4610460b7 100644 --- a/include/SDL3/SDL_video.h +++ b/include/SDL3/SDL_video.h @@ -76,13 +76,13 @@ typedef enum SDL_SystemTheme /** * The structure that defines a display mode. * - * \sa SDL_GetFullscreenDisplayModes() - * \sa SDL_GetDesktopDisplayMode() - * \sa SDL_GetCurrentDisplayMode() - * \sa SDL_SetWindowFullscreenMode() - * \sa SDL_GetWindowFullscreenMode() - * * \since This struct is available since SDL 3.0.0. + * + * \sa SDL_GetFullscreenDisplayModes + * \sa SDL_GetDesktopDisplayMode + * \sa SDL_GetCurrentDisplayMode + * \sa SDL_SetWindowFullscreenMode + * \sa SDL_GetWindowFullscreenMode */ typedef struct SDL_DisplayMode { @@ -110,7 +110,7 @@ typedef enum SDL_DisplayOrientation } SDL_DisplayOrientation; /** - * The struct used as an opaque handle to a window. + * The struct used as an opaque handle to a window. * * \since This struct is available since SDL 3.0.0. * @@ -155,7 +155,7 @@ typedef Uint32 SDL_WindowFlags; #define SDL_WINDOW_NOT_FOCUSABLE 0x80000000U /**< window should not be focusable */ /** - * Used to indicate that you don't care what the window position is. + * Used to indicate that you don't care what the window position is. */ #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u #define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) @@ -164,7 +164,7 @@ typedef Uint32 SDL_WindowFlags; (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) /** - * Used to indicate that the window position should be centered. + * Used to indicate that the window position should be centered. */ #define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) @@ -207,9 +207,17 @@ typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); /** * An enumeration of OpenGL configuration attributes. * - * While you can set most OpenGL attributes normally, the attributes listed above must be known before SDL creates the window that will be used with the OpenGL context. These attributes are set and read with SDL_GL_SetAttribute() and SDL_GL_GetAttribute(). + * While you can set most OpenGL attributes normally, the attributes listed + * above must be known before SDL creates the window that will be used with + * the OpenGL context. These attributes are set and read with + * SDL_GL_SetAttribute() and SDL_GL_GetAttribute(). * - * In some cases, these attributes are minimum requests; the GL does not promise to give you exactly what you asked for. It's possible to ask for a 16-bit depth buffer and get a 24-bit one instead, for example, or to ask for no stencil buffer and still have one available. Context creation should fail if the GL can't provide your requested attributes at a minimum, but you should check to see exactly what you got. + * In some cases, these attributes are minimum requests; the GL does not + * promise to give you exactly what you asked for. It's possible to ask for a + * 16-bit depth buffer and get a 24-bit one instead, for example, or to ask + * for no stencil buffer and still have one available. Context creation should + * fail if the GL can't provide your requested attributes at a minimum, but + * you should check to see exactly what you got. * * \since This enum is available since SDL 3.0.0. */ @@ -271,7 +279,8 @@ typedef enum SDL_GLcontextFlag } SDL_GLcontextFlag; /** - * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR attribute. + * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR + * attribute. * * \since This enum is available since SDL 3.0.0. */