diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h index 0364aabf16..e5343c8aee 100644 --- a/include/SDL3/SDL_gamepad.h +++ b/include/SDL3/SDL_gamepad.h @@ -58,9 +58,18 @@ extern "C" { * * \since This struct is available since SDL 3.0.0. */ -struct SDL_Gamepad; typedef struct SDL_Gamepad SDL_Gamepad; +/** + * Standard gamepad types. + * + * This type does not necessarily map to first-party controllers + * from Microsoft/Sony/Nintendo; in many cases, third-party controllers + * can report as these, either because they were designed for a + * specific console, or they simply most closely match that console's + * controllers (does it have A/B/X/Y buttons or X/O/Square/Triangle? + * Does it have a touchpad? etc). + */ typedef enum SDL_GamepadType { SDL_GAMEPAD_TYPE_UNKNOWN = 0, @@ -182,6 +191,16 @@ typedef enum SDL_GamepadAxis SDL_GAMEPAD_AXIS_MAX } SDL_GamepadAxis; +/** + * Types of gamepad control bindings. + * + * A gamepad is a collection of bindings that map arbitrary joystick + * buttons, axes and hat switches to specific positions on a generic + * console-style gamepad. This enum is used as part of SDL_GamepadBinding + * to specify those mappings. + * + * \since This enum is available since SDL 3.0.0. + */ typedef enum SDL_GamepadBindingType { SDL_GAMEPAD_BINDTYPE_NONE = 0, @@ -190,6 +209,22 @@ typedef enum SDL_GamepadBindingType SDL_GAMEPAD_BINDTYPE_HAT } SDL_GamepadBindingType; +/** + * A mapping between one joystick input to a gamepad control. + * + * A gamepad has a collection of several bindings, to say, for + * example, when joystick button number 5 is pressed, that should + * be treated like the gamepad's "start" button. + * + * SDL has these bindings built-in for many popular controllers, + * and can add more with a simple text string. Those strings are + * parsed into a collection of these structs to make it easier + * to operate on the data. + * + * \since This struct is available since SDL 3.0.0. + * + * \sa SDL_GetGamepadBindings + */ typedef struct SDL_GamepadBinding { SDL_GamepadBindingType input_type; @@ -225,7 +260,6 @@ typedef struct SDL_GamepadBinding } axis; } output; - } SDL_GamepadBinding; diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h index 69fa802e14..62f495df56 100644 --- a/include/SDL3/SDL_joystick.h +++ b/include/SDL3/SDL_joystick.h @@ -63,16 +63,31 @@ extern "C" { * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS */ -/** - * The joystick structure used to identify an SDL joystick - */ #ifdef SDL_THREAD_SAFETY_ANALYSIS +/* + * This is not an exported symbol from SDL, this is only in the headers to + * help Clang's thread safety analysis tools to function. Do not attempt + * to access this symbol from your app, it will not work! + */ extern SDL_Mutex *SDL_joystick_lock; #endif -struct SDL_Joystick; + +/** + * The joystick structure used to identify an SDL joystick. + * + * This is opaque data. + * + * \since This struct is available since SDL 3.0.0. + */ typedef struct SDL_Joystick SDL_Joystick; -/* A structure that encodes the stable unique id for a joystick device */ +/** + * A structure that encodes the stable unique id for a joystick device. + * + * This is just a standard SDL_GUID by a different name. + * + * \since This datatype is available since SDL 3.0.0. + */ typedef SDL_GUID SDL_JoystickGUID; /** @@ -88,6 +103,18 @@ typedef SDL_GUID SDL_JoystickGUID; */ typedef Uint32 SDL_JoystickID; +/** + * An enum of some common joystick types. + * + * In some cases, SDL can identify a low-level joystick as being a certain + * type of device, and will report it through SDL_GetJoystickType (or + * SDL_GetJoystickInstanceType). + * + * This is by no means a complete list of everything that can be plugged + * into a computer. + * + * \since This enum is available since SDL 3.0.0. + */ typedef enum SDL_JoystickType { SDL_JOYSTICK_TYPE_UNKNOWN, @@ -102,6 +129,14 @@ typedef enum SDL_JoystickType SDL_JOYSTICK_TYPE_THROTTLE } SDL_JoystickType; +/** + * Possible connection states for a joystick device. + * + * This is used by SDL_GetJoystickConnectionState to report how a device + * is connected to the system. + * + * \since This enum is available since SDL 3.0.0. + */ typedef enum SDL_JoystickConnectionState { SDL_JOYSTICK_CONNECTION_INVALID = -1, @@ -110,9 +145,27 @@ typedef enum SDL_JoystickConnectionState SDL_JOYSTICK_CONNECTION_WIRELESS } SDL_JoystickConnectionState; +/** + * The largest value an SDL_Joystick's axis can report. + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_JOYSTICK_AXIS_MIN + */ #define SDL_JOYSTICK_AXIS_MAX 32767 + +/** + * The smallest value an SDL_Joystick's axis can report. + * + * This is a negative number! + * + * \since This macro is available since SDL 3.0.0. + * + * \sa SDL_JOYSTICK_AXIS_MAX + */ #define SDL_JOYSTICK_AXIS_MIN -32768 + /* Set max recognized G-force from accelerometer See src/joystick/uikit/SDL_sysjoystick.m for notes on why this is needed */ @@ -929,35 +982,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *j */ extern DECLSPEC int SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); -/** - * \name Hat positions - */ -/* @{ */ -#define SDL_HAT_CENTERED 0x00 -#define SDL_HAT_UP 0x01 -#define SDL_HAT_RIGHT 0x02 -#define SDL_HAT_DOWN 0x04 -#define SDL_HAT_LEFT 0x08 -#define SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP) -#define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN) -#define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP) -#define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN) -/* @} */ - /** * Get the current state of a POV hat on a joystick. * - * The returned value will be one of the following positions: - * - * - `SDL_HAT_CENTERED` - * - `SDL_HAT_UP` - * - `SDL_HAT_RIGHT` - * - `SDL_HAT_DOWN` - * - `SDL_HAT_LEFT` - * - `SDL_HAT_RIGHTUP` - * - `SDL_HAT_RIGHTDOWN` - * - `SDL_HAT_LEFTUP` - * - `SDL_HAT_LEFTDOWN` + * The returned value will be one of the `SDL_HAT_*` values. * * \param joystick an SDL_Joystick structure containing joystick information * \param hat the hat index to get the state from; indices start at index 0 @@ -969,6 +997,16 @@ extern DECLSPEC int SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball */ extern DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int hat); +#define SDL_HAT_CENTERED 0x00 +#define SDL_HAT_UP 0x01 +#define SDL_HAT_RIGHT 0x02 +#define SDL_HAT_DOWN 0x04 +#define SDL_HAT_LEFT 0x08 +#define SDL_HAT_RIGHTUP (SDL_HAT_RIGHT|SDL_HAT_UP) +#define SDL_HAT_RIGHTDOWN (SDL_HAT_RIGHT|SDL_HAT_DOWN) +#define SDL_HAT_LEFTUP (SDL_HAT_LEFT|SDL_HAT_UP) +#define SDL_HAT_LEFTDOWN (SDL_HAT_LEFT|SDL_HAT_DOWN) + /** * Get the current state of a button on a joystick. * diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h index c159a62166..d221ebf00a 100644 --- a/include/SDL3/SDL_keyboard.h +++ b/include/SDL3/SDL_keyboard.h @@ -39,6 +39,17 @@ extern "C" { #endif +/** + * This is a unique ID for a keyboard for the time it is connected to the + * system, and is never reused for the lifetime of the application. + * + * If the keyboard is disconnected and reconnected, it will get a new ID. + * + * The ID value starts at 1 and increments from there. The value 0 is an + * invalid ID. + * + * \since This datatype is available since SDL 3.0.0. + */ typedef Uint32 SDL_KeyboardID; /** diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h index c189af6372..7921c48837 100644 --- a/include/SDL3/SDL_mutex.h +++ b/include/SDL3/SDL_mutex.h @@ -116,8 +116,9 @@ extern "C" { #endif /** - * Synchronization functions which can time out return this value if they time - * out. + * Synchronization functions return this value if they time out. + * + * Not all functions _can_ time out; some will block indefinitely. * * \since This macro is available since SDL 3.0.0. */ @@ -129,8 +130,18 @@ extern "C" { */ /* @{ */ -/* The SDL mutex structure, defined in SDL_sysmutex.c */ -struct SDL_Mutex; +/** + * A means to serialize access to a resource between threads. + * + * Mutexes (short for "mutual exclusion") are a synchronization primitive + * that allows exactly one thread to proceed at a time. + * + * Wikipedia has a thorough explanation of the concept: + * + * https://en.wikipedia.org/wiki/Mutex + * + * \since This struct is available since SDL 3.0.0. + */ typedef struct SDL_Mutex SDL_Mutex; /** @@ -247,13 +258,37 @@ extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_Mutex *mutex); */ /* @{ */ -/* The SDL read/write lock structure, defined in SDL_sysrwlock.c */ -struct SDL_RWLock; +/** + * A mutex that allows read-only threads to run in parallel. + * + * A rwlock is roughly the same concept as SDL_Mutex, but allows + * threads that request read-only access to all hold the lock at + * the same time. If a thread requests write access, it will block + * until all read-only threads have released the lock, and no one + * else can hold the thread (for reading or writing) at the same + * time as the writing thread. + * + * This can be more efficient in cases where several threads need + * to access data frequently, but changes to that data are rare. + * + * There are other rules that apply to rwlocks that don't apply + * to mutexes, about how threads are scheduled and when they can + * be recursively locked. These are documented in the other rwlock + * functions. + * + * \since This struct is available since SDL 3.0.0. + */ typedef struct SDL_RWLock SDL_RWLock; /* - * Synchronization functions which can time out return this value - * if they time out. + * Synchronization functions return this value if they time out. + * + * Not all functions _can_ time out; some will block indefinitely. + * + * This symbol is just for clarity when dealing with SDL_RWLock + * functions; its value is equivalent to SDL_MUTEX_TIMEOUT. + * + * \since This macro is available since SDL 3.0.0. */ #define SDL_RWLOCK_TIMEDOUT SDL_MUTEX_TIMEDOUT @@ -479,8 +514,21 @@ extern DECLSPEC void SDLCALL SDL_DestroyRWLock(SDL_RWLock *rwlock); */ /* @{ */ -/* The SDL semaphore structure, defined in SDL_syssem.c */ -struct SDL_Semaphore; +/** + * A means to manage access to a resource, by count, between threads. + * + * Semaphores (specifically, "counting semaphores"), let X number of + * threads request access at the same time, each thread granted access + * decrementing a counter. When the counter reaches zero, future requests + * block until a prior thread releases their request, incrementing the + * counter again. + * + * Wikipedia has a thorough explanation of the concept: + * + * https://en.wikipedia.org/wiki/Semaphore_(programming) + * + * \since This struct is available since SDL 3.0.0. + */ typedef struct SDL_Semaphore SDL_Semaphore; /** @@ -620,8 +668,19 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); */ /* @{ */ -/* The SDL condition variable structure, defined in SDL_syscond.c */ -struct SDL_Condition; +/** + * A means to block multiple threads until a condition is satisfied. + * + * Condition variables, paired with an SDL_Mutex, let an app + * halt multiple threads until a condition has occurred, at which + * time the app can release one or all waiting threads. + * + * Wikipedia has a thorough explanation of the concept: + * + * https://en.wikipedia.org/wiki/Condition_variable + * + * \since This struct is available since SDL 3.0.0. + */ typedef struct SDL_Condition SDL_Condition; /** diff --git a/include/SDL3/SDL_storage.h b/include/SDL3/SDL_storage.h index 313f555d0a..0c4b4c0d30 100644 --- a/include/SDL3/SDL_storage.h +++ b/include/SDL3/SDL_storage.h @@ -42,6 +42,19 @@ extern "C" { /* !!! FIXME: Don't let this ship without async R/W support!!! */ +/** + * Function interface for SDL_Storage. + * + * Apps that want to supply a custom implementation of SDL_Storage + * will fill in all the functions in this struct, and then pass it to + * SDL_OpenStorage to create a custom SDL_Storage object. + * + * It is not usually necessary to do this; SDL provides standard + * implementations for many things you might expect to do with + * an SDL_Storage. + * + * \since This struct is available since SDL 3.0.0. + */ typedef struct SDL_StorageInterface { /* Called when the storage is closed */ @@ -73,9 +86,18 @@ typedef struct SDL_StorageInterface /* Get the space remaining, optional for read-only storage */ Uint64 (SDLCALL *space_remaining)(void *userdata); - } SDL_StorageInterface; +/** + * An abstract interface for filesystem access. + * + * This is an opaque datatype. One can create this object + * using standard SDL functions like SDL_OpenTitleStorage or + * SDL_OpenUserStorage, etc, or create an object with a custom + * implementation using SDL_OpenStorage. + * + * \since This struct is available since SDL 3.0.0. + */ typedef struct SDL_Storage SDL_Storage; /**