mirror of https://github.com/libsdl-org/SDL.git
include: Filled in some missing documentation.
This commit is contained in:
Ryan C. Gordon
parent
1c6ba2a9ab
commit
760d7d276b
|
|
@ -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;
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
*
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
/**
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
/**
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
/**
|
||||
|
|
|
|||
Loading…
Reference in New Issue