From ad090d2444b35c54fc38c1353d8f8d00058ca1e4 Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Mon, 8 Apr 2024 22:36:57 -0400 Subject: [PATCH] include: A ton of little documentation tweaks, fixes, and improvements. This is just stuff I noticed while working on the wikiheaders updates. A thorough pass over all the docs would not be terrible, and maybe a simple script to check for consistency (does everything have a `\since` on it? etc) might be nice, too. --- include/SDL3/SDL_assert.h | 9 + include/SDL3/SDL_audio.h | 45 +- include/SDL3/SDL_blendmode.h | 27 +- include/SDL3/SDL_camera.h | 12 +- include/SDL3/SDL_clipboard.h | 8 +- include/SDL3/SDL_dialog.h | 2 +- include/SDL3/SDL_error.h | 4 +- include/SDL3/SDL_events.h | 22 +- include/SDL3/SDL_filesystem.h | 4 +- include/SDL3/SDL_gamepad.h | 16 +- include/SDL3/SDL_haptic.h | 264 ++++--- include/SDL3/SDL_hidapi.h | 10 +- include/SDL3/SDL_hints.h | 1284 ++++++++++++++++++++++--------- include/SDL3/SDL_init.h | 2 +- include/SDL3/SDL_iostream.h | 23 +- include/SDL3/SDL_joystick.h | 12 +- include/SDL3/SDL_keyboard.h | 4 +- include/SDL3/SDL_keycode.h | 48 +- include/SDL3/SDL_locale.h | 13 +- include/SDL3/SDL_log.h | 6 +- include/SDL3/SDL_messagebox.h | 14 +- include/SDL3/SDL_mouse.h | 4 +- include/SDL3/SDL_pen.h | 112 ++- include/SDL3/SDL_pixels.h | 56 +- include/SDL3/SDL_power.h | 8 +- include/SDL3/SDL_properties.h | 42 +- include/SDL3/SDL_rect.h | 16 +- include/SDL3/SDL_render.h | 16 +- include/SDL3/SDL_scancode.h | 19 +- include/SDL3/SDL_sensor.h | 20 +- include/SDL3/SDL_stdinc.h | 22 +- include/SDL3/SDL_surface.h | 8 +- include/SDL3/SDL_system.h | 10 +- include/SDL3/SDL_test_assert.h | 20 +- include/SDL3/SDL_test_crc32.h | 8 +- include/SDL3/SDL_test_font.h | 22 +- include/SDL3/SDL_test_harness.h | 8 +- include/SDL3/SDL_thread.h | 2 +- include/SDL3/SDL_time.h | 6 +- include/SDL3/SDL_timer.h | 4 +- include/SDL3/SDL_touch.h | 19 +- include/SDL3/SDL_version.h | 28 +- include/SDL3/SDL_video.h | 115 ++- include/SDL3/SDL_vulkan.h | 2 +- src/hidapi/SDL_hidapi.c | 2 +- 45 files changed, 1565 insertions(+), 833 deletions(-) diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h index 9d6cba57f..6863f4c98 100644 --- a/include/SDL3/SDL_assert.h +++ b/include/SDL3/SDL_assert.h @@ -125,6 +125,15 @@ typedef enum SDL_ASSERTION_ALWAYS_IGNORE /**< Ignore the assert from now on. */ } SDL_AssertState; +/** + * 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(). + * + * \since This struct is available since SDL 3.0.0. + */ typedef struct SDL_AssertData { SDL_bool always_ignore; diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h index feac79c5a..7a7ee934b 100644 --- a/include/SDL3/SDL_audio.h +++ b/include/SDL3/SDL_audio.h @@ -146,6 +146,13 @@ typedef Uint32 SDL_AudioDeviceID; #define SDL_AUDIO_DEVICE_DEFAULT_OUTPUT ((SDL_AudioDeviceID) 0xFFFFFFFF) #define SDL_AUDIO_DEVICE_DEFAULT_CAPTURE ((SDL_AudioDeviceID) 0xFFFFFFFE) +/** + * Format specifier for audio data. + * + * \sa SDL_AudioFormat + * + * \since This struct is available since SDL 3.0.0. + */ typedef struct SDL_AudioSpec { SDL_AudioFormat format; /**< Audio data format */ @@ -156,18 +163,30 @@ typedef struct SDL_AudioSpec /* Calculate the size of each audio frame (in bytes) */ #define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels) -/* 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 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. +/** + * The opaque handle that represents an audio stream. + * + * 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 incoming data in any variable size. + * - It can handle input/output format changes on the fly. + * - You push data as you have it, and pull it when you need it + * - It can also function as a basic audio data queue even if you + * just have sound that needs to pass from one place to another. + * - You can hook callbacks up to them when more data is added or + * requested, to manage data on-the-fly. + * + * Audio streams are the core of the SDL3 audio interface. You create + * one or more of them, bind them to an opened audio device, and feed + * data to them (or for recording, consume data from them). + * + * \since This struct is available since SDL 3.0.0. + * + * \sa SDL_CreateAudioStream */ -struct SDL_AudioStream; /* this is opaque to the outside world. */ +struct SDL_AudioStream; /**< this is opaque to the outside world. */ typedef struct SDL_AudioStream SDL_AudioStream; @@ -903,7 +922,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream); extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream); /** - * Clear any pending data in the stream without converting it + * Clear any pending data in the stream without converting it. * * \param stream The audio stream to clear * \returns 0 on success or a negative error code on failure; call @@ -1090,7 +1109,7 @@ extern DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *strea /** - * Free an audio stream + * Free an audio stream. * * \param stream The audio stream to free * diff --git a/include/SDL3/SDL_blendmode.h b/include/SDL3/SDL_blendmode.h index 8b3667c10..111bf5a53 100644 --- a/include/SDL3/SDL_blendmode.h +++ b/include/SDL3/SDL_blendmode.h @@ -35,9 +35,15 @@ extern "C" { #endif /** - * The blend mode used in SDL_RenderTexture() and drawing operations. + * An enumeration of blend modes used in drawing operations. + * + * Note that additional values may be obtained from SDL_ComposeCustomBlendMode. + * + * \sa SDL_ComposeCustomBlendMode + * + * \since This enum is available since SDL 3.0.0. */ -typedef enum +typedef enum SDL_BlendMode { SDL_BLENDMODE_NONE = 0x00000000, /**< no blending dstRGBA = srcRGBA */ @@ -60,9 +66,11 @@ typedef enum } 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. */ -typedef enum +typedef enum SDL_BlendOperation { SDL_BLENDOPERATION_ADD = 0x1, /**< dst + src: supported by all renderers */ SDL_BLENDOPERATION_SUBTRACT = 0x2, /**< src - dst : supported by D3D9, D3D11, OpenGL, OpenGLES */ @@ -72,9 +80,16 @@ typedef enum } SDL_BlendOperation; /** - * The normalized factor used to multiply pixel components + * 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. + * + * \since This enum is available since SDL 3.0.0. */ -typedef enum +typedef enum SDL_BlendFactor { SDL_BLENDFACTOR_ZERO = 0x1, /**< 0, 0, 0, 0 */ SDL_BLENDFACTOR_ONE = 0x2, /**< 1, 1, 1, 1 */ diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h index 923fb481d..3546d8b54 100644 --- a/include/SDL3/SDL_camera.h +++ b/include/SDL3/SDL_camera.h @@ -48,19 +48,23 @@ extern "C" { */ typedef Uint32 SDL_CameraDeviceID; - /** - * The structure used to identify an opened SDL camera + * The opaque structure used to identify an opened SDL camera. + * + * \since This struct is available since SDL 3.0.0. */ struct SDL_Camera; typedef struct SDL_Camera SDL_Camera; /** - * SDL_CameraSpec structure + * The details of an output format for a camera device. + * + * Cameras often support multiple formats; each one will be encapsulated in this struct. * * \sa SDL_GetCameraDeviceSupportedFormats * \sa SDL_GetCameraFormat * + * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_CameraSpec { @@ -75,6 +79,8 @@ 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. */ typedef enum SDL_CameraPosition { diff --git a/include/SDL3/SDL_clipboard.h b/include/SDL3/SDL_clipboard.h index 5f0257ee7..c1c8386c6 100644 --- a/include/SDL3/SDL_clipboard.h +++ b/include/SDL3/SDL_clipboard.h @@ -165,7 +165,7 @@ typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const c typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); /** - * Offer clipboard data to the OS + * Offer clipboard data to the OS. * * Tell the operating system that the application is offering clipboard data * for each of the proivded mime-types. Once another application requests the @@ -195,7 +195,7 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata); extern DECLSPEC int SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types); /** - * Clear the clipboard data + * Clear the clipboard data. * * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. @@ -207,7 +207,7 @@ extern DECLSPEC int SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callb extern DECLSPEC int SDLCALL SDL_ClearClipboardData(void); /** - * Get the data from clipboard for a given mime type + * Get the data from clipboard for a given mime type. * * The size of text data does not include the terminator, but the text is * guaranteed to be null terminated. @@ -225,7 +225,7 @@ extern DECLSPEC int SDLCALL SDL_ClearClipboardData(void); extern DECLSPEC void *SDLCALL SDL_GetClipboardData(const char *mime_type, size_t *size); /** - * Query whether there is data in the clipboard for the provided mime type + * Query whether there is data in the clipboard for the provided mime type. * * \param mime_type The mime type to check for data for * \returns SDL_TRUE if there exists data in clipboard for the provided mime diff --git a/include/SDL3/SDL_dialog.h b/include/SDL3/SDL_dialog.h index 134c8194d..6a7402efe 100644 --- a/include/SDL3/SDL_dialog.h +++ b/include/SDL3/SDL_dialog.h @@ -46,7 +46,7 @@ extern "C" { * \sa SDL_ShowSaveFileDialog * \sa SDL_ShowOpenFolderDialog */ -typedef struct +typedef struct SDL_DialogFileFilter { const char *name; const char *pattern; diff --git a/include/SDL3/SDL_error.h b/include/SDL3/SDL_error.h index b6ae7aec0..93a786576 100644 --- a/include/SDL3/SDL_error.h +++ b/include/SDL3/SDL_error.h @@ -122,7 +122,7 @@ extern DECLSPEC void SDLCALL SDL_ClearError(void); #define SDL_OutOfMemory() SDL_Error(SDL_ENOMEM) #define SDL_Unsupported() SDL_Error(SDL_UNSUPPORTED) #define SDL_InvalidParamError(param) SDL_SetError("Parameter '%s' is invalid", (param)) -typedef enum +typedef enum SDL_errorcode { SDL_ENOMEM, SDL_EFREAD, @@ -133,7 +133,7 @@ typedef enum } SDL_errorcode; /** - * SDL_Error() + * Set an SDL error from a list of error codes. * * \param code Error code * \returns unconditionally -1. diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h index 4b1d13917..17417ac43 100644 --- a/include/SDL3/SDL_events.h +++ b/include/SDL3/SDL_events.h @@ -54,7 +54,7 @@ extern "C" { /** * The types of events that can be delivered. */ -typedef enum +typedef enum SDL_EventType { SDL_EVENT_FIRST = 0, /**< Unused (do not remove) */ @@ -671,10 +671,10 @@ 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. + * 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 { @@ -722,7 +722,13 @@ typedef struct SDL_QuitEvent } SDL_QuitEvent; /** - * A user-defined event type (event.user.*) + * A user-defined event type (event.user.*) + * + * 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(). */ typedef struct SDL_UserEvent { @@ -737,7 +743,7 @@ typedef struct SDL_UserEvent /** - * General event structure + * The structure for all events in SDL. */ typedef union SDL_Event { @@ -823,7 +829,7 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL extern DECLSPEC void SDLCALL SDL_PumpEvents(void); /* @{ */ -typedef enum +typedef enum SDL_eventaction { SDL_ADDEVENT, SDL_PEEKEVENT, @@ -1263,7 +1269,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EventEnabled(Uint32 type); extern DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents); /** - * Allocate dynamic memory for an SDL event + * Allocate dynamic memory for an SDL event. * * You can use this to allocate memory for user events that will be * automatically freed after the event is processed. diff --git a/include/SDL3/SDL_filesystem.h b/include/SDL3/SDL_filesystem.h index 971a19bee..7b4bff582 100644 --- a/include/SDL3/SDL_filesystem.h +++ b/include/SDL3/SDL_filesystem.h @@ -162,11 +162,11 @@ extern DECLSPEC char *SDLCALL SDL_GetPrefPath(const char *org, const char *app); * | TEMPLATES | X | X | | X | | | * | VIDEOS | X | X* | | X | | | * - * * Note that on macOS/iOS, the Videos folder is called "Movies". + * Note that on macOS/iOS, the Videos folder is called "Movies". * * \sa SDL_GetUserFolder */ -typedef enum +typedef enum SDL_Folder { /** The folder which contains all of the current user's data, preferences, and documents. It usually contains most of the other folders. If a diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h index 9d2e86eaa..a889c73c7 100644 --- a/include/SDL3/SDL_gamepad.h +++ b/include/SDL3/SDL_gamepad.h @@ -59,7 +59,7 @@ extern "C" { struct SDL_Gamepad; typedef struct SDL_Gamepad SDL_Gamepad; -typedef enum +typedef enum SDL_GamepadType { SDL_GAMEPAD_TYPE_UNKNOWN = 0, SDL_GAMEPAD_TYPE_STANDARD, @@ -95,7 +95,7 @@ typedef enum * * You can query the labels for the face buttons using SDL_GetGamepadButtonLabel() */ -typedef enum +typedef enum SDL_GamepadButton { SDL_GAMEPAD_BUTTON_INVALID = -1, SDL_GAMEPAD_BUTTON_SOUTH, /* Bottom face button (e.g. Xbox A button) */ @@ -134,7 +134,7 @@ typedef enum * * 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 +typedef enum SDL_GamepadButtonLabel { SDL_GAMEPAD_BUTTON_LABEL_UNKNOWN, SDL_GAMEPAD_BUTTON_LABEL_A, @@ -158,7 +158,7 @@ typedef enum * (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 +typedef enum SDL_GamepadAxis { SDL_GAMEPAD_AXIS_INVALID = -1, SDL_GAMEPAD_AXIS_LEFTX, @@ -170,7 +170,7 @@ typedef enum SDL_GAMEPAD_AXIS_MAX } SDL_GamepadAxis; -typedef enum +typedef enum SDL_GamepadBindingType { SDL_GAMEPAD_BINDTYPE_NONE = 0, SDL_GAMEPAD_BINDTYPE_BUTTON, @@ -886,7 +886,7 @@ extern DECLSPEC SDL_PowerState SDLCALL SDL_GetGamepadPowerInfo(SDL_Gamepad *game extern DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad); /** - * Get the underlying joystick from a gamepad + * Get the underlying joystick from a gamepad. * * This function will give you a SDL_Joystick object, which allows you to use * the SDL_Joystick functions with a SDL_Gamepad object. This would be useful @@ -935,7 +935,7 @@ extern DECLSPEC void SDLCALL SDL_SetGamepadEventsEnabled(SDL_bool enabled); extern DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void); /** - * Get the SDL joystick layer bindings for a gamepad + * Get the SDL joystick layer bindings for a gamepad. * * \param gamepad a gamepad * \param count a pointer filled in with the number of bindings returned @@ -1350,7 +1350,7 @@ extern DECLSPEC int SDLCALL SDL_RumbleGamepadTriggers(SDL_Gamepad *gamepad, Uint extern DECLSPEC int SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, Uint8 green, Uint8 blue); /** - * Send a gamepad specific effect packet + * Send a gamepad specific effect packet. * * \param gamepad The gamepad to affect * \param data The data to send to the gamepad diff --git a/include/SDL3/SDL_haptic.h b/include/SDL3/SDL_haptic.h index 3bc17b8a8..d79ad4da4 100644 --- a/include/SDL3/SDL_haptic.h +++ b/include/SDL3/SDL_haptic.h @@ -25,18 +25,20 @@ * The SDL haptic subsystem manages haptic (force feedback) devices. * * The basic usage is as follows: - * - Initialize the subsystem (::SDL_INIT_HAPTIC). + * + * - Initialize the subsystem (SDL_INIT_HAPTIC). * - Open a haptic device. * - SDL_OpenHaptic() to open from index. * - SDL_OpenHapticFromJoystick() to open from an existing joystick. - * - Create an effect (::SDL_HapticEffect). + * - Create an effect (SDL_HapticEffect). * - Upload the effect with SDL_CreateHapticEffect(). * - Run the effect with SDL_RunHapticEffect(). * - (optional) Free the effect with SDL_DestroyHapticEffect(). * - Close the haptic device with SDL_CloseHaptic(). * - * \par Simple rumble example: - * \code + * Simple rumble example: + * + * ```c * SDL_Haptic *haptic = NULL; * * // Open the device @@ -59,10 +61,11 @@ * * // Clean up * SDL_CloseHaptic(haptic); - * \endcode + * ``` * - * \par Complete example: - * \code + * Complete example: + * + * ```c * int test_haptic(SDL_Joystick *joystick) * { * SDL_Haptic *haptic; @@ -105,7 +108,7 @@ * * return 0; // Success * } - * \endcode + * ``` * * Note that the SDL haptic subsystem is not thread-safe. */ @@ -386,52 +389,56 @@ typedef struct SDL_Haptic SDL_Haptic; * instead of the direction in which the force is exerted. * * 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. * * The following diagram represents the cardinal directions: - * \verbatim - .--. - |__| .-------. - |=.| |.-----.| - |--| || || - | | |'-----'| - |__|~')_____(' - [ COMPUTER ] - - - North (0,-1) - ^ - | - | - (-1,0) West <----[ HAPTIC ]----> East (1,0) - | - | - v - South (0,1) - - - [ USER ] - \|||/ - (o o) - ---ooO-(_)-Ooo--- - \endverbatim * - * 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 \c dir parameter. The cardinal directions would be: + * ``` + * .--. + * |__| .-------. + * |=.| |.-----.| + * |--| || || + * | | |'-----'| + * |__|~')_____(' + * [ COMPUTER ] + * + * + * North (0,-1) + * ^ + * | + * | + * (-1,0) West <----[ HAPTIC ]----> East (1,0) + * | + * | + * v + * South (0,1) + * + * + * [ USER ] + * \|||/ + * (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: + * * - 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 \c 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 @@ -441,16 +448,17 @@ typedef struct SDL_Haptic SDL_Haptic; * 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 \c dir parameters are used. The \c dir parameters are as + * 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). * - * * 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): - * \code + * + * ```c * SDL_HapticDirection direction; * * // Cartesian directions @@ -466,7 +474,7 @@ 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. - * \endcode + * ``` * * \sa SDL_HAPTIC_POLAR * \sa SDL_HAPTIC_CARTESIAN @@ -485,7 +493,7 @@ typedef struct SDL_HapticDirection /** * 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. @@ -496,7 +504,7 @@ typedef struct SDL_HapticDirection typedef struct SDL_HapticConstant { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_CONSTANT */ + Uint16 type; /**< SDL_HAPTIC_CONSTANT */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -521,11 +529,12 @@ typedef struct SDL_HapticConstant * A structure containing a template for a Periodic effect. * * 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 @@ -533,6 +542,7 @@ typedef struct SDL_HapticConstant * * 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. @@ -540,32 +550,33 @@ typedef struct SDL_HapticConstant * - 36000: Displaced 100% of its period, same as 0, but 0 is preferred. * * Examples: - * \verbatim - SDL_HAPTIC_SINE - __ __ __ __ - / \ / \ / \ / - / \__/ \__/ \__/ - - SDL_HAPTIC_SQUARE - __ __ __ __ __ - | | | | | | | | | | - | |__| |__| |__| |__| | - - SDL_HAPTIC_TRIANGLE - /\ /\ /\ /\ /\ - / \ / \ / \ / \ / - / \/ \/ \/ \/ - - SDL_HAPTIC_SAWTOOTHUP - /| /| /| /| /| /| /| - / | / | / | / | / | / | / | - / |/ |/ |/ |/ |/ |/ | - - SDL_HAPTIC_SAWTOOTHDOWN - \ |\ |\ |\ |\ |\ |\ | - \ | \ | \ | \ | \ | \ | \ | - \| \| \| \| \| \| \| - \endverbatim + * + * ``` + * SDL_HAPTIC_SINE + * __ __ __ __ + * / \ / \ / \ / + * / \__/ \__/ \__/ + * + * SDL_HAPTIC_SQUARE + * __ __ __ __ __ + * | | | | | | | | | | + * | |__| |__| |__| |__| | + * + * SDL_HAPTIC_TRIANGLE + * /\ /\ /\ /\ /\ + * / \ / \ / \ / \ / + * / \/ \/ \/ \/ + * + * SDL_HAPTIC_SAWTOOTHUP + * /| /| /| /| /| /| /| + * / | / | / | / | / | / | / | + * / |/ |/ |/ |/ |/ |/ | + * + * SDL_HAPTIC_SAWTOOTHDOWN + * \ |\ |\ |\ |\ |\ |\ | + * \ | \ | \ | \ | \ | \ | \ | + * \| \| \| \| \| \| \| + * ``` * * \sa SDL_HAPTIC_SINE * \sa SDL_HAPTIC_SQUARE @@ -577,9 +588,9 @@ typedef struct SDL_HapticConstant typedef struct SDL_HapticPeriodic { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_SINE, ::SDL_HAPTIC_SQUARE - ::SDL_HAPTIC_TRIANGLE, ::SDL_HAPTIC_SAWTOOTHUP or - ::SDL_HAPTIC_SAWTOOTHDOWN */ + Uint16 type; /**< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE + SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or + SDL_HAPTIC_SAWTOOTHDOWN */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -607,17 +618,18 @@ typedef struct SDL_HapticPeriodic * A structure containing a template for a Condition effect. * * 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 + * refer to the SDL_HapticDirection diagram for which side is positive and * which is negative. * * \sa SDL_HapticDirection @@ -630,8 +642,8 @@ typedef struct SDL_HapticPeriodic typedef struct SDL_HapticCondition { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_SPRING, ::SDL_HAPTIC_DAMPER, - ::SDL_HAPTIC_INERTIA or ::SDL_HAPTIC_FRICTION */ + Uint16 type; /**< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, + SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION */ SDL_HapticDirection direction; /**< Direction of the effect - Not used ATM. */ /* Replay */ @@ -654,7 +666,7 @@ typedef struct SDL_HapticCondition /** * 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 @@ -667,7 +679,7 @@ typedef struct SDL_HapticCondition typedef struct SDL_HapticRamp { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_RAMP */ + Uint16 type; /**< SDL_HAPTIC_RAMP */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -692,7 +704,7 @@ typedef struct SDL_HapticRamp /** * A structure containing a template for a Left/Right effect. * - * This struct is exclusively for the ::SDL_HAPTIC_LEFTRIGHT effect. + * This struct is exclusively for the SDL_HAPTIC_LEFTRIGHT effect. * * The Left/Right effect is used to explicitly control the large and small * motors, commonly found in modern game controllers. The small (right) motor @@ -704,7 +716,7 @@ typedef struct SDL_HapticRamp typedef struct SDL_HapticLeftRight { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_LEFTRIGHT */ + Uint16 type; /**< SDL_HAPTIC_LEFTRIGHT */ /* Replay */ Uint32 length; /**< Duration of the effect in milliseconds. */ @@ -715,9 +727,9 @@ 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 @@ -732,7 +744,7 @@ typedef struct SDL_HapticLeftRight typedef struct SDL_HapticCustom { /* Header */ - Uint16 type; /**< ::SDL_HAPTIC_CUSTOM */ + Uint16 type; /**< SDL_HAPTIC_CUSTOM */ SDL_HapticDirection direction; /**< Direction of the effect. */ /* Replay */ @@ -762,12 +774,12 @@ typedef struct SDL_HapticCustom * 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 + * 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. + * 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 @@ -777,7 +789,8 @@ typedef struct SDL_HapticCustom * otherwise both values are used. * * Common parts: - * \code + * + * ```c * // Replay - All effects have this * Uint32 length; // Duration of effect (ms). * Uint16 delay; // Delay before starting effect. @@ -791,29 +804,29 @@ 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. - * \endcode - * + * ``` * * Here we have an example of a constant effect evolution in time: - * \verbatim - Strength - ^ - | - | effect level --> _________________ - | / \ - | / \ - | / \ - | / \ - | attack_level --> | \ - | | | <--- fade_level - | - +--------------------------------------------------> Time - [--] [---] - attack_length fade_length - - [------------------][-----------------------] - delay length - \endverbatim + * + * ``` + * Strength + * ^ + * | + * | effect level --> _________________ + * | / \ + * | / \ + * | / \ + * | / \ + * | attack_level --> | \ + * | | | <--- fade_level + * | + * +--------------------------------------------------> Time + * [--] [---] + * attack_length fade_length + * + * [------------------][-----------------------] + * delay length + * ``` * * Note either the attack_level or the fade_level may be above the actual * effect level. @@ -1058,7 +1071,6 @@ extern DECLSPEC int SDLCALL SDL_GetMaxHapticEffectsPlaying(SDL_Haptic *haptic); */ extern DECLSPEC Uint32 SDLCALL SDL_GetHapticFeatures(SDL_Haptic *haptic); - /** * Get the number of haptic axes the device has. * @@ -1153,8 +1165,6 @@ extern DECLSPEC int SDLCALL SDL_RunHapticEffect(SDL_Haptic *haptic, int effect, /** * Stop the haptic effect on its associated haptic device. * - * * - * * \param haptic the SDL_Haptic device to stop the effect on * \param effect the ID of the haptic effect to stop * \returns 0 on success or a negative error code on failure; call diff --git a/include/SDL3/SDL_hidapi.h b/include/SDL3/SDL_hidapi.h index ecbe0de50..3416ddf21 100644 --- a/include/SDL3/SDL_hidapi.h +++ b/include/SDL3/SDL_hidapi.h @@ -74,13 +74,13 @@ extern "C" { /** * A handle representing an open HID device */ -struct SDL_hid_device_; -typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */ +struct SDL_hid_device; +typedef struct SDL_hid_device SDL_hid_device; /**< opaque hidapi structure */ /** * HID underlying bus types. */ -typedef enum { +typedef enum SDL_hid_bus_type { /** Unknown bus type */ SDL_HID_API_BUS_UNKNOWN = 0x00, @@ -243,7 +243,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void); extern DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned short vendor_id, unsigned short product_id); /** - * Free an enumeration Linked List + * Free an enumeration linked list. * * This function frees a linked list created by SDL_hid_enumerate(). * @@ -534,7 +534,7 @@ extern DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hid_de extern DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *dev, unsigned char *buf, size_t buf_size); /** - * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers + * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers. * * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan * diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h index 5b34233d6..45f4e8fa6 100644 --- a/include/SDL3/SDL_hints.h +++ b/include/SDL3/SDL_hints.h @@ -56,10 +56,13 @@ extern "C" { * 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. - * "1" - SDL will minimize your window when Alt+Tab is pressed (default) + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED" @@ -69,10 +72,13 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY "SDL_ANDROID_ALLOW_RECREATE_ACTIVITY" @@ -80,10 +86,13 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE" @@ -91,10 +100,13 @@ extern "C" { * A variable to control whether SDL will pause audio in background. * * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO" @@ -104,12 +116,15 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON" @@ -123,11 +138,8 @@ extern "C" { * 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 entire ID must be less than 255 characters in length. * * Examples of valid app ID strings: @@ -143,6 +155,8 @@ extern "C" { * If the executable name cannot be retrieved, the generic string "SDL_App" will be used. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_APP_ID "SDL_APP_ID" @@ -162,6 +176,8 @@ extern "C" { * SDL_HINT_AUDIO_DEVICE_APP_NAME. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_APP_NAME "SDL_APP_NAME" @@ -177,10 +193,13 @@ extern "C" { * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/ * * The variable can be set to the following values: - * "0" - Controller input does not generate UI events. (default) - * "1" - Controller input generates UI events. + * + * - "0": Controller input does not generate UI events. (default) + * - "1": Controller input generates UI events. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS" @@ -188,10 +207,13 @@ extern "C" { * 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: - * "0" - Remote orientation does not affect joystick axes. (default) - * "1" - Joystick axes are based on the orientation of the remote. + * + * - "0": Remote orientation does not affect joystick axes. (default) + * - "1": Joystick axes are based on the orientation of the remote. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION" @@ -199,13 +221,16 @@ extern "C" { * A variable controlling the audio category on iOS and macOS. * * The variable can be set to the following values: - * "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: - * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html + * - "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: + * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html * * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_AUDIO_CATEGORY "SDL_AUDIO_CATEGORY" @@ -227,6 +252,8 @@ extern "C" { * if SDL doesn't have any better information. * * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME" @@ -247,6 +274,8 @@ extern "C" { * at all, or might adjust it. * * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES "SDL_AUDIO_DEVICE_SAMPLE_FRAMES" @@ -267,7 +296,13 @@ extern "C" { * Setting this to "" or leaving it unset will have SDL use a reasonable * 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. + * * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME" @@ -287,7 +322,13 @@ extern "C" { * Setting this to "" or leaving it unset will have SDL use a reasonable * 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. + * * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE" @@ -297,21 +338,26 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_AUDIO_DRIVER "SDL_AUDIO_DRIVER" /** - * A variable that causes SDL to not ignore audio "monitors" + * A variable that causes SDL to not ignore audio "monitors". * * 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. * * The variable can be set to the following values: - * "0" - Audio monitor devices will be ignored. (default) - * "1" - Audio monitor devices will show up in the device list. + * + * - "0": Audio monitor devices will be ignored. (default) + * - "1": Audio monitor devices will show up in the device list. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS" @@ -319,21 +365,27 @@ extern "C" { * A variable controlling whether SDL updates joystick state when getting input events. * * The variable can be set to the following values: - * "0" - You'll call SDL_UpdateJoysticks() manually. - * "1" - SDL will automatically call SDL_UpdateJoysticks(). (default) + * + * - "0": You'll call SDL_UpdateJoysticks() manually. + * - "1": SDL will automatically call SDL_UpdateJoysticks(). (default) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #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: - * "0" - You'll call SDL_UpdateSensors() manually. - * "1" - SDL will automatically call SDL_UpdateSensors(). (default) + * + * - "0": You'll call SDL_UpdateSensors() manually. + * - "1": SDL will automatically call SDL_UpdateSensors(). (default) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_AUTO_UPDATE_SENSORS "SDL_AUTO_UPDATE_SENSORS" @@ -345,14 +397,17 @@ extern "C" { * 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 + * + * - "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 + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT" @@ -368,7 +423,7 @@ extern "C" { * the best camera backend on your behalf. This hint needs to be set * before SDL_Init() is called to be useful. * - * This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_CAMERA_DRIVER "SDL_CAMERA_DRIVER" @@ -382,35 +437,39 @@ extern "C" { * features. * * The variable can be set to a comma separated list containing the following items: - * "all" - * "altivec" - * "sse" - * "sse2" - * "sse3" - * "sse41" - * "sse42" - * "avx" - * "avx2" - * "avx512f" - * "arm-simd" - * "neon" - * "lsx" - * "lasx" + * + * - "all" + * - "altivec" + * - "sse" + * - "sse2" + * - "sse3" + * - "sse41" + * - "sse42" + * - "avx" + * - "avx2" + * - "avx512f" + * - "arm-simd" + * - "neon" + * - "lsx" + * - "lasx" * * The items can be prefixed by '+'/'-' to add/remove features. * - * This hint is available since SDL 3.0.0. + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_CPU_FEATURE_MASK "SDL_CPU_FEATURE_MASK" /** - * A variable controlling whether DirectInput should be used for controllers + * A variable controlling whether DirectInput should be used for controllers. * * The variable can be set to the following values: - * "0" - Disable DirectInput detection. - * "1" - Enable DirectInput detection. (default) + * + * - "0": Disable DirectInput detection. + * - "1": Enable DirectInput detection. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_DIRECTINPUT "SDL_JOYSTICK_DIRECTINPUT" @@ -424,24 +483,29 @@ extern "C" { * 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: - * NULL - Select automatically (default, all platforms) - * "portal" - Use XDG Portals through DBus (Unix only) - * "zenity" - Use the Zenity program (Unix only) + * + * - NULL: Select automatically (default, all platforms) + * - "portal": Use XDG Portals through DBus (Unix only) + * - "zenity": Use the Zenity program (Unix only) * * More options may be added in the future. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_FILE_DIALOG_DRIVER "SDL_FILE_DIALOG_DRIVER" /** - * Override for SDL_GetDisplayUsableBounds() + * 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. * * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS" @@ -453,10 +517,13 @@ extern "C" { * 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). - * "1" - Enable emscripten_sleep calls. (default) + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_EMSCRIPTEN_ASYNCIFY "SDL_EMSCRIPTEN_ASYNCIFY" @@ -468,6 +535,8 @@ extern "C" { * The default value is "#canvas" * * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_EMSCRIPTEN_CANVAS_SELECTOR "SDL_EMSCRIPTEN_CANVAS_SELECTOR" @@ -476,26 +545,32 @@ extern "C" { * * This hint only applies to the emscripten platform. * - * The variable can be one of - * "#window" - The javascript window object (default) - * "#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. + * The variable can be one of: + * + * - "#window": the javascript window object (default) + * - "#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. * * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.0.0. */ #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) - * "0" - Do not show the on-screen keyboard. - * "1" - Show the on-screen keyboard, if available. + * + * - "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. * * This hint must be set before SDL_StartTextInput() is called + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD" @@ -503,13 +578,16 @@ extern "C" { * 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: - * "0" - Don't log any events. (default) - * "1" - Log most events (other than the really spammy ones). - * "2" - Include mouse and finger motion events. + * + * - "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 hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_EVENT_LOGGING "SDL_EVENT_LOGGING" @@ -517,12 +595,15 @@ extern "C" { * 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. + * + * - "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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_FORCE_RAISEWINDOW "SDL_FORCE_RAISEWINDOW" @@ -532,11 +613,14 @@ extern "C" { * 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.) + * + * - "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.) * * This hint should be set before calling SDL_GetWindowSurface() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" @@ -548,6 +632,8 @@ extern "C" { * You can update mappings after SDL is initialized with SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" @@ -559,11 +645,13 @@ extern "C" { * You can update mappings after SDL is initialized with SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE" /** - * A variable that overrides the automatic controller type detection + * A variable that overrides the automatic controller type detection. * * The variable should be comma separated entries, in the form: VID/PID=type * @@ -572,14 +660,17 @@ extern "C" { * This hint affects what low level protocol is used with the HIDAPI driver. * * The variable can be set to the following values: - * "Xbox360" - * "XboxOne" - * "PS3" - * "PS4" - * "PS5" - * "SwitchPro" + * + * - "Xbox360" + * - "XboxOne" + * - "PS3" + * - "PS4" + * - "PS5" + * - "SwitchPro" * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_GAMECONTROLLERTYPE "SDL_GAMECONTROLLERTYPE" @@ -593,6 +684,8 @@ extern "C" { * 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_GAMECONTROLLER_IGNORE_DEVICES "SDL_GAMECONTROLLER_IGNORE_DEVICES" @@ -606,6 +699,8 @@ extern "C" { * 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_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT "SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT" @@ -613,8 +708,9 @@ extern "C" { * 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 + * + * - "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. * @@ -623,6 +719,8 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_GAMECONTROLLER_SENSOR_FUSION "SDL_GAMECONTROLLER_SENSOR_FUSION" @@ -632,6 +730,8 @@ extern "C" { * This hint is available only if SDL_GDK_TEXTINPUT defined. * * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT "SDL_GDK_TEXTINPUT_DEFAULT_TEXT" @@ -641,6 +741,8 @@ extern "C" { * This hint is available only if SDL_GDK_TEXTINPUT defined. * * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_GDK_TEXTINPUT_DESCRIPTION "SDL_GDK_TEXTINPUT_DESCRIPTION" @@ -652,6 +754,8 @@ extern "C" { * This hint is available only if SDL_GDK_TEXTINPUT defined. * * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH "SDL_GDK_TEXTINPUT_MAX_LENGTH" @@ -663,6 +767,8 @@ extern "C" { * This hint is available only if SDL_GDK_TEXTINPUT defined. * * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_GDK_TEXTINPUT_SCOPE "SDL_GDK_TEXTINPUT_SCOPE" @@ -672,6 +778,8 @@ extern "C" { * This hint is available only if SDL_GDK_TEXTINPUT defined. * * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_GDK_TEXTINPUT_TITLE "SDL_GDK_TEXTINPUT_TITLE" @@ -679,25 +787,30 @@ extern "C" { * 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) + * + * - "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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS "SDL_HIDAPI_ENUMERATE_ONLY_CONTROLLERS" /** - * A variable containing a list of devices to ignore in SDL_hid_enumerate() + * 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. * - * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * `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" * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_HIDAPI_IGNORE_DEVICES "SDL_HIDAPI_IGNORE_DEVICES" @@ -705,13 +818,16 @@ extern "C" { * 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 + * + * - "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, + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_IME_INTERNAL_EDITING "SDL_IME_INTERNAL_EDITING" @@ -719,22 +835,28 @@ extern "C" { * 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: - * "0" - Native UI components are not display. (default) - * "1" - Native UI components are displayed. + * + * - "0": Native UI components are not display. (default) + * - "1": Native UI components are displayed. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_IME_SHOW_UI "SDL_IME_SHOW_UI" /** * 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) + * 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) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_IOS_HIDE_HOME_INDICATOR "SDL_IOS_HIDE_HOME_INDICATOR" @@ -742,10 +864,13 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" @@ -754,24 +879,30 @@ extern "C" { * * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES "SDL_JOYSTICK_ARCADESTICK_DEVICES" /** - * 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. + * 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. * * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED" @@ -780,11 +911,13 @@ extern "C" { * * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_BLACKLIST_DEVICES "SDL_JOYSTICK_BLACKLIST_DEVICES" @@ -793,19 +926,23 @@ extern "C" { * * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #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. - * - * This variable is currently only used by the Linux joystick driver. - */ + * A variable containing a comma separated list of devices to open as joysticks. + * + * This variable is currently only used by the Linux joystick driver. + * + * \since This hint is available since SDL 3.0.0. + */ #define SDL_HINT_JOYSTICK_DEVICE "SDL_JOYSTICK_DEVICE" /** @@ -813,11 +950,13 @@ extern "C" { * * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES "SDL_JOYSTICK_FLIGHTSTICK_DEVICES" @@ -826,11 +965,13 @@ extern "C" { * * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED "SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED" @@ -839,11 +980,13 @@ extern "C" { * * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES "SDL_JOYSTICK_GAMECUBE_DEVICES" @@ -852,11 +995,13 @@ extern "C" { * * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED "SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED" @@ -864,12 +1009,15 @@ extern "C" { * A variable controlling whether the HIDAPI joystick drivers should be used. * * The variable can be set to the following values: - * "0" - HIDAPI drivers are not used. - * "1" - HIDAPI drivers are used. (default) + * + * - "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 hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI "SDL_JOYSTICK_HIDAPI" @@ -877,10 +1025,13 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS "SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS" @@ -888,17 +1039,20 @@ extern "C" { * A variable controlling whether the HIDAPI driver for Nintendo GameCube controllers should be used. * * The variable can be set to the following values: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #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 @@ -906,10 +1060,13 @@ extern "C" { * - StopHard is implemented by setting both low_frequency_rumble and high_frequency_rumble to 0 * * The variable can be set to the following values: - * "0" - Normal rumble behavior is behavior is used. (default) - * "1" - Proper GameCube controller rumble behavior is used. + * + * - "0": Normal rumble behavior is behavior is used. (default) + * - "1": Proper GameCube controller rumble behavior is used. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE "SDL_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE" @@ -917,25 +1074,31 @@ extern "C" { * A variable controlling whether the HIDAPI driver for Nintendo Switch Joy-Cons should be used. * * The variable can be set to the following values: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #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 + * + * - "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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED "SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED" @@ -943,12 +1106,15 @@ extern "C" { * 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: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_LUNA "SDL_JOYSTICK_HIDAPI_LUNA" @@ -956,12 +1122,15 @@ extern "C" { * A variable controlling whether the HIDAPI driver for Nintendo Online classic controllers should be used. * * The variable can be set to the following values: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC "SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC" @@ -969,8 +1138,9 @@ extern "C" { * 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. + * + * - "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. * @@ -978,6 +1148,8 @@ extern "C" { * See https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3 "SDL_JOYSTICK_HIDAPI_PS3" @@ -985,12 +1157,15 @@ extern "C" { * 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: - * "0" - Sony driver (sixaxis.sys) is not used. - * "1" - Sony driver (sixaxis.sys) is used. + * + * - "0": Sony driver (sixaxis.sys) is not used. + * - "1": Sony driver (sixaxis.sys) is used. * * The default value is 0. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER "SDL_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER" @@ -998,12 +1173,15 @@ extern "C" { * A variable controlling whether the HIDAPI driver for PS4 controllers should be used. * * The variable can be set to the following values: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4 "SDL_JOYSTICK_HIDAPI_PS4" @@ -1011,8 +1189,9 @@ extern "C" { * 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. + * + * - "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. * @@ -1021,6 +1200,8 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE "SDL_JOYSTICK_HIDAPI_PS4_RUMBLE" @@ -1028,12 +1209,15 @@ extern "C" { * A variable controlling whether the HIDAPI driver for PS5 controllers should be used. * * The variable can be set to the following values: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5 "SDL_JOYSTICK_HIDAPI_PS5" @@ -1041,8 +1225,11 @@ extern "C" { * 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: - * "0" - player LEDs are not enabled. - * "1" - player LEDs are enabled. (default) + * + * - "0": player LEDs are not enabled. + * - "1": player LEDs are enabled. (default) + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED "SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED" @@ -1050,8 +1237,9 @@ extern "C" { * 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. + * + * - "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. * @@ -1060,6 +1248,8 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_PS5_RUMBLE "SDL_JOYSTICK_HIDAPI_PS5_RUMBLE" @@ -1067,12 +1257,15 @@ extern "C" { * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD controllers should be used. * * The variable can be set to the following values: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SHIELD "SDL_JOYSTICK_HIDAPI_SHIELD" @@ -1080,10 +1273,13 @@ extern "C" { * A variable controlling whether the HIDAPI driver for Google Stadia controllers should be used. * * The variable can be set to the following values: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STADIA "SDL_JOYSTICK_HIDAPI_STADIA" @@ -1091,10 +1287,13 @@ extern "C" { * 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. + * + * - "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. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAM "SDL_JOYSTICK_HIDAPI_STEAM" @@ -1102,12 +1301,15 @@ extern "C" { * 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: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_STEAMDECK "SDL_JOYSTICK_HIDAPI_STEAMDECK" @@ -1115,25 +1317,31 @@ extern "C" { * A variable controlling whether the HIDAPI driver for Nintendo Switch controllers should be used. * * The variable can be set to the following values: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #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. + * + * - "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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED "SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED" @@ -1141,10 +1349,13 @@ extern "C" { * 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: - * "0" - Player LEDs are not enabled. - * "1" - Player LEDs are enabled. (default) + * + * - "0": Player LEDs are not enabled. + * - "1": Player LEDs are enabled. (default) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED "SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED" @@ -1152,10 +1363,13 @@ extern "C" { * 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) - * "1" - Left and right Joy-Con controllers will be in vertical mode. + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS "SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS" @@ -1163,12 +1377,15 @@ extern "C" { * 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. + * + * - "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 hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII "SDL_JOYSTICK_HIDAPI_WII" @@ -1176,10 +1393,13 @@ extern "C" { * 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: - * "0" - Player LEDs are not enabled. - * "1" - Player LEDs are enabled. (default) + * + * - "0": Player LEDs are not enabled. + * - "1": Player LEDs are enabled. (default) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED "SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED" @@ -1187,12 +1407,15 @@ extern "C" { * 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. + * + * - "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 * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX "SDL_JOYSTICK_HIDAPI_XBOX" @@ -1200,12 +1423,15 @@ extern "C" { * A variable controlling whether the HIDAPI driver for XBox 360 controllers should be used. * * The variable can be set to the following values: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 "SDL_JOYSTICK_HIDAPI_XBOX_360" @@ -1213,10 +1439,13 @@ extern "C" { * 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: - * "0" - Player LEDs are not enabled. - * "1" - Player LEDs are enabled. (default) + * + * - "0": Player LEDs are not enabled. + * - "1": Player LEDs are enabled. (default) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED "SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED" @@ -1224,12 +1453,15 @@ extern "C" { * A variable controlling whether the HIDAPI driver for XBox 360 wireless controllers should be used. * * The variable can be set to the following values: - * "0" - HIDAPI driver is not used. - * "1" - HIDAPI driver is used. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS "SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS" @@ -1237,12 +1469,15 @@ extern "C" { * 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. + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. * * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. * * This hint should be set before enumerating controllers. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE "SDL_JOYSTICK_HIDAPI_XBOX_ONE" @@ -1250,12 +1485,15 @@ extern "C" { * 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. + * + * - "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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED "SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED" @@ -1263,21 +1501,27 @@ extern "C" { * A variable controlling whether IOKit should be used for controller handling. * * The variable can be set to the following values: - * "0" - IOKit is not used. - * "1" - IOKit is used. (default) + * + * - "0": IOKit is not used. + * - "1": IOKit is used. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #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: - * "0" - Use /dev/input/event* (default) - * "1" - Use /dev/input/js* + * + * - "0": Use /dev/input/event* (default) + * - "1": Use /dev/input/js* * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_LINUX_CLASSIC "SDL_JOYSTICK_LINUX_CLASSIC" @@ -1285,10 +1529,13 @@ extern "C" { * 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: - * "0" - Return unfiltered joystick axis values. (default) - * "1" - Return axis values with deadzones taken into account. + * + * - "0": Return unfiltered joystick axis values. (default) + * - "1": Return axis values with deadzones taken into account. * * This hint should be set before a controller is opened. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_LINUX_DEADZONES "SDL_JOYSTICK_LINUX_DEADZONES" @@ -1296,10 +1543,13 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS "SDL_JOYSTICK_LINUX_DIGITAL_HATS" @@ -1307,10 +1557,13 @@ extern "C" { * 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) + * + * - "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) * * This hint should be set before a controller is opened. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES "SDL_JOYSTICK_LINUX_HAT_DEADZONES" @@ -1318,10 +1571,13 @@ extern "C" { * A variable controlling whether GCController should be used for controller handling. * * The variable can be set to the following values: - * "0" - GCController is not used. - * "1" - GCController is used. (default) + * + * - "0": GCController is not used. + * - "1": GCController is used. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_MFI "SDL_JOYSTICK_MFI" @@ -1329,10 +1585,13 @@ extern "C" { * 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: - * "0" - RAWINPUT drivers are not used. - * "1" - RAWINPUT drivers are used. (default) + * + * - "0": RAWINPUT drivers are not used. + * - "1": RAWINPUT drivers are used. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT "SDL_JOYSTICK_RAWINPUT" @@ -1340,10 +1599,13 @@ extern "C" { * 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) + * + * - "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) * * This hint should be set before a gamepad is opened. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT "SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT" @@ -1351,10 +1613,13 @@ extern "C" { * A variable controlling whether the ROG Chakram mice should show up as joysticks. * * The variable can be set to the following values: - * "0" - ROG Chakram mice do not show up as joysticks. (default) - * "1" - ROG Chakram mice show up as joysticks. + * + * - "0": ROG Chakram mice do not show up as joysticks. (default) + * - "1": ROG Chakram mice show up as joysticks. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_ROG_CHAKRAM "SDL_JOYSTICK_ROG_CHAKRAM" @@ -1362,10 +1627,13 @@ extern "C" { * 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: - * "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_THREAD "SDL_JOYSTICK_THREAD" @@ -1374,12 +1642,14 @@ extern "C" { * * 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. * * 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" /** @@ -1387,11 +1657,13 @@ extern "C" { * * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED "SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED" @@ -1399,10 +1671,13 @@ extern "C" { * A variable controlling whether Windows.Gaming.Input should be used for controller handling. * * The variable can be set to the following values: - * "0" - WGI is not used. - * "1" - WGI is used. (default) + * + * - "0": WGI is not used. + * - "1": WGI is used. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_WGI "SDL_JOYSTICK_WGI" @@ -1411,11 +1686,13 @@ extern "C" { * * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES "SDL_JOYSTICK_WHEEL_DEVICES" @@ -1424,11 +1701,13 @@ extern "C" { * * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED "SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED" @@ -1437,11 +1716,13 @@ extern "C" { * * 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. * * This hint should be set before a controller is opened. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES "SDL_JOYSTICK_ZERO_CENTERED_DEVICES" @@ -1451,6 +1732,8 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_KMSDRM_DEVICE_INDEX "SDL_KMSDRM_DEVICE_INDEX" @@ -1469,10 +1752,13 @@ extern "C" { * using its own code to render to DRM overlays that SDL doesn't support. * * The variable can be set to the following values: - * "0" - SDL will allow usage of the KMSDRM backend without DRM master. - * "1" - SDL Will require DRM master to use the KMSDRM backend. (default) + * + * - "0": SDL will allow usage of the KMSDRM backend without DRM master. + * - "1": SDL Will require DRM master to use the KMSDRM backend. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER "SDL_KMSDRM_REQUIRE_DRM_MASTER" @@ -1488,9 +1774,12 @@ extern "C" { * 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: - * "app=info,assert=warn,test=verbose,*=error" + * + * `app=info,assert=warn,test=verbose,*=error` * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_LOGGING "SDL_LOGGING" @@ -1498,10 +1787,13 @@ extern "C" { * 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) - * "1" - The application may remain in the background when launched. + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MAC_BACKGROUND_APP "SDL_MAC_BACKGROUND_APP" @@ -1509,10 +1801,13 @@ extern "C" { * 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) - * "1" - Ctrl+Click generated a right mouse button click event. + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" @@ -1520,12 +1815,15 @@ extern "C" { * 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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH "SDL_MAC_OPENGL_ASYNC_DISPATCH" @@ -1542,6 +1840,8 @@ extern "C" { * the default. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MAIN_CALLBACK_RATE "SDL_MAIN_CALLBACK_RATE" @@ -1549,12 +1849,15 @@ extern "C" { * 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. + * + * - "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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MOUSE_AUTO_CAPTURE "SDL_MOUSE_AUTO_CAPTURE" @@ -1562,6 +1865,8 @@ extern "C" { * A variable setting the double click radius, in pixels. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS "SDL_MOUSE_DOUBLE_CLICK_RADIUS" @@ -1569,6 +1874,8 @@ extern "C" { * A variable setting the double click time, in milliseconds. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MOUSE_DOUBLE_CLICK_TIME "SDL_MOUSE_DOUBLE_CLICK_TIME" @@ -1576,10 +1883,13 @@ extern "C" { * Allow mouse click events when clicking to focus an SDL window. * * The variable can be set to the following values: - * "0" - Ignore mouse clicks that activate a window. (default) - * "1" - Generate events for mouse clicks that activate a window. + * + * - "0": Ignore mouse clicks that activate a window. (default) + * - "1": Generate events for mouse clicks that activate a window. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH "SDL_MOUSE_FOCUS_CLICKTHROUGH" @@ -1587,6 +1897,8 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MOUSE_NORMAL_SPEED_SCALE "SDL_MOUSE_NORMAL_SPEED_SCALE" @@ -1596,10 +1908,13 @@ extern "C" { * 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) + * + * - "0": Relative mouse mode constrains the mouse to the window. + * - "1": Relative mouse mode constrains the mouse to the center of the window. (default) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MOUSE_RELATIVE_MODE_CENTER "SDL_MOUSE_RELATIVE_MODE_CENTER" @@ -1607,10 +1922,13 @@ extern "C" { * A variable controlling whether relative mouse mode is implemented using mouse warping. * * The variable can be set to the following values: - * "0" - Relative mouse mode uses raw input. (default) - * "1" - Relative mouse mode uses mouse warping. + * + * - "0": Relative mouse mode uses raw input. (default) + * - "1": Relative mouse mode uses mouse warping. * * This hint can be set anytime relative mode is not currently enabled. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" @@ -1618,6 +1936,8 @@ extern "C" { * A variable setting the scale for mouse motion, in floating point, when the mouse is in relative mode. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE "SDL_MOUSE_RELATIVE_SPEED_SCALE" @@ -1625,12 +1945,15 @@ extern "C" { * 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. + * + * - "0": Relative mouse motion will be unscaled. (default) + * - "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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE "SDL_MOUSE_RELATIVE_SYSTEM_SCALE" @@ -1638,23 +1961,29 @@ extern "C" { * 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 + * + * - "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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_MOUSE_TOUCH_EVENTS "SDL_MOUSE_TOUCH_EVENTS" @@ -1662,10 +1991,13 @@ extern "C" { * Tell SDL not to catch the SIGINT or SIGTERM signals on POSIX platforms. * * 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) - * "1" - SDL will not install a signal handler at all. + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_NO_SIGNAL_HANDLERS "SDL_NO_SIGNAL_HANDLERS" @@ -1683,10 +2015,13 @@ extern "C" { * This variable is ignored on most platforms because OpenGL ES is native or not supported. * * The variable can be set to the following values: - * "0" - Use ES profile of OpenGL, if available. (default) - * "1" - Load OpenGL ES library using the default library names. + * + * - "0": Use ES profile of OpenGL, if available. (default) + * - "1": Load OpenGL ES library using the default library names. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_OPENGL_ES_DRIVER "SDL_OPENGL_ES_DRIVER" @@ -1696,9 +2031,15 @@ extern "C" { * 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: - * "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown" + * + * - "LandscapeLeft" + * - "LandscapeRight" + * - "Portrait" + * - "PortraitUpsideDown" * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS" @@ -1706,51 +2047,62 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #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) + * + * - "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). + * - "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. + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #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. * * The variable can be set to the following values: - * "0" - Disable poll sentinels. - * "1" - Enable poll sentinels. (default) + * + * - "0": Disable poll sentinels. + * - "1": Enable poll sentinels. (default) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL" /** - * Override for SDL_GetPreferredLocales() + * 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). * * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_PREFERRED_LOCALES "SDL_PREFERRED_LOCALES" @@ -1758,10 +2110,13 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE "SDL_QUIT_ON_LAST_WINDOW_CLOSE" @@ -1769,10 +2124,13 @@ extern "C" { * A variable controlling whether the Direct3D device is initialized for thread-safe operations. * * The variable can be set to the following values: - * "0" - Thread-safety is not enabled. (default) - * "1" - Thread-safety is enabled. + * + * - "0": Thread-safety is not enabled. (default) + * - "1": Thread-safety is enabled. * * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" @@ -1782,22 +2140,27 @@ extern "C" { * This variable does not have any effect on the Direct3D 9 based renderer. * * The variable can be set to the following values: - * "0" - Disable Debug Layer use. (default) - * "1" - Enable Debug Layer use. + * + * - "0": Disable Debug Layer use. (default) + * - "1": Enable Debug Layer use. * * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.0.0. */ #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: - * "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_RENDER_VULKAN_DEBUG "SDL_RENDER_VULKAN_DEBUG" @@ -1807,19 +2170,22 @@ extern "C" { * 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: - * "direct3d" - * "direct3d11" - * "direct3d12" - * "opengl" - * "opengles2" - * "opengles" - * "metal" - * "vulkan" - * "software" + * + * - "direct3d" + * - "direct3d11" + * - "direct3d12" + * - "opengl" + * - "opengles2" + * - "opengles" + * - "metal" + * - "vulkan" + * - "software" * * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" @@ -1827,12 +2193,15 @@ extern "C" { * A variable controlling how the 2D render API renders lines. * * 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 - * "3" - Use the driver geometry API (correct, draws thicker diagonal lines) + * + * - "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 + * - "3": Use the driver geometry API (correct, draws thicker diagonal lines) * * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_RENDER_LINE_METHOD "SDL_RENDER_LINE_METHOD" @@ -1840,10 +2209,13 @@ extern "C" { * A variable controlling whether the Metal render driver select low power device over default one. * * The variable can be set to the following values: - * "0" - Use the prefered OS device. (default) - * "1" - Select a low power device. + * + * - "0": Use the prefered OS device. (default) + * - "1": Select a low power device. * * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE "SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE" @@ -1851,10 +2223,13 @@ extern "C" { * 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 + * + * - "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 * * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_RENDER_PS2_DYNAMIC_VSYNC "SDL_RENDER_PS2_DYNAMIC_VSYNC" @@ -1864,10 +2239,13 @@ extern "C" { * This hint overrides the application preference when creating a renderer. * * The variable can be set to the following values: - * "0" - Disable vsync. (default) - * "1" - Enable vsync. + * + * - "0": Disable vsync. (default) + * - "1": Enable vsync. * * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" @@ -1875,10 +2253,13 @@ extern "C" { * 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: - * "0" - The return key will be handled as a key event. (default) - * "1" - The return key will hide the keyboard. + * + * - "0": The return key will be handled as a key event. (default) + * - "1": The return key will hide the keyboard. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_RETURN_KEY_HIDES_IME "SDL_RETURN_KEY_HIDES_IME" @@ -1887,11 +2268,13 @@ extern "C" { * * 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. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_ROG_GAMEPAD_MICE "SDL_ROG_GAMEPAD_MICE" @@ -1900,11 +2283,13 @@ extern "C" { * * 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. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED" @@ -1915,6 +2300,8 @@ extern "C" { * The default is 10000. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_RPI_VIDEO_LAYER "SDL_RPI_VIDEO_LAYER" @@ -1928,6 +2315,8 @@ extern "C" { * 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() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME "SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME" @@ -1937,10 +2326,13 @@ extern "C" { * 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: - * "0" - SDL will not call dbus_shutdown() on quit. (default) - * "1" - SDL will call dbus_shutdown() on quit. + * + * - "0": SDL will not call dbus_shutdown() on quit. (default) + * - "1": SDL will call dbus_shutdown() on quit. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_SHUTDOWN_DBUS_ON_QUIT "SDL_SHUTDOWN_DBUS_ON_QUIT" @@ -1950,6 +2342,8 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_STORAGE_TITLE_DRIVER "SDL_STORAGE_TITLE_DRIVER" @@ -1959,6 +2353,8 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_STORAGE_USER_DRIVER "SDL_STORAGE_USER_DRIVER" @@ -1968,15 +2364,19 @@ extern "C" { * 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: + * * - 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. + * - 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 + * + * - "0": default platform specific behaviour + * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling policy * * This hint should be set before calling SDL_SetThreadPriority() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL "SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL" @@ -1991,6 +2391,8 @@ extern "C" { * 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() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_THREAD_PRIORITY_POLICY "SDL_THREAD_PRIORITY_POLICY" @@ -2007,17 +2409,22 @@ extern "C" { * If this variable is set to "0", the system timer resolution is not set. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #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: - * "0" - Touch events will not generate mouse events. - * "1" - Touch events will generate mouse events. (default) + * + * - "0": Touch events will not generate mouse events. + * - "1": Touch events will generate mouse events. (default) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_TOUCH_MOUSE_EVENTS "SDL_TOUCH_MOUSE_EVENTS" @@ -2027,10 +2434,13 @@ extern "C" { * 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: - * "0" - Trackpad will send mouse events. (default) - * "1" - Trackpad will send touch events. + * + * - "0": Trackpad will send mouse events. (default) + * - "1": Trackpad will send touch events. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_TRACKPAD_IS_TOUCH_ONLY "SDL_TRACKPAD_IS_TOUCH_ONLY" @@ -2038,10 +2448,13 @@ extern "C" { * 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: - * "0" - Remotes send enter/escape/arrow key events. - * "1" - Remotes are available as 2 axis, 2 button joysticks. (default) + * + * - "0": Remotes send enter/escape/arrow key events. + * - "1": Remotes are available as 2 axis, 2 button joysticks. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_TV_REMOTE_AS_JOYSTICK "SDL_TV_REMOTE_AS_JOYSTICK" @@ -2049,10 +2462,13 @@ extern "C" { * A variable controlling whether the screensaver is enabled. * * The variable can be set to the following values: - * "0" - Disable screensaver. (default) - * "1" - Enable screensaver. + * + * - "0": Disable screensaver. (default) + * - "1": Enable screensaver. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" @@ -2064,9 +2480,12 @@ extern "C" { * 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: + * * - Raspberry Pi (raspberrypi) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_DOUBLE_BUFFER "SDL_VIDEO_DOUBLE_BUFFER" @@ -2076,6 +2495,8 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_DRIVER "SDL_VIDEO_DRIVER" @@ -2083,10 +2504,13 @@ extern "C" { * If eglGetPlatformDisplay fails, fall back to calling eglGetDisplay. * * The variable can be set to one of the following values: - * "0" - Do not fall back to eglGetDisplay. - * "1" - Fall back to eglGetDisplay if eglGetPlatformDisplay fails. (default) + * + * - "0": Do not fall back to eglGetDisplay. + * - "1": Fall back to eglGetDisplay if eglGetPlatformDisplay fails. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK "SDL_VIDEO_EGL_GETDISPLAY_FALLBACK" @@ -2094,10 +2518,13 @@ extern "C" { * 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) - * "1" - Use EGL + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_FORCE_EGL "SDL_VIDEO_FORCE_EGL" @@ -2105,10 +2532,13 @@ extern "C" { * A variable that specifies the policy for fullscreen Spaces on macOS. * * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" @@ -2116,10 +2546,13 @@ extern "C" { * 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) - * "1" - Fullscreen windows are minimized when they lose focus. + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" @@ -2131,10 +2564,13 @@ extern "C" { * 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: - * "0" - Window operations are non-blocking. (default) - * "1" - Window operations will block until completed. + * + * - "0": Window operations are non-blocking. (default) + * - "1": Window operations will block until completed. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS "SDL_VIDEO_SYNC_WINDOW_OPERATIONS" @@ -2144,10 +2580,13 @@ extern "C" { * libdecor is used over xdg-shell when xdg-decoration protocol is unavailable. * * The variable can be set to the following values: - * "0" - libdecor use is disabled. - * "1" - libdecor use is enabled. (default) + * + * - "0": libdecor use is disabled. + * - "1": libdecor use is enabled. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR" @@ -2157,12 +2596,15 @@ extern "C" { * 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. - * "1" - Some mouse warps will be emulated by forcing relative mouse mode. + * + * - "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. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_WAYLAND_EMULATE_MOUSE_WARP "SDL_VIDEO_WAYLAND_EMULATE_MOUSE_WARP" @@ -2172,10 +2614,13 @@ extern "C" { * 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: - * "0" - Video mode emulation is disabled. - * "1" - Video mode emulation is enabled. (default) + * + * - "0": Video mode emulation is disabled. + * - "1": Video mode emulation is enabled. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION "SDL_VIDEO_WAYLAND_MODE_EMULATION" @@ -2185,11 +2630,14 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_WAYLAND_MODE_SCALING "SDL_VIDEO_WAYLAND_MODE_SCALING" @@ -2199,10 +2647,13 @@ extern "C" { * 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) - * "1" - libdecor is always enabled if available. + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR "SDL_VIDEO_WAYLAND_PREFER_LIBDECOR" @@ -2222,10 +2673,13 @@ extern "C" { * New applications should be designed with proper DPI awareness handling instead of enabling this. * * The variable can be set to the following values: - * "0" - Windows will be scaled normally. - * "1" - Windows will be forced to scale to achieve 1:1 output. + * + * - "0": Windows will be scaled normally. + * - "1": Windows will be forced to scale to achieve 1:1 output. * * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_WAYLAND_SCALE_TO_DISPLAY "SDL_VIDEO_WAYLAND_SCALE_TO_DISPLAY" @@ -2235,11 +2689,14 @@ extern "C" { * 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. + * + * - "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. * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" @@ -2247,10 +2704,13 @@ extern "C" { * A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used. * * The variable can be set to the following values: - * "0" - Disable _NET_WM_BYPASS_COMPOSITOR. - * "1" - Enable _NET_WM_BYPASS_COMPOSITOR. (default) + * + * - "0": Disable _NET_WM_BYPASS_COMPOSITOR. + * - "1": Enable _NET_WM_BYPASS_COMPOSITOR. (default) * * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR "SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR" @@ -2260,10 +2720,13 @@ extern "C" { * 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: - * "0" - Disable _NET_WM_PING. - * "1" - Enable _NET_WM_PING. (default) + * + * - "0": Disable _NET_WM_PING. + * - "1": Enable _NET_WM_PING. (default) * * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_X11_NET_WM_PING "SDL_VIDEO_X11_NET_WM_PING" @@ -2273,13 +2736,17 @@ extern "C" { * The variable can be set to a floating point value in the range 1.0-10.0f * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_X11_SCALING_FACTOR "SDL_VIDEO_X11_SCALING_FACTOR" /** - * A variable forcing the visual ID chosen for new X11 windows + * A variable forcing the visual ID chosen for new X11 windows. * * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VIDEO_X11_WINDOW_VISUALID "SDL_VIDEO_X11_WINDOW_VISUALID" @@ -2287,22 +2754,28 @@ extern "C" { * A variable controlling whether the X11 XRandR extension should be used. * * The variable can be set to the following values: - * "0" - Disable XRandR. - * "1" - Enable XRandR. (default) + * + * - "0": Disable XRandR. + * - "1": Enable XRandR. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #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: - * "0" - Only front touchpad should generate mouse events. (default) - * "1" - Only back touchpad should generate mouse events. - * "2" - Both touchpads should generate mouse events. + * + * - "0": Only front touchpad should generate mouse events. (default) + * - "1": Only back touchpad should generate mouse events. + * - "2": Both touchpads should generate mouse events. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_VITA_TOUCH_MOUSE_DEVICE "SDL_VITA_TOUCH_MOUSE_DEVICE" @@ -2314,12 +2787,15 @@ extern "C" { * 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() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WAVE_FACT_CHUNK "SDL_WAVE_FACT_CHUNK" @@ -2331,12 +2807,15 @@ extern "C" { * 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() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WAVE_RIFF_CHUNK_SIZE "SDL_WAVE_RIFF_CHUNK_SIZE" @@ -2346,12 +2825,15 @@ extern "C" { * 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) + * + * - "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) * * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WAVE_TRUNCATION "SDL_WAVE_TRUNCATION" @@ -2359,10 +2841,13 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED "SDL_WINDOW_ACTIVATE_WHEN_RAISED" @@ -2370,10 +2855,13 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN "SDL_WINDOW_ACTIVATE_WHEN_SHOWN" @@ -2383,21 +2871,27 @@ extern "C" { * 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: - * "0" - don't allow topmost - * "1" - allow topmost (default) + * + * - "0": don't allow topmost + * - "1": allow topmost (default) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #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). - * "1" - The window frame is interactive when the cursor is hidden. (default) + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN "SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN" @@ -2405,10 +2899,13 @@ extern "C" { * 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) + * + * - "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) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINDOWS_CLOSE_ON_ALT_F4 "SDL_WINDOWS_CLOSE_ON_ALT_F4" @@ -2422,10 +2919,13 @@ extern "C" { * 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: - * "0" - Alt+mnemonic does nothing, no beeping. (default) - * "1" - Alt+mnemonic opens menus, invalid mnemonics produce a beep. + * + * - "0": Alt+mnemonic does nothing, no beeping. (default) + * - "1": Alt+mnemonic opens menus, invalid mnemonics produce a beep. * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS "SDL_WINDOWS_ENABLE_MENU_MNEMONICS" @@ -2433,21 +2933,27 @@ extern "C" { * A variable controlling whether the windows message loop is processed by SDL. * * The variable can be set to the following values: - * "0" - The window message loop is not run. - * "1" - The window message loop is processed in SDL_PumpEvents(). (default) + * + * - "0": The window message loop is not run. + * - "1": The window message loop is processed in SDL_PumpEvents(). (default) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP "SDL_WINDOWS_ENABLE_MESSAGELOOP" /** - * A variable controlling whether raw keyboard events are used on Windows + * A variable controlling whether raw keyboard events are used on Windows. * * The variable can be set to the following values: - * "0" - The Windows message loop is used for keyboard events. - * "1" - Low latency raw keyboard events are used. (default) + * + * - "0": The Windows message loop is used for keyboard events. + * - "1": Low latency raw keyboard events are used. (default) * * This hint can be set anytime. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINDOWS_RAW_KEYBOARD "SDL_WINDOWS_RAW_KEYBOARD" @@ -2457,10 +2963,13 @@ extern "C" { * 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) - * "1" - Force the use of Critical Sections in all cases. + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS "SDL_WINDOWS_FORCE_MUTEX_CRITICAL_SECTIONS" @@ -2470,17 +2979,22 @@ extern "C" { * 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) - * "1" - Force the use of Kernel Objects in all cases. + * + * - "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. + * + * \since This hint is available since SDL 3.0.0. */ #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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" @@ -2491,14 +3005,18 @@ extern "C" { * 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 * * 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) + * + * - "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) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINDOWS_USE_D3D9EX "SDL_WINDOWS_USE_D3D9EX" @@ -2519,11 +3037,13 @@ extern "C" { * * 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. */ #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON" /** - * A variable specifying the label text for a WinRT app's privacy policy link + * 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. * @@ -2536,11 +3056,13 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL" /** - * A variable specifying the URL to a WinRT app's privacy policy + * 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. * @@ -2551,6 +3073,8 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_WINRT_PRIVACY_POLICY_URL "SDL_WINRT_PRIVACY_POLICY_URL" @@ -2562,10 +3086,13 @@ extern "C" { * 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: - * "0" - Do not mark the window as override-redirect. (default) - * "1" - Mark the window as override-redirect. + * + * - "0": Do not mark the window as override-redirect. (default) + * - "1": Mark the window as override-redirect. * * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT "SDL_X11_FORCE_OVERRIDE_REDIRECT" @@ -2575,6 +3102,8 @@ extern "C" { * 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. + * + * \since This hint is available since SDL 3.0.0. */ #define SDL_HINT_X11_WINDOW_TYPE "SDL_X11_WINDOW_TYPE" @@ -2582,17 +3111,22 @@ extern "C" { * A variable controlling whether XInput should be used for controller handling. * * The variable can be set to the following values: - * "0" - XInput is not enabled. - * "1" - XInput is enabled. (default) + * + * - "0": XInput is not enabled. + * - "1": XInput is enabled. (default) * * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.0.0. */ #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. */ -typedef enum +typedef enum SDL_HintPriority { SDL_HINT_DEFAULT, SDL_HINT_NORMAL, diff --git a/include/SDL3/SDL_init.h b/include/SDL3/SDL_init.h index d1b925270..4a03b4012 100644 --- a/include/SDL3/SDL_init.h +++ b/include/SDL3/SDL_init.h @@ -51,7 +51,7 @@ extern "C" { * \sa SDL_QuitSubSystem * \sa SDL_WasInit */ -typedef enum +typedef enum SDL_InitFlags { SDL_INIT_TIMER = 0x00000001, SDL_INIT_AUDIO = 0x00000010, /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */ diff --git a/include/SDL3/SDL_iostream.h b/include/SDL3/SDL_iostream.h index 52e218e69..fb5e6e027 100644 --- a/include/SDL3/SDL_iostream.h +++ b/include/SDL3/SDL_iostream.h @@ -53,6 +53,17 @@ typedef enum SDL_IOStatus SDL_IO_STATUS_WRITEONLY /**< Tried to read a write-only buffer */ } 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(). + * + * \since This struct is available since SDL 3.0.0. + */ typedef struct SDL_IOStreamInterface { /** @@ -107,7 +118,14 @@ typedef struct SDL_IOStreamInterface /** - * This is the read/write operation structure -- opaque, as of SDL3! + * 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. + * + * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_IOStream SDL_IOStream; @@ -305,6 +323,9 @@ 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. + * * \param iface The function pointers that implement this SDL_IOStream. * \param userdata The app-controlled pointer that is passed to iface's * functions when called. diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h index 3840c9afc..97a9835ce 100644 --- a/include/SDL3/SDL_joystick.h +++ b/include/SDL3/SDL_joystick.h @@ -118,7 +118,7 @@ typedef enum /* Function prototypes */ /** - * Locking for atomic access to the joystick API + * Locking for atomic access to the joystick API. * * The SDL joystick functions are thread-safe, however you can lock the * joysticks while processing to guarantee that the joystick list won't change @@ -129,7 +129,7 @@ typedef enum extern DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock); /** - * Unlocking for atomic access to the joystick API + * Unlocking for atomic access to the joystick API. * * \since This function is available since SDL 3.0.0. */ @@ -388,7 +388,7 @@ typedef struct SDL_VirtualJoystickDesc } SDL_VirtualJoystickDesc; /** - * The current version of the SDL_VirtualJoystickDesc structure + * The current version of the SDL_VirtualJoystickDesc structure. */ #define SDL_VIRTUAL_JOYSTICK_DESC_VERSION 1 @@ -714,7 +714,7 @@ extern DECLSPEC int SDLCALL SDL_GetJoystickGUIDString(SDL_JoystickGUID guid, cha extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_GetJoystickGUIDFromString(const char *pchGUID); /** - * Get the device information encoded in a SDL_JoystickGUID structure + * Get the device information encoded in a SDL_JoystickGUID structure. * * \param guid the SDL_JoystickGUID you wish to get info about * \param vendor A pointer filled in with the device VID, or 0 if not @@ -1007,7 +1007,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int extern DECLSPEC int SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble, Uint32 duration_ms); /** - * Start a rumble effect in the joystick's triggers + * Start a rumble effect in the joystick's triggers. * * Each call to this function cancels any previous trigger rumble effect, and * calling it with 0 intensity stops any rumbling. @@ -1056,7 +1056,7 @@ extern DECLSPEC int SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, U extern DECLSPEC int SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); /** - * Send a joystick specific effect packet + * Send a joystick specific effect packet. * * \param joystick The joystick to affect * \param data The data to send to the joystick diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h index fe06957c6..9ece2a1d7 100644 --- a/include/SDL3/SDL_keyboard.h +++ b/include/SDL3/SDL_keyboard.h @@ -44,7 +44,7 @@ typedef Uint32 SDL_KeyboardID; /** * The SDL keysym structure, used in key events. * - * \note 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 { @@ -143,7 +143,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetKeyboardFocus(void); extern DECLSPEC const Uint8 *SDLCALL SDL_GetKeyboardState(int *numkeys); /** - * Clear the state of the keyboard + * Clear the state of the keyboard. * * This function will generate key up events for all pressed keys. * diff --git a/include/SDL3/SDL_keycode.h b/include/SDL3/SDL_keycode.h index e94ace90b..8aa40854a 100644 --- a/include/SDL3/SDL_keycode.h +++ b/include/SDL3/SDL_keycode.h @@ -47,7 +47,15 @@ typedef Sint32 SDL_Keycode; #define SDLK_SCANCODE_MASK (1<<30) #define SDL_SCANCODE_TO_KEYCODE(X) (X | SDLK_SCANCODE_MASK) -typedef enum +/** + * Possible SDL virtual key values. + * + * Values from this enum are used to represent keyboard keys using the current + * layout of the keyboard. + * + * \since This enum is available since SDL 3.0.0. + */ +typedef enum SDL_KeyCode { SDLK_UNKNOWN = 0, @@ -328,27 +336,29 @@ typedef enum /** * Enumeration of valid key mods (possibly OR'd together). + * + * \since This enum is available since SDL 3.0.0. */ -typedef enum +typedef enum SDL_Keymod { - SDL_KMOD_NONE = 0x0000, - SDL_KMOD_LSHIFT = 0x0001, - SDL_KMOD_RSHIFT = 0x0002, - SDL_KMOD_LCTRL = 0x0040, - SDL_KMOD_RCTRL = 0x0080, - SDL_KMOD_LALT = 0x0100, - SDL_KMOD_RALT = 0x0200, - SDL_KMOD_LGUI = 0x0400, - SDL_KMOD_RGUI = 0x0800, - SDL_KMOD_NUM = 0x1000, - SDL_KMOD_CAPS = 0x2000, - SDL_KMOD_MODE = 0x4000, - SDL_KMOD_SCROLL = 0x8000, + SDL_KMOD_NONE = 0x0000, /**< no modifier is applicable. */ + SDL_KMOD_LSHIFT = 0x0001, /**< the left Shift key is down. */ + SDL_KMOD_RSHIFT = 0x0002, /**< the right Shift key is down. */ + SDL_KMOD_LCTRL = 0x0040, /**< the left Ctrl (Control) key is down. */ + SDL_KMOD_RCTRL = 0x0080, /**< the right Ctrl (Control) key is down. */ + SDL_KMOD_LALT = 0x0100, /**< the left Alt key is down. */ + SDL_KMOD_RALT = 0x0200, /**< the right Alt key is down. */ + SDL_KMOD_LGUI = 0x0400, /**< the left GUI key (often the Windows key) is down. */ + SDL_KMOD_RGUI = 0x0800, /**< the right GUI key (often the Windows key) is down. */ + SDL_KMOD_NUM = 0x1000, /**< the Num Lock key (may be located on an extended keypad) is down. */ + SDL_KMOD_CAPS = 0x2000, /**< the Caps Lock key is down. */ + SDL_KMOD_MODE = 0x4000, /**< the !AltGr key is down. */ + SDL_KMOD_SCROLL = 0x8000, /**< the Scoll Lock key is down. */ - SDL_KMOD_CTRL = SDL_KMOD_LCTRL | SDL_KMOD_RCTRL, - SDL_KMOD_SHIFT = SDL_KMOD_LSHIFT | SDL_KMOD_RSHIFT, - SDL_KMOD_ALT = SDL_KMOD_LALT | SDL_KMOD_RALT, - SDL_KMOD_GUI = SDL_KMOD_LGUI | SDL_KMOD_RGUI, + SDL_KMOD_CTRL = SDL_KMOD_LCTRL | SDL_KMOD_RCTRL, /**< Any Ctrl key is down. */ + SDL_KMOD_SHIFT = SDL_KMOD_LSHIFT | SDL_KMOD_RSHIFT, /**< Any Shift key is down. */ + SDL_KMOD_ALT = SDL_KMOD_LALT | SDL_KMOD_RALT, /**< Any Alt key is down. */ + SDL_KMOD_GUI = SDL_KMOD_LGUI | SDL_KMOD_RGUI, /**< Any GUI key is down. */ SDL_KMOD_RESERVED = SDL_KMOD_SCROLL /* This is for source-level compatibility with SDL 2.0.0. */ } SDL_Keymod; diff --git a/include/SDL3/SDL_locale.h b/include/SDL3/SDL_locale.h index adea62819..4b6faf86d 100644 --- a/include/SDL3/SDL_locale.h +++ b/include/SDL3/SDL_locale.h @@ -39,7 +39,18 @@ extern "C" { /* *INDENT-ON* */ #endif - +/** + * 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"). + * + * \since This function is available since SDL 3.0.0. + * + * \sa SDL_GetPreferredLocales + */ typedef struct SDL_Locale { const char *language; /**< A language name, like "en" for English. */ diff --git a/include/SDL3/SDL_log.h b/include/SDL3/SDL_log.h index 99d2f2c36..2d8ecded7 100644 --- a/include/SDL3/SDL_log.h +++ b/include/SDL3/SDL_log.h @@ -47,7 +47,7 @@ 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. */ @@ -61,7 +61,7 @@ extern "C" { * at the VERBOSE level and all other categories are enabled at the * ERROR level. */ -typedef enum +typedef enum SDL_LogCategory { SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_CATEGORY_ERROR, @@ -99,7 +99,7 @@ typedef enum /** * The predefined log priorities */ -typedef enum +typedef enum SDL_LogPriority { SDL_LOG_PRIORITY_VERBOSE = 1, SDL_LOG_PRIORITY_DEBUG, diff --git a/include/SDL3/SDL_messagebox.h b/include/SDL3/SDL_messagebox.h index 3d6855275..59e3203e7 100644 --- a/include/SDL3/SDL_messagebox.h +++ b/include/SDL3/SDL_messagebox.h @@ -35,7 +35,7 @@ extern "C" { /** * SDL_MessageBox flags. If supported will display warning icon, etc. */ -typedef enum +typedef enum SDL_MessageBoxFlags { SDL_MESSAGEBOX_ERROR = 0x00000010, /**< error dialog */ SDL_MESSAGEBOX_WARNING = 0x00000020, /**< warning dialog */ @@ -47,7 +47,7 @@ typedef enum /** * Flags for SDL_MessageBoxButtonData. */ -typedef enum +typedef enum SDL_MessageBoxButtonFlags { SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT = 0x00000001, /**< Marks the default button when return is hit */ SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT = 0x00000002 /**< Marks the default button when escape is hit */ @@ -56,7 +56,7 @@ typedef enum /** * Individual button data. */ -typedef struct +typedef struct SDL_MessageBoxButtonData { Uint32 flags; /**< ::SDL_MessageBoxButtonFlags */ int buttonID; /**< User defined button id (value returned via SDL_ShowMessageBox) */ @@ -66,12 +66,12 @@ typedef struct /** * RGB value used in a message box color scheme */ -typedef struct +typedef struct SDL_MessageBoxColor { Uint8 r, g, b; } SDL_MessageBoxColor; -typedef enum +typedef enum SDL_MessageBoxColorType { SDL_MESSAGEBOX_COLOR_BACKGROUND, SDL_MESSAGEBOX_COLOR_TEXT, @@ -84,7 +84,7 @@ typedef enum /** * A set of colors to use for message box dialogs */ -typedef struct +typedef struct SDL_MessageBoxColorScheme { SDL_MessageBoxColor colors[SDL_MESSAGEBOX_COLOR_MAX]; } SDL_MessageBoxColorScheme; @@ -92,7 +92,7 @@ typedef struct /** * MessageBox structure containing title, text, window, etc. */ -typedef struct +typedef struct SDL_MessageBoxData { Uint32 flags; /**< ::SDL_MessageBoxFlags */ SDL_Window *window; /**< Parent window, can be NULL */ diff --git a/include/SDL3/SDL_mouse.h b/include/SDL3/SDL_mouse.h index a374277c1..89f54dbc6 100644 --- a/include/SDL3/SDL_mouse.h +++ b/include/SDL3/SDL_mouse.h @@ -45,7 +45,7 @@ typedef struct SDL_Cursor SDL_Cursor; /**< Implementation dependent */ /** * Cursor types for SDL_CreateSystemCursor(). */ -typedef enum +typedef enum SDL_SystemCursor { SDL_SYSTEM_CURSOR_ARROW, /**< Arrow */ SDL_SYSTEM_CURSOR_IBEAM, /**< I-beam */ @@ -73,7 +73,7 @@ typedef enum /** * Scroll direction types for the Scroll event */ -typedef enum +typedef enum SDL_MouseWheelDirection { SDL_MOUSEWHEEL_NORMAL, /**< The scroll direction is normal */ SDL_MOUSEWHEEL_FLIPPED /**< The scroll direction is flipped / natural */ diff --git a/include/SDL3/SDL_pen.h b/include/SDL3/SDL_pen.h index ccb61370d..a20e1f67f 100644 --- a/include/SDL3/SDL_pen.h +++ b/include/SDL3/SDL_pen.h @@ -28,18 +28,18 @@ * and drawing tablets or suitably equipped mobile / tablet devices. * * To get started with pens: - * - Listen to ::SDL_PenMotionEvent and ::SDL_PenButtonEvent - * - To avoid treating pen events as mouse events, ignore ::SDL_MouseMotionEvent and ::SDL_MouseButtonEvent - * whenever "which" == ::SDL_PEN_MOUSEID. + * - Listen to SDL_PenMotionEvent and SDL_PenButtonEvent + * - To avoid treating pen events as mouse events, ignore SDL_MouseMotionEvent and SDL_MouseButtonEvent + * whenever "which" == SDL_PEN_MOUSEID. * * This header file describes advanced functionality that can be useful for managing user configuration * and understanding the capabilities of the attached pens. * - * We primarily identify pens by ::SDL_PenID. The implementation makes a best effort to relate each :SDL_PenID - * to the same physical device during a session. Formerly valid ::SDL_PenID values remain valid + * We primarily identify pens by SDL_PenID. The implementation makes a best effort to relate each :SDL_PenID + * to the same physical device during a session. Formerly valid SDL_PenID values remain valid * even if a device disappears. * - * For identifying pens across sessions, the API provides the type ::SDL_GUID . + * For identifying pens across sessions, the API provides the type SDL_GUID . */ #ifndef SDL_pen_h_ @@ -57,7 +57,7 @@ extern "C" { typedef Uint32 SDL_PenID; /**< SDL_PenIDs identify pens uniquely within a session */ -#define SDL_PEN_INVALID ((SDL_PenID)0) /**< Reserved invalid ::SDL_PenID is valid */ +#define SDL_PEN_INVALID ((SDL_PenID)0) /**< Reserved invalid SDL_PenID is valid */ #define SDL_PEN_MOUSEID ((SDL_MouseID)-2) /**< Device ID for mouse events triggered by pen events */ @@ -66,16 +66,20 @@ 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. + * 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, e.g., "SDL_sinf(xtilt * SDL_PI_F / 180.0)". + * SDL_sinf on the XTILT, YTILT, or ROTATION component, for example: + * + * `SDL_sinf(xtilt * SDL_PI_F / 180.0)`. + * + * \since This enum is available since SDL 3.0.0 */ -typedef enum +typedef enum SDL_PenAxis { SDL_PEN_AXIS_PRESSURE = 0, /**< Pen pressure. Unidirectional: 0..1.0 */ SDL_PEN_AXIS_XTILT, /**< Pen horizontal tilt angle. Bidirectional: -90.0..90.0 (left-to-right). @@ -89,7 +93,7 @@ typedef enum SDL_PEN_AXIS_LAST = SDL_PEN_NUM_AXES - 1 /**< Last axis index plus 1 */ } SDL_PenAxis; -/* Pen flags. These share a bitmask space with ::SDL_BUTTON_LEFT and friends. */ +/* Pen flags. These share a bitmask space with SDL_BUTTON_LEFT and friends. */ #define SDL_PEN_FLAG_DOWN_BIT_INDEX 13 /* Bit for storing that pen is touching the surface */ #define SDL_PEN_FLAG_INK_BIT_INDEX 14 /* Bit for storing has-non-eraser-capability status */ #define SDL_PEN_FLAG_ERASER_BIT_INDEX 15 /* Bit for storing is-eraser or has-eraser-capability property */ @@ -98,41 +102,31 @@ typedef enum #define SDL_PEN_CAPABILITY(capbit) (1ul << (capbit)) #define SDL_PEN_AXIS_CAPABILITY(axis) SDL_PEN_CAPABILITY((axis) + SDL_PEN_FLAG_AXIS_BIT_OFFSET) -/** - * Pen tips - * @{ - */ +/* Pen tips */ #define SDL_PEN_TIP_INK SDL_PEN_FLAG_INK_BIT_INDEX /**< Regular pen tip (for drawing) touched the surface */ #define SDL_PEN_TIP_ERASER SDL_PEN_FLAG_ERASER_BIT_INDEX /**< Eraser pen tip touched the surface */ -/** @} */ - -/** - * \defgroup SDL_PEN_CAPABILITIES Pen capabilities - * Pen capabilities reported by ::SDL_GetPenCapabilities - * @{ - */ +/* Pen capabilities reported by SDL_GetPenCapabilities */ #define SDL_PEN_DOWN_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_DOWN_BIT_INDEX) /**< Pen tip is currently touching the drawing surface. */ -#define SDL_PEN_INK_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_INK_BIT_INDEX) /**< Pen has a regular drawing tip (::SDL_GetPenCapabilities). For events (::SDL_PenButtonEvent, ::SDL_PenMotionEvent, ::SDL_GetPenStatus) this flag is mutually exclusive with ::SDL_PEN_ERASER_MASK . */ -#define SDL_PEN_ERASER_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_ERASER_BIT_INDEX) /**< Pen has an eraser tip (::SDL_GetPenCapabilities) or is being used as eraser (::SDL_PenButtonEvent , ::SDL_PenMotionEvent , ::SDL_GetPenStatus) */ -#define SDL_PEN_AXIS_PRESSURE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE) /**< Pen provides pressure information in axis ::SDL_PEN_AXIS_PRESSURE */ -#define SDL_PEN_AXIS_XTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_XTILT) /**< Pen provides horizontal tilt information in axis ::SDL_PEN_AXIS_XTILT */ -#define SDL_PEN_AXIS_YTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_YTILT) /**< Pen provides vertical tilt information in axis ::SDL_PEN_AXIS_YTILT */ -#define SDL_PEN_AXIS_DISTANCE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_DISTANCE) /**< Pen provides distance to drawing tablet in ::SDL_PEN_AXIS_DISTANCE */ -#define SDL_PEN_AXIS_ROTATION_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_ROTATION) /**< Pen provides barrel rotation information in axis ::SDL_PEN_AXIS_ROTATION */ -#define SDL_PEN_AXIS_SLIDER_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_SLIDER) /**< Pen provides slider / finger wheel or similar in axis ::SDL_PEN_AXIS_SLIDER */ +#define SDL_PEN_INK_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_INK_BIT_INDEX) /**< Pen has a regular drawing tip (SDL_GetPenCapabilities). For events (SDL_PenButtonEvent, SDL_PenMotionEvent, SDL_GetPenStatus) this flag is mutually exclusive with SDL_PEN_ERASER_MASK . */ +#define SDL_PEN_ERASER_MASK SDL_PEN_CAPABILITY(SDL_PEN_FLAG_ERASER_BIT_INDEX) /**< Pen has an eraser tip (SDL_GetPenCapabilities) or is being used as eraser (SDL_PenButtonEvent , SDL_PenMotionEvent , SDL_GetPenStatus) */ +#define SDL_PEN_AXIS_PRESSURE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_PRESSURE) /**< Pen provides pressure information in axis SDL_PEN_AXIS_PRESSURE */ +#define SDL_PEN_AXIS_XTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_XTILT) /**< Pen provides horizontal tilt information in axis SDL_PEN_AXIS_XTILT */ +#define SDL_PEN_AXIS_YTILT_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_YTILT) /**< Pen provides vertical tilt information in axis SDL_PEN_AXIS_YTILT */ +#define SDL_PEN_AXIS_DISTANCE_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_DISTANCE) /**< Pen provides distance to drawing tablet in SDL_PEN_AXIS_DISTANCE */ +#define SDL_PEN_AXIS_ROTATION_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_ROTATION) /**< Pen provides barrel rotation information in axis SDL_PEN_AXIS_ROTATION */ +#define SDL_PEN_AXIS_SLIDER_MASK SDL_PEN_AXIS_CAPABILITY(SDL_PEN_AXIS_SLIDER) /**< Pen provides slider / finger wheel or similar in axis SDL_PEN_AXIS_SLIDER */ #define SDL_PEN_AXIS_BIDIRECTIONAL_MASKS (SDL_PEN_AXIS_XTILT_MASK | SDL_PEN_AXIS_YTILT_MASK) -/**< Masks for all axes that may be bidirectional */ -/** @} */ /** * Pen types * * 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 */ -typedef enum +typedef enum SDL_PenSubtype { SDL_PEN_TYPE_UNKNOWN = 0, SDL_PEN_TYPE_ERASER = 1, /**< Eraser */ @@ -149,15 +143,15 @@ typedef enum /** * Retrieves all pens that are connected to the system. * - * Yields an array of ::SDL_PenID values. These identify and track pens + * Yields an array of SDL_PenID values. These identify and track pens * throughout a session. To track pens across sessions (program restart), use - * ::SDL_GUID . + * SDL_GUID . * * \param count The number of pens in the array (number of array elements * minus 1, i.e., not counting the terminator 0). - * \returns A 0 terminated array of ::SDL_PenID values, or NULL on error. The - * array must be freed with ::SDL_free(). On a NULL return, - * ::SDL_GetError() is set. + * \returns A 0 terminated array of SDL_PenID values, or NULL on error. The + * array must be freed with SDL_free(). On a NULL return, + * SDL_GetError() is set. * * \since This function is available since SDL 3.0.0 */ @@ -166,29 +160,29 @@ extern DECLSPEC SDL_PenID *SDLCALL SDL_GetPens(int *count); /** * Retrieves the pen's current status. * - * If the pen is detached (cf. ::SDL_PenConnected), this operation may return + * If the pen is detached (cf. SDL_PenConnected), this operation may return * default values. * * \param instance_id The pen to query. * \param x Out-mode parameter for pen x coordinate. May be NULL. * \param y Out-mode parameter for pen y coordinate. May be NULL. * \param axes Out-mode parameter for axis information. May be null. The axes - * are in the same order as ::SDL_PenAxis. + * are in the same order as SDL_PenAxis. * \param num_axes Maximum number of axes to write to "axes". - * \returns a bit mask with the current pen button states (::SDL_BUTTON_LMASK - * etc.), possibly ::SDL_PEN_DOWN_MASK, and exactly one of - * ::SDL_PEN_INK_MASK or ::SDL_PEN_ERASER_MASK , or 0 on error (see - * ::SDL_GetError()). + * \returns a bit mask with the current pen button states (SDL_BUTTON_LMASK + * etc.), possibly SDL_PEN_DOWN_MASK, and exactly one of + * SDL_PEN_INK_MASK or SDL_PEN_ERASER_MASK , or 0 on error (see + * SDL_GetError()). * * \since This function is available since SDL 3.0.0 */ extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x, float *y, float *axes, size_t num_axes); /** - * Retrieves an ::SDL_PenID for the given ::SDL_GUID. + * Retrieves an SDL_PenID for the given SDL_GUID. * * \param guid A pen GUID. - * \returns A valid ::SDL_PenID, or ::SDL_PEN_INVALID if there is no matching + * \returns A valid SDL_PenID, or SDL_PEN_INVALID if there is no matching * SDL_PenID. * * \since This function is available since SDL 3.0.0 @@ -196,11 +190,11 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float *x, extern DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid); /** - * Retrieves the ::SDL_GUID for a given ::SDL_PenID. + * Retrieves the SDL_GUID for a given SDL_PenID. * * \param instance_id The pen to query. * \returns The corresponding pen GUID; persistent across multiple sessions. - * If "instance_id" is ::SDL_PEN_INVALID, returns an all-zeroes GUID. + * If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID. * * \since This function is available since SDL 3.0.0 */ @@ -209,7 +203,7 @@ extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id); /** * Checks whether a pen is still attached. * - * If a pen is detached, it will not show up for ::SDL_GetPens(). Other + * If a pen is detached, it will not show up for SDL_GetPens(). Other * operations will still be available but may return default values. * * \param instance_id A pen ID. @@ -221,23 +215,23 @@ extern DECLSPEC SDL_GUID SDLCALL SDL_GetPenGUID(SDL_PenID instance_id); extern DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id); /** - * Retrieves a human-readable description for a ::SDL_PenID. + * Retrieves a human-readable description for a SDL_PenID. * * \param instance_id The pen to query. * \returns A string that contains the name of the pen, intended for human * consumption. The string might or might not be localised, depending * on platform settings. It is not guaranteed to be unique; use - * ::SDL_GetPenGUID() for (best-effort) unique identifiers. The + * SDL_GetPenGUID() for (best-effort) unique identifiers. The * pointer is managed by the SDL pen subsystem and must not be * deallocated. The pointer remains valid until SDL is shut down. - * Returns NULL on error (cf. ::SDL_GetError()) + * Returns NULL on error (cf. SDL_GetError()) * * \since This function is available since SDL 3.0.0 */ extern DECLSPEC const char *SDLCALL SDL_GetPenName(SDL_PenID instance_id); /** - * Pen capabilities, as reported by ::SDL_GetPenCapabilities() + * Pen capabilities, as reported by SDL_GetPenCapabilities() */ typedef struct SDL_PenCapabilityInfo { @@ -247,7 +241,7 @@ typedef struct SDL_PenCapabilityInfo } SDL_PenCapabilityInfo; /** - * Retrieves capability flags for a given ::SDL_PenID. + * Retrieves capability flags for a given SDL_PenID. * * \param instance_id The pen to query. * \param capabilities Detail information about pen capabilities, such as the @@ -259,14 +253,14 @@ typedef struct SDL_PenCapabilityInfo extern DECLSPEC Uint32 SDLCALL SDL_GetPenCapabilities(SDL_PenID instance_id, SDL_PenCapabilityInfo *capabilities); /** - * Retrieves the pen type for a given ::SDL_PenID. + * Retrieves the pen type for a given SDL_PenID. * * \param instance_id The pen to query. - * \returns The corresponding pen type (cf. ::SDL_PenSubtype) or 0 on error. + * \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 + * 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 + * 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 b0606ce62..e12eeef1d 100644 --- a/include/SDL3/SDL_pixels.h +++ b/include/SDL3/SDL_pixels.h @@ -85,7 +85,7 @@ extern "C" { /* @} */ /** Pixel type. */ -typedef enum +typedef enum SDL_PixelType { SDL_PIXELTYPE_UNKNOWN, SDL_PIXELTYPE_INDEX1, @@ -104,7 +104,7 @@ typedef enum } SDL_PixelType; /** Bitmap pixel order, high bit -> low bit. */ -typedef enum +typedef enum SDL_BitmapOrder { SDL_BITMAPORDER_NONE, SDL_BITMAPORDER_4321, @@ -112,7 +112,7 @@ typedef enum } SDL_BitmapOrder; /** Packed component order, high bit -> low bit. */ -typedef enum +typedef enum SDL_PackedOrder { SDL_PACKEDORDER_NONE, SDL_PACKEDORDER_XRGB, @@ -126,7 +126,7 @@ typedef enum } SDL_PackedOrder; /** Array component order, low byte -> high byte. */ -typedef enum +typedef enum SDL_ArrayOrder { SDL_ARRAYORDER_NONE, SDL_ARRAYORDER_RGB, @@ -138,7 +138,7 @@ typedef enum } SDL_ArrayOrder; /** Packed component layout. */ -typedef enum +typedef enum SDL_PackedLayout { SDL_PACKEDLAYOUT_NONE, SDL_PACKEDLAYOUT_332, @@ -212,7 +212,7 @@ typedef enum ((format) && (SDL_PIXELFLAG(format) != 1)) /* Note: If you modify this list, update SDL_GetPixelFormatName() */ -typedef enum +typedef enum SDL_PixelFormatEnum { SDL_PIXELFORMAT_UNKNOWN, SDL_PIXELFORMAT_INDEX1LSB = @@ -449,7 +449,7 @@ typedef enum /** * The color type */ -typedef enum +typedef enum SDL_ColorType { SDL_COLOR_TYPE_UNKNOWN = 0, SDL_COLOR_TYPE_RGB = 1, @@ -459,7 +459,7 @@ typedef enum /** * The color range, as described by https://www.itu.int/rec/R-REC-BT.2100-2-201807-I/en */ -typedef enum +typedef enum SDL_ColorRange { SDL_COLOR_RANGE_UNKNOWN = 0, SDL_COLOR_RANGE_LIMITED = 1, /**< Narrow range, e.g. 16-235 for 8-bit RGB and luma, and 16-240 for 8-bit chroma */ @@ -469,7 +469,7 @@ typedef enum /** * The color primaries, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en */ -typedef enum +typedef enum SDL_ColorPrimaries { SDL_COLOR_PRIMARIES_UNKNOWN = 0, SDL_COLOR_PRIMARIES_BT709 = 1, /**< ITU-R BT.709-6 */ @@ -490,7 +490,7 @@ typedef enum /** * The transfer characteristics, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en */ -typedef enum +typedef enum SDL_TransferCharacteristics { SDL_TRANSFER_CHARACTERISTICS_UNKNOWN = 0, SDL_TRANSFER_CHARACTERISTICS_BT709 = 1, /**< Rec. ITU-R BT.709-6 / ITU-R BT1361 */ @@ -516,7 +516,7 @@ typedef enum /** * The matrix coefficients, as described by https://www.itu.int/rec/T-REC-H.273-201612-S/en */ -typedef enum +typedef enum SDL_MatrixCoefficients { SDL_MATRIX_COEFFICIENTS_IDENTITY = 0, SDL_MATRIX_COEFFICIENTS_BT709 = 1, /**< ITU-R BT.709-6 */ @@ -538,7 +538,7 @@ typedef enum /** * The chroma sample location */ -typedef enum +typedef enum SDL_ChromaLocation { SDL_CHROMA_LOCATION_NONE = 0, /**< RGB, no chroma sampling */ SDL_CHROMA_LOCATION_LEFT = 1, /**< In MPEG-2, MPEG-4, and AVC, Cb and Cr are taken on midpoint of the left-edge of the 2x2 square. In other words, they have the same horizontal location as the top-left pixel, but is shifted one-half pixel down vertically. */ @@ -565,7 +565,7 @@ typedef enum #define SDL_ISCOLORSPACE_LIMITED_RANGE(X) (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL) #define SDL_ISCOLORSPACE_FULL_RANGE(X) (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL) -typedef enum +typedef enum SDL_Colorspace { SDL_COLORSPACE_UNKNOWN, @@ -661,9 +661,13 @@ 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). + * + * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_Color { @@ -677,6 +681,8 @@ typedef struct SDL_Color /** * The bits of this structure can be directly reinterpreted as a float-packed * color which uses the SDL_PIXELFORMAT_RGBA128_FLOAT format + * + * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_FColor { @@ -687,16 +693,30 @@ typedef struct SDL_FColor } SDL_FColor; #define SDL_FColour SDL_FColor +/** + * A set of indexed colors representing a palette. + * + * \since This struct is available since SDL 3.0.0. + * + * \sa SDL_PixelFormat + * \sa SDL_SetPaletteColors + */ typedef struct SDL_Palette { - int ncolors; - SDL_Color *colors; - Uint32 version; - int refcount; + int ncolors; /*< number of elements in `colors`. */ + SDL_Color *colors; /*< an array of colors, `ncolors` long. */ + Uint32 version; /*< internal use only, do not touch. */ + int refcount; /*< internal use only, do not touch. */ } SDL_Palette; /** - * \note Everything in the pixel format structure is read-only. + * 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. + * + * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_PixelFormat { diff --git a/include/SDL3/SDL_power.h b/include/SDL3/SDL_power.h index 15e5baa44..d452b2a3b 100644 --- a/include/SDL3/SDL_power.h +++ b/include/SDL3/SDL_power.h @@ -38,9 +38,13 @@ extern "C" { #endif /** - * The basic state for the system's power supply. + * The basic state for the system's power supply. + * + * These are results returned by SDL_GetPowerInfo(). + * + * \since This enum is available since SDL 3.0.0 */ -typedef enum +typedef enum SDL_PowerState { SDL_POWERSTATE_ERROR = -1, /**< error determining power status */ SDL_POWERSTATE_UNKNOWN, /**< cannot determine power status */ diff --git a/include/SDL3/SDL_properties.h b/include/SDL3/SDL_properties.h index f9d895a9e..b16e2ac5c 100644 --- a/include/SDL3/SDL_properties.h +++ b/include/SDL3/SDL_properties.h @@ -45,7 +45,7 @@ typedef Uint32 SDL_PropertiesID; /** * SDL property type */ -typedef enum +typedef enum SDL_PropertyType { SDL_PROPERTY_TYPE_INVALID, SDL_PROPERTY_TYPE_POINTER, @@ -56,7 +56,7 @@ typedef enum } SDL_PropertyType; /** - * Get the global SDL properties + * Get the global SDL properties. * * \returns a valid property ID on success or 0 on failure; call * SDL_GetError() for more information. @@ -69,7 +69,7 @@ typedef enum extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); /** - * Create a set of properties + * Create a set of properties. * * All properties are automatically destroyed when SDL_Quit() is called. * @@ -85,7 +85,7 @@ extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); extern DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void); /** - * Copy a set of properties + * Copy a set of properties. * * Copy all the properties from one set of properties to another, with the * exception of properties requiring cleanup (set using @@ -104,7 +104,7 @@ extern DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void); extern DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst); /** - * Lock a set of properties + * Lock a set of properties. * * Obtain a multi-threaded lock for these properties. Other threads will wait * while trying to lock these properties until they are unlocked. Properties @@ -128,7 +128,7 @@ extern DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_Propert extern DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props); /** - * Unlock a set of properties + * Unlock a set of properties. * * \param props the properties to unlock * @@ -142,7 +142,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props); /** * Set a property on a set of properties with a cleanup function that is - * called when the property is deleted + * called when the property is deleted. * * The cleanup function is also called if setting the property fails for any * reason. @@ -166,7 +166,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props); extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata); /** - * Set a property on a set of properties + * Set a property on a set of properties. * * \param props the properties to modify * \param name the name of the property to modify @@ -189,7 +189,7 @@ extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, c extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value); /** - * Set a string property on a set of properties + * Set a string property on a set of properties. * * This function makes a copy of the string; the caller does not have to * preserve the data after this call completes. @@ -209,7 +209,7 @@ extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char * extern DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value); /** - * Set an integer property on a set of properties + * Set an integer property on a set of properties. * * \param props the properties to modify * \param name the name of the property to modify @@ -226,7 +226,7 @@ extern DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const extern DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value); /** - * Set a floating point property on a set of properties + * Set a floating point property on a set of properties. * * \param props the properties to modify * \param name the name of the property to modify @@ -243,7 +243,7 @@ extern DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const extern DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value); /** - * Set a boolean property on a set of properties + * Set a boolean property on a set of properties. * * \param props the properties to modify * \param name the name of the property to modify @@ -275,7 +275,7 @@ extern DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const extern DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name); /** - * Get the type of a property on a set of properties + * Get the type of a property on a set of properties. * * \param props the properties to query * \param name the name of the property to query @@ -291,7 +291,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const c extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID props, const char *name); /** - * Get a property on a set of properties + * Get a property on a set of properties. * * By convention, the names of properties that SDL exposes on objects will * start with "SDL.", and properties that SDL uses internally will start with @@ -323,7 +323,7 @@ extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID pr extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char *name, void *default_value); /** - * Get a string property on a set of properties + * Get a string property on a set of properties. * * \param props the properties to query * \param name the name of the property to query @@ -342,7 +342,7 @@ extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value); /** - * Get a number property on a set of properties + * Get a number property on a set of properties. * * You can use SDL_GetPropertyType() to query whether the property exists and * is a number property. @@ -364,7 +364,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value); /** - * Get a floating point property on a set of properties + * Get a floating point property on a set of properties. * * You can use SDL_GetPropertyType() to query whether the property exists and * is a floating point property. @@ -386,7 +386,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, con extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value); /** - * Get a boolean property on a set of properties + * Get a boolean property on a set of properties. * * You can use SDL_GetPropertyType() to query whether the property exists and * is a boolean property. @@ -408,7 +408,7 @@ extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const extern DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value); /** - * Clear a property on a set of properties + * Clear a property on a set of properties. * * \param props the properties to modify * \param name the name of the property to clear @@ -424,7 +424,7 @@ extern DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name); /** - * Enumerate the properties on a set of properties + * Enumerate the properties on a set of properties. * * The callback function is called for each property on the set of properties. * The properties are locked during enumeration. @@ -442,7 +442,7 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop extern DECLSPEC int SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata); /** - * Destroy a set of properties + * Destroy a set of properties. * * All properties are deleted and their cleanup functions will be called, if * any. diff --git a/include/SDL3/SDL_rect.h b/include/SDL3/SDL_rect.h index 4b496e348..b96802f81 100644 --- a/include/SDL3/SDL_rect.h +++ b/include/SDL3/SDL_rect.h @@ -38,10 +38,12 @@ extern "C" { #endif /** - * The structure that defines a point (integer) + * The structure that defines a point (using integers). * * \sa SDL_GetRectEnclosingPoints * \sa SDL_PointInRect + * + * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_Point { @@ -50,10 +52,12 @@ typedef struct SDL_Point } SDL_Point; /** - * The structure that defines a point (floating point) + * The structure that defines a point (using floating point values). * * \sa SDL_GetRectEnclosingPointsFloat * \sa SDL_PointInRectFloat + * + * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_FPoint { @@ -63,7 +67,7 @@ typedef struct SDL_FPoint /** - * A rectangle, with the origin at the upper left (integer). + * A rectangle, with the origin at the upper left (using integers). * * \sa SDL_RectEmpty * \sa SDL_RectsEqual @@ -72,6 +76,8 @@ 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 { @@ -81,7 +87,7 @@ typedef struct SDL_Rect /** - * A rectangle, with the origin at the upper left (floating point). + * A rectangle, with the origin at the upper left (using floating point values). * * \sa SDL_RectEmptyFloat * \sa SDL_RectsEqualFloat @@ -92,6 +98,8 @@ 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 5024931e7..8efd80dee 100644 --- a/include/SDL3/SDL_render.h +++ b/include/SDL3/SDL_render.h @@ -62,14 +62,14 @@ extern "C" { #endif /** - * The name of the software renderer + * The name of the software renderer. */ #define SDL_SOFTWARE_RENDERER "software" /** - * Flags used when creating a rendering context + * Flags used when creating a rendering context. */ -typedef enum +typedef enum SDL_RendererFlags { SDL_RENDERER_PRESENTVSYNC = 0x00000004 /**< Present is synchronized with the refresh rate */ } SDL_RendererFlags; @@ -88,7 +88,7 @@ typedef struct SDL_RendererInfo } SDL_RendererInfo; /** - * Vertex structure + * Vertex structure. */ typedef struct SDL_Vertex { @@ -100,7 +100,7 @@ typedef struct SDL_Vertex /** * The access pattern allowed for a texture. */ -typedef enum +typedef enum SDL_TextureAccess { SDL_TEXTUREACCESS_STATIC, /**< Changes rarely, not lockable */ SDL_TEXTUREACCESS_STREAMING, /**< Changes frequently, lockable */ @@ -108,9 +108,9 @@ typedef enum } SDL_TextureAccess; /** - * How the logical size is mapped to the output + * How the logical size is mapped to the output. */ -typedef enum +typedef enum SDL_RendererLogicalPresentation { SDL_LOGICAL_PRESENTATION_DISABLED, /**< There is no logical size in effect */ SDL_LOGICAL_PRESENTATION_STRETCH, /**< The rendered content is stretched to the output resolution */ @@ -2078,7 +2078,7 @@ extern DECLSPEC int SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer); extern DECLSPEC void *SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *renderer); /** - * Get the Metal command encoder for the current frame + * Get the Metal command encoder for the current frame. * * This function returns `void *`, so SDL doesn't have to include Metal's * headers, but it can be safely cast to an `id`. diff --git a/include/SDL3/SDL_scancode.h b/include/SDL3/SDL_scancode.h index 336d6f0ba..5719905f2 100644 --- a/include/SDL3/SDL_scancode.h +++ b/include/SDL3/SDL_scancode.h @@ -31,19 +31,20 @@ #include /** - * The SDL keyboard scancode representation. + * The SDL keyboard scancode representation. * - * An SDL scancode is the physical representation of a key on the keyboard, - * independent of language and keyboard mapping. + * An SDL scancode is the physical representation of a key on the keyboard, + * independent of language and keyboard mapping. * - * Values of this type are used to represent keyboard keys, among other places - * in the \link SDL_Keysym::scancode key.keysym.scancode \endlink field of the - * SDL_Event structure. + * Values of this type are used to represent keyboard keys, among other places + * in the `keysym.scancode` field of the SDL_KeyboardEvent structure. * - * The values in this enumeration are based on the USB usage page standard: - * https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf + * The values in this enumeration are based on the USB usage page standard: + * https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf + * + * \since This enum is available since SDL 3.0.0. */ -typedef enum +typedef enum SDL_Scancode { SDL_SCANCODE_UNKNOWN = 0, diff --git a/include/SDL3/SDL_sensor.h b/include/SDL3/SDL_sensor.h index 6db5beb38..fa347a0c3 100644 --- a/include/SDL3/SDL_sensor.h +++ b/include/SDL3/SDL_sensor.h @@ -79,7 +79,7 @@ typedef enum } SDL_SensorType; /** - * Accelerometer sensor + * Accelerometer sensor. * * The accelerometer returns the current acceleration in SI meters per * second squared. This measurement includes the force of gravity, so @@ -91,9 +91,10 @@ typedef enum * 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: - * -X ... +X : left ... right - * -Y ... +Y : bottom ... top - * -Z ... +Z : farther ... closer + * + * - -X ... +X : left ... right + * - -Y ... +Y : bottom ... top + * - -Z ... +Z : farther ... closer * * The axis data is not changed when the device is rotated. * @@ -102,7 +103,7 @@ typedef enum #define SDL_STANDARD_GRAVITY 9.80665f /** - * Gyroscope sensor + * Gyroscope sensor. * * The gyroscope returns the current rate of rotation in radians per second. * The rotation is positive in the counter-clockwise direction. That is, @@ -115,9 +116,10 @@ typedef enum * values[2]: Angular speed around the z axis (roll) * * 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 - * -Z ... +Z : farther ... closer + * + * - -X ... +X : left ... right + * - -Y ... +Y : bottom ... top + * - -Z ... +Z : farther ... closer * * The axis data is not changed when the device is rotated. * @@ -205,7 +207,7 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_GetSensorFromInstanceID(SDL_SensorID ins extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor *sensor); /** - * Get the implementation dependent name of a sensor + * Get the implementation dependent name of a sensor. * * \param sensor The SDL_Sensor object * \returns the sensor name, or NULL if `sensor` is NULL. diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h index e6a387c31..c2f708fc8 100644 --- a/include/SDL3/SDL_stdinc.h +++ b/include/SDL3/SDL_stdinc.h @@ -93,9 +93,13 @@ char *alloca(); #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. * - * e.g. #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n") + * For example: + * + * ```c + * #define LOG_ERROR(X) OutputDebugString(SDL_STRINGIFY_ARG(__FUNCTION__) ": " X "\n")` + * ``` */ #define SDL_STRINGIFY_ARG(arg) #arg @@ -187,7 +191,7 @@ 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(). @@ -417,7 +421,7 @@ typedef void *(SDLCALL *SDL_realloc_func)(void *mem, size_t size); typedef void (SDLCALL *SDL_free_func)(void *mem); /** - * Get the original set of SDL memory functions + * Get the original set of SDL memory functions. * * \param malloc_func filled with malloc function * \param calloc_func filled with calloc function @@ -432,7 +436,7 @@ extern DECLSPEC void SDLCALL SDL_GetOriginalMemoryFunctions(SDL_malloc_func *mal SDL_free_func *free_func); /** - * Get the current set of SDL memory functions + * Get the current set of SDL memory functions. * * \param malloc_func filled with malloc function * \param calloc_func filled with calloc function @@ -447,7 +451,7 @@ extern DECLSPEC void SDLCALL SDL_GetMemoryFunctions(SDL_malloc_func *malloc_func SDL_free_func *free_func); /** - * Replace SDL's memory allocation functions with a custom set + * Replace SDL's memory allocation functions with a custom set. * * \param malloc_func custom malloc function * \param calloc_func custom calloc function @@ -464,7 +468,7 @@ extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, SDL_free_func free_func); /** - * Allocate memory aligned to a specific value + * Allocate memory aligned to a specific value. * * If `alignment` is less than the size of `void *`, then it will be increased * to match that. @@ -485,7 +489,7 @@ extern DECLSPEC int SDLCALL SDL_SetMemoryFunctions(SDL_malloc_func malloc_func, extern DECLSPEC SDL_MALLOC void *SDLCALL SDL_aligned_alloc(size_t alignment, size_t size); /** - * Free memory allocated by SDL_aligned_alloc() + * Free memory allocated by SDL_aligned_alloc(). * * \since This function is available since SDL 3.0.0. * @@ -494,7 +498,7 @@ extern DECLSPEC SDL_MALLOC void *SDLCALL SDL_aligned_alloc(size_t alignment, siz extern DECLSPEC void SDLCALL SDL_aligned_free(void *mem); /** - * Get the number of outstanding (unfreed) allocations + * Get the number of outstanding (unfreed) allocations. * * \returns the number of allocations * diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h index ddef6abda..779b11f29 100644 --- a/include/SDL3/SDL_surface.h +++ b/include/SDL3/SDL_surface.h @@ -69,7 +69,7 @@ typedef struct SDL_BlitMap SDL_BlitMap; /* this is an opaque type. */ /** * The scaling mode */ -typedef enum +typedef enum SDL_ScaleMode { SDL_SCALEMODE_NEAREST, /**< nearest pixel sampling */ SDL_SCALEMODE_LINEAR, /**< linear filtering */ @@ -79,7 +79,7 @@ typedef enum /** * The flip mode */ -typedef enum +typedef enum SDL_FlipMode { SDL_FLIP_NONE, /**< Do not flip */ SDL_FLIP_HORIZONTAL, /**< flip horizontally */ @@ -419,7 +419,7 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *file); extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, int flag); /** - * Returns whether the surface is RLE enabled + * Returns whether the surface is RLE enabled. * * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. * @@ -459,7 +459,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface); extern DECLSPEC int SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, int flag, Uint32 key); /** - * Returns whether the surface has a color key + * Returns whether the surface has a color key. * * It is safe to pass a NULL `surface` here; it will return SDL_FALSE. * diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h index 3d8410085..fa1272eef 100644 --- a/include/SDL3/SDL_system.h +++ b/include/SDL3/SDL_system.h @@ -112,7 +112,7 @@ typedef union _XEvent XEvent; typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); /** - * Set a callback for every X11 event + * Set a callback for every X11 event. * * The callback may modify the event, and should return SDL_TRUE if the event * should continue to be processed, or SDL_FALSE to prevent further @@ -125,9 +125,7 @@ typedef SDL_bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); */ extern DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata); -/* - * Platform specific functions for Linux - */ +/* Platform specific functions for Linux*/ #ifdef SDL_PLATFORM_LINUX /** @@ -483,7 +481,7 @@ extern DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param); /** * WinRT / Windows Phone path types */ -typedef enum +typedef enum SDL_WinRT_Path { /** The installed app's root directory. Files here are likely to be read-only. */ @@ -507,7 +505,7 @@ typedef enum /** * WinRT Device Family */ -typedef enum +typedef enum SDL_WinRT_DeviceFamily { /** Unknown family */ SDL_WINRT_DEVICEFAMILY_UNKNOWN, diff --git a/include/SDL3/SDL_test_assert.h b/include/SDL3/SDL_test_assert.h index 122c355bd..1c00bc157 100644 --- a/include/SDL3/SDL_test_assert.h +++ b/include/SDL3/SDL_test_assert.h @@ -42,17 +42,13 @@ extern "C" { #endif -/** - * Fails the assert. - */ +/* Fails the assert. */ #define ASSERT_FAIL 0 -/** - * Passes the assert. - */ +/* Passes the assert. */ #define ASSERT_PASS 1 -/** +/* * Assert that logs and break execution flow on failures. * * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0). @@ -60,7 +56,7 @@ extern "C" { */ void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); -/** +/* * Assert for test cases that logs but does not break execution flow on failures. Updates assertion counters. * * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0). @@ -70,25 +66,25 @@ void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *as */ int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2); -/** +/* * Explicitly pass without checking an assertion condition. Updates assertion counter. * * \param assertDescription Message to log with the assert describing it. */ void SDLTest_AssertPass(SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(1); -/** +/* * Resets the assert summary counters to zero. */ void SDLTest_ResetAssertSummary(void); -/** +/* * Logs summary of all assertions (total, pass, fail) since last reset as INFO or ERROR. */ void SDLTest_LogAssertSummary(void); -/** +/* * Converts the current assert summary state to a test result. * * \returns TEST_RESULT_PASSED, TEST_RESULT_FAILED, or TEST_RESULT_NO_ASSERT diff --git a/include/SDL3/SDL_test_crc32.h b/include/SDL3/SDL_test_crc32.h index 07f89aba2..72e96e563 100644 --- a/include/SDL3/SDL_test_crc32.h +++ b/include/SDL3/SDL_test_crc32.h @@ -60,7 +60,7 @@ extern "C" { #define CRC32_POLY 0xEDB88320 /* Perl String::CRC32 compatible */ #endif -/** +/* * Data structure for CRC32 (checksum) computation */ typedef struct SDLTest_Crc32Context { @@ -69,7 +69,7 @@ extern "C" { /* ---------- Function Prototypes ------------- */ -/** +/* * Initialize the CRC context * * Note: The function initializes the crc table required for all crc calculations. @@ -82,7 +82,7 @@ extern "C" { int SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext); -/** +/* * calculate a crc32 from a data block * * \param crcContext pointer to context variable @@ -101,7 +101,7 @@ int SDLTest_Crc32CalcEnd(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32); int SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32); -/** +/* * clean up CRC context * * \param crcContext pointer to context variable diff --git a/include/SDL3/SDL_test_font.h b/include/SDL3/SDL_test_font.h index 824f97c25..867205b86 100644 --- a/include/SDL3/SDL_test_font.h +++ b/include/SDL3/SDL_test_font.h @@ -19,7 +19,7 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** +/* * \file SDL_test_font.h * * Font related functions of SDL test framework. @@ -42,7 +42,7 @@ extern int FONT_CHARACTER_SIZE; #define FONT_LINE_HEIGHT (FONT_CHARACTER_SIZE + 2) -/** +/* * Draw a string in the currently set font. * * \param renderer The renderer to draw on. @@ -54,7 +54,7 @@ extern int FONT_CHARACTER_SIZE; */ int SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c); -/** +/* * Draw a UTF-8 string in the currently set font. * * The font currently only supports characters in the Basic Latin and Latin-1 Supplement sets. @@ -68,7 +68,7 @@ int SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c); */ int SDLTest_DrawString(SDL_Renderer *renderer, float x, float y, const char *s); -/** +/* * Data used for multi-line text output */ typedef struct SDLTest_TextWindow @@ -79,7 +79,7 @@ typedef struct SDLTest_TextWindow char **lines; } SDLTest_TextWindow; -/** +/* * Create a multi-line text output window * * \param x The X coordinate of the upper left corner of the window. @@ -93,7 +93,7 @@ typedef struct SDLTest_TextWindow */ SDLTest_TextWindow *SDLTest_TextWindowCreate(float x, float y, float w, float h); -/** +/* * Display a multi-line text output window * * This function should be called every frame to display the text @@ -105,7 +105,7 @@ SDLTest_TextWindow *SDLTest_TextWindowCreate(float x, float y, float w, float h) */ void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *renderer); -/** +/* * Add text to a multi-line text output window * * Adds UTF-8 text to the end of the current text. The newline character starts a @@ -120,7 +120,7 @@ void SDLTest_TextWindowDisplay(SDLTest_TextWindow *textwin, SDL_Renderer *render */ void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); -/** +/* * Add text to a multi-line text output window * * Adds UTF-8 text to the end of the current text. The newline character starts a @@ -135,7 +135,7 @@ void SDLTest_TextWindowAddText(SDLTest_TextWindow *textwin, SDL_PRINTF_FORMAT_ST */ void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char *text, size_t len); -/** +/* * Clear the text in a multi-line text output window * * \param textwin The text output window @@ -144,7 +144,7 @@ void SDLTest_TextWindowAddTextWithLength(SDLTest_TextWindow *textwin, const char */ void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin); -/** +/* * Free the storage associated with a multi-line text output window * * \param textwin The text output window @@ -153,7 +153,7 @@ void SDLTest_TextWindowClear(SDLTest_TextWindow *textwin); */ void SDLTest_TextWindowDestroy(SDLTest_TextWindow *textwin); -/** +/* * Cleanup textures used by font drawing functions. */ void SDLTest_CleanupTextDrawing(void); diff --git a/include/SDL3/SDL_test_harness.h b/include/SDL3/SDL_test_harness.h index b17e0b30a..263071fbd 100644 --- a/include/SDL3/SDL_test_harness.h +++ b/include/SDL3/SDL_test_harness.h @@ -69,7 +69,7 @@ typedef int (*SDLTest_TestCaseFp)(void *arg); /* !< Function pointer to a test case teardown function (run after every test) */ typedef void (*SDLTest_TestCaseTearDownFp)(void *arg); -/** +/* * Holds information about a single test case. */ typedef struct SDLTest_TestCaseReference { @@ -83,7 +83,7 @@ typedef struct SDLTest_TestCaseReference { int enabled; } SDLTest_TestCaseReference; -/** +/* * Holds information about a test suite (multiple test cases). */ typedef struct SDLTest_TestSuiteReference { @@ -98,7 +98,7 @@ typedef struct SDLTest_TestSuiteReference { } SDLTest_TestSuiteReference; -/** +/* * Generates a random run seed string for the harness. The generated seed will contain alphanumeric characters (0-9A-Z). * * Note: The returned string needs to be deallocated by the caller. @@ -109,7 +109,7 @@ typedef struct SDLTest_TestSuiteReference { */ char *SDLTest_GenerateRunSeed(const int length); -/** +/* * Execute a test suite using the given run seed and execution key. * * \param testSuites Suites containing the test case. diff --git a/include/SDL3/SDL_thread.h b/include/SDL3/SDL_thread.h index ad16fc25c..1dd4bb806 100644 --- a/include/SDL3/SDL_thread.h +++ b/include/SDL3/SDL_thread.h @@ -65,7 +65,7 @@ typedef Uint32 SDL_TLSID; * * \note On many systems you require special privileges to set high or time critical priority. */ -typedef enum { +typedef enum SDL_ThreadPriority { SDL_THREAD_PRIORITY_LOW, SDL_THREAD_PRIORITY_NORMAL, SDL_THREAD_PRIORITY_HIGH, diff --git a/include/SDL3/SDL_time.h b/include/SDL3/SDL_time.h index f7686f58c..ff04fa5bf 100644 --- a/include/SDL3/SDL_time.h +++ b/include/SDL3/SDL_time.h @@ -76,8 +76,8 @@ typedef enum SDL_TimeFormat SDL_TIME_FORMAT_12HR = 1, /**< 12 hour time */ } SDL_TimeFormat; -/** - * Global date/time properties +/* + * Global date/time properties. * * - `SDL_PROP_GLOBAL_SYSTEM_DATE_FORMAT_NUMBER`: the SDL_DateFormat to use as the preferred date display format * for the current system locale. @@ -148,7 +148,7 @@ extern DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDate /** * Converts a Windows FILETIME (100-nanosecond intervals since January 1, - * 1601) to an SDL time + * 1601) to an SDL time. * * This function takes the two 32-bit values of the FILETIME structure as * parameters. diff --git a/include/SDL3/SDL_timer.h b/include/SDL3/SDL_timer.h index d317bd81f..a4ab59777 100644 --- a/include/SDL3/SDL_timer.h +++ b/include/SDL3/SDL_timer.h @@ -37,9 +37,7 @@ extern "C" { #endif -/** - * SDL time constants - */ +/* SDL time constants */ #define SDL_MS_PER_SECOND 1000 #define SDL_US_PER_SECOND 1000000 #define SDL_NS_PER_SECOND 1000000000LL diff --git a/include/SDL3/SDL_touch.h b/include/SDL3/SDL_touch.h index 0e679cb0d..a81712a60 100644 --- a/include/SDL3/SDL_touch.h +++ b/include/SDL3/SDL_touch.h @@ -50,12 +50,23 @@ typedef enum SDL_TOUCH_DEVICE_INDIRECT_RELATIVE /* trackpad with screen cursor-relative coordinates */ } SDL_TouchDeviceType; +/** + * Data about a single finger in a multitouch event. + * + * Each touch even is a collection of fingers that are simultaneously in + * contact with the touch device (so a "touch" can be a "multitouch," in + * reality), and this struct reports details of the specific fingers. + * + * \since This struct is available since SDL 3.0.0. + * + * \sa SDL_GetTouchFinger + */ typedef struct SDL_Finger { - SDL_FingerID id; - float x; - float y; - float pressure; + SDL_FingerID id; /**< the finger ID */ + float x; /**< the x-axis location of the touch event, normalized (0...1) */ + float y; /**< the y-axis location of the touch event, normalized (0...1) */ + float pressure; /**< the quantity of pressure applied, normalized (0...1) */ } SDL_Finger; /* Used as the device ID for mouse events simulated with touch input */ diff --git a/include/SDL3/SDL_version.h b/include/SDL3/SDL_version.h index 3ef442866..24c141166 100644 --- a/include/SDL3/SDL_version.h +++ b/include/SDL3/SDL_version.h @@ -48,6 +48,8 @@ extern "C" { * * \sa SDL_VERSION * \sa SDL_GetVersion + * + * \since This struct is available since SDL 3.0.0. */ typedef struct SDL_Version { @@ -56,8 +58,7 @@ typedef struct SDL_Version Uint8 patch; /**< update version */ } SDL_Version; -/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL -*/ +/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL */ #define SDL_MAJOR_VERSION 3 #define SDL_MINOR_VERSION 1 #define SDL_PATCHLEVEL 1 @@ -76,6 +77,8 @@ typedef struct SDL_Version * * \sa SDL_Version * \sa SDL_GetVersion + * + * \since This macro is available since SDL 3.0.0. */ #define SDL_VERSION(x) \ { \ @@ -85,22 +88,31 @@ typedef struct SDL_Version } /** - * This macro turns the version numbers into a numeric value: - * \verbatim - (1,2,3) -> (0x1000203) - \endverbatim + * This macro turns the version numbers into a numeric value. + * + * (1,2,3) becomes 0x1000203. + * + * \param major the major version number. + * \param minor the minorversion number. + * \param patch the patch version number. + * + * \since This macro is available since SDL 3.0.0. */ -#define SDL_VERSIONNUM(X, Y, Z) \ - ((X) << 24 | (Y) << 8 | (Z) << 0) +#define SDL_VERSIONNUM(major, minor, patch) \ + ((major) << 24 | (minor) << 8 | (patch) << 0) /** * This is the version number macro for the current SDL version. + * + * \since This macro is available since SDL 3.0.0. */ #define SDL_COMPILEDVERSION \ 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. + * + * \since This macro is available since SDL 3.0.0. */ #define SDL_VERSION_ATLEAST(X, Y, Z) \ (SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z)) diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index 0be8e627d..770210e73 100644 --- a/include/SDL3/SDL_video.h +++ b/include/SDL3/SDL_video.h @@ -45,8 +45,8 @@ extern "C" { typedef Uint32 SDL_DisplayID; typedef Uint32 SDL_WindowID; -/** - * Global video properties +/* + * Global video properties. * * - `SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER`: the pointer to * the global `wl_display` object used by the Wayland video backend. Can be @@ -62,9 +62,11 @@ typedef Uint32 SDL_WindowID; #define SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER "SDL.video.wayland.wl_display" /** - * System theme + * System theme. + * + * \since This enum is available since SDL 3.0.0. */ -typedef enum +typedef enum SDL_SystemTheme { SDL_SYSTEM_THEME_UNKNOWN, /**< Unknown system theme */ SDL_SYSTEM_THEME_LIGHT, /**< Light colored system theme */ @@ -72,15 +74,17 @@ typedef enum } SDL_SystemTheme; /** - * The structure that defines a display mode + * The structure that defines a display mode. * - * \sa SDL_GetFullscreenDisplayModes() - * \sa SDL_GetDesktopDisplayMode() - * \sa SDL_GetCurrentDisplayMode() - * \sa SDL_SetWindowFullscreenMode() - * \sa SDL_GetWindowFullscreenMode() + * \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. */ -typedef struct +typedef struct SDL_DisplayMode { SDL_DisplayID displayID; /**< the display this mode is associated with */ SDL_PixelFormatEnum format; /**< pixel format */ @@ -92,9 +96,11 @@ typedef struct } SDL_DisplayMode; /** - * Display orientation + * Display orientation values; the way a display is rotated. + * + * \since This enum is available since SDL 3.0.0. */ -typedef enum +typedef enum SDL_DisplayOrientation { SDL_ORIENTATION_UNKNOWN, /**< The display orientation can't be determined */ SDL_ORIENTATION_LANDSCAPE, /**< The display is in landscape mode, with the right side up, relative to portrait mode */ @@ -104,14 +110,23 @@ typedef enum } SDL_DisplayOrientation; /** - * The type used to identify a window + * The struct used as an opaque handle to a window. + * + * \since This struct is available since SDL 3.0.0. + * + * \sa SDL_CreateWindow */ typedef struct SDL_Window SDL_Window; /** - * The flags on a window + * The flags on a window. * - * \sa SDL_GetWindowFlags + * These cover a lot of true/false, or on/off, window state. Some of it + * is immutable after being set through SDL_CreateWindow(), some of it can + * be changed on existing windows by the app, and some of it might be altered + * by the user or system outside of the app's control. + * + * \sa SDL_GetWindowFlags */ typedef Uint32 SDL_WindowFlags; @@ -158,9 +173,11 @@ typedef Uint32 SDL_WindowFlags; (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) /** - * Window flash operation + * Window flash operation. + * + * \since This enum is available since SDL 3.0.0. */ -typedef enum +typedef enum SDL_FlashOperation { SDL_FLASH_CANCEL, /**< Cancel any window flash state */ SDL_FLASH_BRIEFLY, /**< Flash the window briefly to get attention */ @@ -188,9 +205,15 @@ typedef SDL_EGLAttrib *(SDLCALL *SDL_EGLAttribArrayCallback)(void); typedef SDL_EGLint *(SDLCALL *SDL_EGLIntArrayCallback)(void); /** - * OpenGL configuration attributes + * 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(). + * + * 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. */ -typedef enum +typedef enum SDL_GLattr { SDL_GL_RED_SIZE, SDL_GL_GREEN_SIZE, @@ -222,14 +245,24 @@ typedef enum SDL_GL_EGL_PLATFORM } SDL_GLattr; -typedef enum +/** + * Possible values to be set for the SDL_GL_CONTEXT_PROFILE_MASK attribute. + * + * \since This enum is available since SDL 3.0.0. + */ +typedef enum SDL_GLprofile { SDL_GL_CONTEXT_PROFILE_CORE = 0x0001, SDL_GL_CONTEXT_PROFILE_COMPATIBILITY = 0x0002, SDL_GL_CONTEXT_PROFILE_ES = 0x0004 /**< GLX_CONTEXT_ES2_PROFILE_BIT_EXT */ } SDL_GLprofile; -typedef enum +/** + * Possible values to be set for the SDL_GL_CONTEXT_FLAGS attribute. + * + * \since This enum is available since SDL 3.0.0. + */ +typedef enum SDL_GLcontextFlag { SDL_GL_CONTEXT_DEBUG_FLAG = 0x0001, SDL_GL_CONTEXT_FORWARD_COMPATIBLE_FLAG = 0x0002, @@ -237,13 +270,23 @@ typedef enum SDL_GL_CONTEXT_RESET_ISOLATION_FLAG = 0x0008 } SDL_GLcontextFlag; -typedef enum +/** + * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR attribute. + * + * \since This enum is available since SDL 3.0.0. + */ +typedef enum SDL_GLcontextReleaseFlag { SDL_GL_CONTEXT_RELEASE_BEHAVIOR_NONE = 0x0000, SDL_GL_CONTEXT_RELEASE_BEHAVIOR_FLUSH = 0x0001 } SDL_GLcontextReleaseFlag; -typedef enum +/** + * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute. + * + * \since This enum is available since SDL 3.0.0. + */ +typedef enum SDL_GLContextResetNotification { SDL_GL_CONTEXT_RESET_NO_NOTIFICATION = 0x0000, SDL_GL_CONTEXT_RESET_LOSE_CONTEXT = 0x0001 @@ -292,7 +335,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index); extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void); /** - * Get the current system theme + * Get the current system theme. * * \returns the current system theme, light, dark, or unknown * @@ -2004,18 +2047,18 @@ extern DECLSPEC int SDLCALL SDL_ShowWindowSystemMenu(SDL_Window *window, int x, * * \sa SDL_HitTest */ -typedef enum +typedef enum SDL_HitTestResult { - SDL_HITTEST_NORMAL, /**< Region is normal. No special properties. */ - SDL_HITTEST_DRAGGABLE, /**< Region can drag entire window. */ - SDL_HITTEST_RESIZE_TOPLEFT, - SDL_HITTEST_RESIZE_TOP, - SDL_HITTEST_RESIZE_TOPRIGHT, - SDL_HITTEST_RESIZE_RIGHT, - SDL_HITTEST_RESIZE_BOTTOMRIGHT, - SDL_HITTEST_RESIZE_BOTTOM, - SDL_HITTEST_RESIZE_BOTTOMLEFT, - SDL_HITTEST_RESIZE_LEFT + SDL_HITTEST_NORMAL, /**< Region is normal. No special properties. */ + SDL_HITTEST_DRAGGABLE, /**< Region can drag entire window. */ + SDL_HITTEST_RESIZE_TOPLEFT, /**< Region is the resizable top-left corner border. */ + SDL_HITTEST_RESIZE_TOP, /**< Region is the resizable top border. */ + SDL_HITTEST_RESIZE_TOPRIGHT, /**< Region is the resizable top-right corner border. */ + SDL_HITTEST_RESIZE_RIGHT, /**< Region is the resizable right border. */ + SDL_HITTEST_RESIZE_BOTTOMRIGHT, /**< Region is the resizable bottom-right corner border. */ + SDL_HITTEST_RESIZE_BOTTOM, /**< Region is the resizable bottom border. */ + SDL_HITTEST_RESIZE_BOTTOMLEFT, /**< Region is the resizable bottom-left corner border. */ + SDL_HITTEST_RESIZE_LEFT /**< Region is the resizable left border. */ } SDL_HitTestResult; /** diff --git a/include/SDL3/SDL_vulkan.h b/include/SDL3/SDL_vulkan.h index 64e7349e4..aa08ec717 100644 --- a/include/SDL3/SDL_vulkan.h +++ b/include/SDL3/SDL_vulkan.h @@ -128,7 +128,7 @@ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path); extern DECLSPEC SDL_FunctionPointer SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void); /** - * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary() + * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary(). * * \since This function is available since SDL 3.0.0. * diff --git a/src/hidapi/SDL_hidapi.c b/src/hidapi/SDL_hidapi.c index 70ff84136..3b5fbbf18 100644 --- a/src/hidapi/SDL_hidapi.c +++ b/src/hidapi/SDL_hidapi.c @@ -998,7 +998,7 @@ static const struct hidapi_backend LIBUSB_Backend = { }; #endif /* HAVE_LIBUSB */ -struct SDL_hid_device_ +struct SDL_hid_device { const void *magic; void *device;