From 30f41c02aec763d32e62351452da9ef582bc3472 Mon Sep 17 00:00:00 2001 From: 3gg <3gg@shellblade.net> Date: Fri, 6 Mar 2026 13:30:59 -0800 Subject: Move contrib libraries to contrib repo --- contrib/SDL-3.2.8/include/SDL3/SDL_joystick.h | 1202 ------------------------- 1 file changed, 1202 deletions(-) delete mode 100644 contrib/SDL-3.2.8/include/SDL3/SDL_joystick.h (limited to 'contrib/SDL-3.2.8/include/SDL3/SDL_joystick.h') diff --git a/contrib/SDL-3.2.8/include/SDL3/SDL_joystick.h b/contrib/SDL-3.2.8/include/SDL3/SDL_joystick.h deleted file mode 100644 index d15668b..0000000 --- a/contrib/SDL-3.2.8/include/SDL3/SDL_joystick.h +++ /dev/null @@ -1,1202 +0,0 @@ -/* - Simple DirectMedia Layer - Copyright (C) 1997-2025 Sam Lantinga - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. -*/ - -/** - * # CategoryJoystick - * - * SDL joystick support. - * - * This is the lower-level joystick handling. If you want the simpler option, - * where what each button does is well-defined, you should use the gamepad API - * instead. - * - * The term "instance_id" is the current instantiation of a joystick device in - * the system, if the joystick is removed and then re-inserted then it will - * get a new instance_id, instance_id's are monotonically increasing - * identifiers of a joystick plugged in. - * - * The term "player_index" is the number assigned to a player on a specific - * controller. For XInput controllers this returns the XInput user index. Many - * joysticks will not be able to supply this information. - * - * SDL_GUID is used as a stable 128-bit identifier for a joystick device that - * does not change over time. It identifies class of the device (a X360 wired - * controller for example). This identifier is platform dependent. - * - * In order to use these functions, SDL_Init() must have been called with the - * SDL_INIT_JOYSTICK flag. This causes SDL to scan the system for joysticks, - * and load appropriate drivers. - * - * If you would like to receive joystick updates while the application is in - * the background, you should set the following hint before calling - * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS - */ - -#ifndef SDL_joystick_h_ -#define SDL_joystick_h_ - -#include -#include -#include -#include -#include -#include -#include - -#include -/* Set up for C function definitions, even when using C++ */ -#ifdef __cplusplus -extern "C" { -#endif - -#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 - -/** - * The joystick structure used to identify an SDL joystick. - * - * This is opaque data. - * - * \since This struct is available since SDL 3.2.0. - */ -typedef struct SDL_Joystick SDL_Joystick; - -/** - * This is a unique ID for a joystick for the time it is connected to the - * system, and is never reused for the lifetime of the application. - * - * If the joystick is disconnected and reconnected, it will get a new ID. - * - * The value 0 is an invalid ID. - * - * \since This datatype is available since SDL 3.2.0. - */ -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_GetJoystickTypeForID). - * - * 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.2.0. - */ -typedef enum SDL_JoystickType -{ - SDL_JOYSTICK_TYPE_UNKNOWN, - SDL_JOYSTICK_TYPE_GAMEPAD, - SDL_JOYSTICK_TYPE_WHEEL, - SDL_JOYSTICK_TYPE_ARCADE_STICK, - SDL_JOYSTICK_TYPE_FLIGHT_STICK, - SDL_JOYSTICK_TYPE_DANCE_PAD, - SDL_JOYSTICK_TYPE_GUITAR, - SDL_JOYSTICK_TYPE_DRUM_KIT, - SDL_JOYSTICK_TYPE_ARCADE_PAD, - SDL_JOYSTICK_TYPE_THROTTLE, - SDL_JOYSTICK_TYPE_COUNT -} 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.2.0. - */ -typedef enum SDL_JoystickConnectionState -{ - SDL_JOYSTICK_CONNECTION_INVALID = -1, - SDL_JOYSTICK_CONNECTION_UNKNOWN, - SDL_JOYSTICK_CONNECTION_WIRED, - SDL_JOYSTICK_CONNECTION_WIRELESS -} SDL_JoystickConnectionState; - -/** - * The largest value an SDL_Joystick's axis can report. - * - * \since This macro is available since SDL 3.2.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.2.0. - * - * \sa SDL_JOYSTICK_AXIS_MAX - */ -#define SDL_JOYSTICK_AXIS_MIN -32768 - - -/* Function prototypes */ - -/** - * 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 - * and joystick and gamepad events will not be delivered. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC void SDLCALL SDL_LockJoysticks(void) SDL_ACQUIRE(SDL_joystick_lock); - -/** - * Unlocking for atomic access to the joystick API. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC void SDLCALL SDL_UnlockJoysticks(void) SDL_RELEASE(SDL_joystick_lock); - -/** - * Return whether a joystick is currently connected. - * - * \returns true if a joystick is connected, false otherwise. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoysticks - */ -extern SDL_DECLSPEC bool SDLCALL SDL_HasJoystick(void); - -/** - * Get a list of currently connected joysticks. - * - * \param count a pointer filled in with the number of joysticks returned, may - * be NULL. - * \returns a 0 terminated array of joystick instance IDs or NULL on failure; - * call SDL_GetError() for more information. This should be freed - * with SDL_free() when it is no longer needed. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_HasJoystick - * \sa SDL_OpenJoystick - */ -extern SDL_DECLSPEC SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count); - -/** - * Get the implementation dependent name of a joystick. - * - * This can be called before any joysticks are opened. - * - * \param instance_id the joystick instance ID. - * \returns the name of the selected joystick. If no name can be found, this - * function returns NULL; call SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickName - * \sa SDL_GetJoysticks - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID instance_id); - -/** - * Get the implementation dependent path of a joystick. - * - * This can be called before any joysticks are opened. - * - * \param instance_id the joystick instance ID. - * \returns the path of the selected joystick. If no path can be found, this - * function returns NULL; call SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickPath - * \sa SDL_GetJoysticks - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPathForID(SDL_JoystickID instance_id); - -/** - * Get the player index of a joystick. - * - * This can be called before any joysticks are opened. - * - * \param instance_id the joystick instance ID. - * \returns the player index of a joystick, or -1 if it's not available. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickPlayerIndex - * \sa SDL_GetJoysticks - */ -extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndexForID(SDL_JoystickID instance_id); - -/** - * Get the implementation-dependent GUID of a joystick. - * - * This can be called before any joysticks are opened. - * - * \param instance_id the joystick instance ID. - * \returns the GUID of the selected joystick. If called with an invalid - * instance_id, this function returns a zero GUID. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickGUID - * \sa SDL_GUIDToString - */ -extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUIDForID(SDL_JoystickID instance_id); - -/** - * Get the USB vendor ID of a joystick, if available. - * - * This can be called before any joysticks are opened. If the vendor ID isn't - * available this function returns 0. - * - * \param instance_id the joystick instance ID. - * \returns the USB vendor ID of the selected joystick. If called with an - * invalid instance_id, this function returns 0. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickVendor - * \sa SDL_GetJoysticks - */ -extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendorForID(SDL_JoystickID instance_id); - -/** - * Get the USB product ID of a joystick, if available. - * - * This can be called before any joysticks are opened. If the product ID isn't - * available this function returns 0. - * - * \param instance_id the joystick instance ID. - * \returns the USB product ID of the selected joystick. If called with an - * invalid instance_id, this function returns 0. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickProduct - * \sa SDL_GetJoysticks - */ -extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductForID(SDL_JoystickID instance_id); - -/** - * Get the product version of a joystick, if available. - * - * This can be called before any joysticks are opened. If the product version - * isn't available this function returns 0. - * - * \param instance_id the joystick instance ID. - * \returns the product version of the selected joystick. If called with an - * invalid instance_id, this function returns 0. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickProductVersion - * \sa SDL_GetJoysticks - */ -extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersionForID(SDL_JoystickID instance_id); - -/** - * Get the type of a joystick, if available. - * - * This can be called before any joysticks are opened. - * - * \param instance_id the joystick instance ID. - * \returns the SDL_JoystickType of the selected joystick. If called with an - * invalid instance_id, this function returns - * `SDL_JOYSTICK_TYPE_UNKNOWN`. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickType - * \sa SDL_GetJoysticks - */ -extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_JoystickID instance_id); - -/** - * Open a joystick for use. - * - * The joystick subsystem must be initialized before a joystick can be opened - * for use. - * - * \param instance_id the joystick instance ID. - * \returns a joystick identifier or NULL on failure; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_CloseJoystick - */ -extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_OpenJoystick(SDL_JoystickID instance_id); - -/** - * Get the SDL_Joystick associated with an instance ID, if it has been opened. - * - * \param instance_id the instance ID to get the SDL_Joystick for. - * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been - * opened yet; call SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromID(SDL_JoystickID instance_id); - -/** - * Get the SDL_Joystick associated with a player index. - * - * \param player_index the player index to get the SDL_Joystick for. - * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickPlayerIndex - * \sa SDL_SetJoystickPlayerIndex - */ -extern SDL_DECLSPEC SDL_Joystick * SDLCALL SDL_GetJoystickFromPlayerIndex(int player_index); - -/** - * The structure that describes a virtual joystick touchpad. - * - * \since This struct is available since SDL 3.2.0. - * - * \sa SDL_VirtualJoystickDesc - */ -typedef struct SDL_VirtualJoystickTouchpadDesc -{ - Uint16 nfingers; /**< the number of simultaneous fingers on this touchpad */ - Uint16 padding[3]; -} SDL_VirtualJoystickTouchpadDesc; - -/** - * The structure that describes a virtual joystick sensor. - * - * \since This struct is available since SDL 3.2.0. - * - * \sa SDL_VirtualJoystickDesc - */ -typedef struct SDL_VirtualJoystickSensorDesc -{ - SDL_SensorType type; /**< the type of this sensor */ - float rate; /**< the update frequency of this sensor, may be 0.0f */ -} SDL_VirtualJoystickSensorDesc; - -/** - * The structure that describes a virtual joystick. - * - * This structure should be initialized using SDL_INIT_INTERFACE(). All - * elements of this structure are optional. - * - * \since This struct is available since SDL 3.2.0. - * - * \sa SDL_AttachVirtualJoystick - * \sa SDL_INIT_INTERFACE - * \sa SDL_VirtualJoystickSensorDesc - * \sa SDL_VirtualJoystickTouchpadDesc - */ -typedef struct SDL_VirtualJoystickDesc -{ - Uint32 version; /**< the version of this interface */ - Uint16 type; /**< `SDL_JoystickType` */ - Uint16 padding; /**< unused */ - Uint16 vendor_id; /**< the USB vendor ID of this joystick */ - Uint16 product_id; /**< the USB product ID of this joystick */ - Uint16 naxes; /**< the number of axes on this joystick */ - Uint16 nbuttons; /**< the number of buttons on this joystick */ - Uint16 nballs; /**< the number of balls on this joystick */ - Uint16 nhats; /**< the number of hats on this joystick */ - Uint16 ntouchpads; /**< the number of touchpads on this joystick, requires `touchpads` to point at valid descriptions */ - Uint16 nsensors; /**< the number of sensors on this joystick, requires `sensors` to point at valid descriptions */ - Uint16 padding2[2]; /**< unused */ - Uint32 button_mask; /**< A mask of which buttons are valid for this controller - e.g. (1 << SDL_GAMEPAD_BUTTON_SOUTH) */ - Uint32 axis_mask; /**< A mask of which axes are valid for this controller - e.g. (1 << SDL_GAMEPAD_AXIS_LEFTX) */ - const char *name; /**< the name of the joystick */ - const SDL_VirtualJoystickTouchpadDesc *touchpads; /**< A pointer to an array of touchpad descriptions, required if `ntouchpads` is > 0 */ - const SDL_VirtualJoystickSensorDesc *sensors; /**< A pointer to an array of sensor descriptions, required if `nsensors` is > 0 */ - - void *userdata; /**< User data pointer passed to callbacks */ - void (SDLCALL *Update)(void *userdata); /**< Called when the joystick state should be updated */ - void (SDLCALL *SetPlayerIndex)(void *userdata, int player_index); /**< Called when the player index is set */ - bool (SDLCALL *Rumble)(void *userdata, Uint16 low_frequency_rumble, Uint16 high_frequency_rumble); /**< Implements SDL_RumbleJoystick() */ - bool (SDLCALL *RumbleTriggers)(void *userdata, Uint16 left_rumble, Uint16 right_rumble); /**< Implements SDL_RumbleJoystickTriggers() */ - bool (SDLCALL *SetLED)(void *userdata, Uint8 red, Uint8 green, Uint8 blue); /**< Implements SDL_SetJoystickLED() */ - bool (SDLCALL *SendEffect)(void *userdata, const void *data, int size); /**< Implements SDL_SendJoystickEffect() */ - bool (SDLCALL *SetSensorsEnabled)(void *userdata, bool enabled); /**< Implements SDL_SetGamepadSensorEnabled() */ - void (SDLCALL *Cleanup)(void *userdata); /**< Cleans up the userdata when the joystick is detached */ -} SDL_VirtualJoystickDesc; - -/* Check the size of SDL_VirtualJoystickDesc - * - * If this assert fails, either the compiler is padding to an unexpected size, - * or the interface has been updated and this should be updated to match and - * the code using this interface should be updated to handle the old version. - */ -SDL_COMPILE_TIME_ASSERT(SDL_VirtualJoystickDesc_SIZE, - (sizeof(void *) == 4 && sizeof(SDL_VirtualJoystickDesc) == 84) || - (sizeof(void *) == 8 && sizeof(SDL_VirtualJoystickDesc) == 136)); - -/** - * Attach a new virtual joystick. - * - * \param desc joystick description, initialized using SDL_INIT_INTERFACE(). - * \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for - * more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_DetachVirtualJoystick - */ -extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystick(const SDL_VirtualJoystickDesc *desc); - -/** - * Detach a virtual joystick. - * - * \param instance_id the joystick instance ID, previously returned from - * SDL_AttachVirtualJoystick(). - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_AttachVirtualJoystick - */ -extern SDL_DECLSPEC bool SDLCALL SDL_DetachVirtualJoystick(SDL_JoystickID instance_id); - -/** - * Query whether or not a joystick is virtual. - * - * \param instance_id the joystick instance ID. - * \returns true if the joystick is virtual, false otherwise. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_id); - -/** - * Set the state of an axis on an opened virtual joystick. - * - * Please note that values set here will not be applied until the next call to - * SDL_UpdateJoysticks, which can either be called directly, or can be called - * indirectly through various other SDL APIs, including, but not limited to - * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, - * SDL_WaitEvent. - * - * Note that when sending trigger axes, you should scale the value to the full - * range of Sint16. For example, a trigger at rest would have the value of - * `SDL_JOYSTICK_AXIS_MIN`. - * - * \param joystick the virtual joystick on which to set state. - * \param axis the index of the axis on the virtual joystick to update. - * \param value the new value for the specified axis. - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, int axis, Sint16 value); - -/** - * Generate ball motion on an opened virtual joystick. - * - * Please note that values set here will not be applied until the next call to - * SDL_UpdateJoysticks, which can either be called directly, or can be called - * indirectly through various other SDL APIs, including, but not limited to - * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, - * SDL_WaitEvent. - * - * \param joystick the virtual joystick on which to set state. - * \param ball the index of the ball on the virtual joystick to update. - * \param xrel the relative motion on the X axis. - * \param yrel the relative motion on the Y axis. - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualBall(SDL_Joystick *joystick, int ball, Sint16 xrel, Sint16 yrel); - -/** - * Set the state of a button on an opened virtual joystick. - * - * Please note that values set here will not be applied until the next call to - * SDL_UpdateJoysticks, which can either be called directly, or can be called - * indirectly through various other SDL APIs, including, but not limited to - * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, - * SDL_WaitEvent. - * - * \param joystick the virtual joystick on which to set state. - * \param button the index of the button on the virtual joystick to update. - * \param down true if the button is pressed, false otherwise. - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick, int button, bool down); - -/** - * Set the state of a hat on an opened virtual joystick. - * - * Please note that values set here will not be applied until the next call to - * SDL_UpdateJoysticks, which can either be called directly, or can be called - * indirectly through various other SDL APIs, including, but not limited to - * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, - * SDL_WaitEvent. - * - * \param joystick the virtual joystick on which to set state. - * \param hat the index of the hat on the virtual joystick to update. - * \param value the new value for the specified hat. - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualHat(SDL_Joystick *joystick, int hat, Uint8 value); - -/** - * Set touchpad finger state on an opened virtual joystick. - * - * Please note that values set here will not be applied until the next call to - * SDL_UpdateJoysticks, which can either be called directly, or can be called - * indirectly through various other SDL APIs, including, but not limited to - * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, - * SDL_WaitEvent. - * - * \param joystick the virtual joystick on which to set state. - * \param touchpad the index of the touchpad on the virtual joystick to - * update. - * \param finger the index of the finger on the touchpad to set. - * \param down true if the finger is pressed, false if the finger is released. - * \param x the x coordinate of the finger on the touchpad, normalized 0 to 1, - * with the origin in the upper left. - * \param y the y coordinate of the finger on the touchpad, normalized 0 to 1, - * with the origin in the upper left. - * \param pressure the pressure of the finger. - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickVirtualTouchpad(SDL_Joystick *joystick, int touchpad, int finger, bool down, float x, float y, float pressure); - -/** - * Send a sensor update for an opened virtual joystick. - * - * Please note that values set here will not be applied until the next call to - * SDL_UpdateJoysticks, which can either be called directly, or can be called - * indirectly through various other SDL APIs, including, but not limited to - * the following: SDL_PollEvent, SDL_PumpEvents, SDL_WaitEventTimeout, - * SDL_WaitEvent. - * - * \param joystick the virtual joystick on which to set state. - * \param type the type of the sensor on the virtual joystick to update. - * \param sensor_timestamp a 64-bit timestamp in nanoseconds associated with - * the sensor reading. - * \param data the data associated with the sensor reading. - * \param num_values the number of values pointed to by `data`. - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickVirtualSensorData(SDL_Joystick *joystick, SDL_SensorType type, Uint64 sensor_timestamp, const float *data, int num_values); - -/** - * Get the properties associated with a joystick. - * - * The following read-only properties are provided by SDL: - * - * - `SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN`: true if this joystick has an - * LED that has adjustable brightness - * - `SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN`: true if this joystick has an LED - * that has adjustable color - * - `SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN`: true if this joystick has a - * player LED - * - `SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN`: true if this joystick has - * left/right rumble - * - `SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN`: true if this joystick has - * simple trigger rumble - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \returns a valid property ID on success or 0 on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joystick *joystick); - -#define SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN "SDL.joystick.cap.mono_led" -#define SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN "SDL.joystick.cap.rgb_led" -#define SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN "SDL.joystick.cap.player_led" -#define SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN "SDL.joystick.cap.rumble" -#define SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN "SDL.joystick.cap.trigger_rumble" - -/** - * Get the implementation dependent name of a joystick. - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \returns the name of the selected joystick. If no name can be found, this - * function returns NULL; call SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickNameForID - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joystick); - -/** - * Get the implementation dependent path of a joystick. - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \returns the path of the selected joystick. If no path can be found, this - * function returns NULL; call SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickPathForID - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickPath(SDL_Joystick *joystick); - -/** - * Get the player index of an opened joystick. - * - * For XInput controllers this returns the XInput user index. Many joysticks - * will not be able to supply this information. - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \returns the player index, or -1 if it's not available. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_SetJoystickPlayerIndex - */ -extern SDL_DECLSPEC int SDLCALL SDL_GetJoystickPlayerIndex(SDL_Joystick *joystick); - -/** - * Set the player index of an opened joystick. - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \param player_index player index to assign to this joystick, or -1 to clear - * the player index and turn off player LEDs. - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickPlayerIndex - */ -extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickPlayerIndex(SDL_Joystick *joystick, int player_index); - -/** - * Get the implementation-dependent GUID for the joystick. - * - * This function requires an open joystick. - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \returns the GUID of the given joystick. If called on an invalid index, - * this function returns a zero GUID; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickGUIDForID - * \sa SDL_GUIDToString - */ -extern SDL_DECLSPEC SDL_GUID SDLCALL SDL_GetJoystickGUID(SDL_Joystick *joystick); - -/** - * Get the USB vendor ID of an opened joystick, if available. - * - * If the vendor ID isn't available this function returns 0. - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickVendorForID - */ -extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickVendor(SDL_Joystick *joystick); - -/** - * Get the USB product ID of an opened joystick, if available. - * - * If the product ID isn't available this function returns 0. - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \returns the USB product ID of the selected joystick, or 0 if unavailable. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickProductForID - */ -extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProduct(SDL_Joystick *joystick); - -/** - * Get the product version of an opened joystick, if available. - * - * If the product version isn't available this function returns 0. - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \returns the product version of the selected joystick, or 0 if unavailable. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickProductVersionForID - */ -extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickProductVersion(SDL_Joystick *joystick); - -/** - * Get the firmware version of an opened joystick, if available. - * - * If the firmware version isn't available this function returns 0. - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \returns the firmware version of the selected joystick, or 0 if - * unavailable. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick *joystick); - -/** - * Get the serial number of an opened joystick, if available. - * - * Returns the serial number of the joystick, or NULL if it is not available. - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \returns the serial number of the selected joystick, or NULL if - * unavailable. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickSerial(SDL_Joystick *joystick); - -/** - * Get the type of an opened joystick. - * - * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). - * \returns the SDL_JoystickType of the selected joystick. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickTypeForID - */ -extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *joystick); - -/** - * Get the device information encoded in a SDL_GUID structure. - * - * \param guid the SDL_GUID you wish to get info about. - * \param vendor a pointer filled in with the device VID, or 0 if not - * available. - * \param product a pointer filled in with the device PID, or 0 if not - * available. - * \param version a pointer filled in with the device version, or 0 if not - * available. - * \param crc16 a pointer filled in with a CRC used to distinguish different - * products with the same VID/PID, or 0 if not available. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickGUIDForID - */ -extern SDL_DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_GUID guid, Uint16 *vendor, Uint16 *product, Uint16 *version, Uint16 *crc16); - -/** - * Get the status of a specified joystick. - * - * \param joystick the joystick to query. - * \returns true if the joystick has been opened, false if it has not; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool SDLCALL SDL_JoystickConnected(SDL_Joystick *joystick); - -/** - * Get the instance ID of an opened joystick. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the instance ID of the specified joystick on success or 0 on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetJoystickID(SDL_Joystick *joystick); - -/** - * Get the number of general axis controls on a joystick. - * - * Often, the directional pad on a game controller will either look like 4 - * separate buttons or a POV hat, and not axes, but all of this is up to the - * device and platform. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of axis controls/number of axes on success or -1 on - * failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickAxis - * \sa SDL_GetNumJoystickBalls - * \sa SDL_GetNumJoystickButtons - * \sa SDL_GetNumJoystickHats - */ -extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickAxes(SDL_Joystick *joystick); - -/** - * Get the number of trackballs on a joystick. - * - * Joystick trackballs have only relative motion events associated with them - * and their state cannot be polled. - * - * Most joysticks do not have trackballs. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of trackballs on success or -1 on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickBall - * \sa SDL_GetNumJoystickAxes - * \sa SDL_GetNumJoystickButtons - * \sa SDL_GetNumJoystickHats - */ -extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickBalls(SDL_Joystick *joystick); - -/** - * Get the number of POV hats on a joystick. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of POV hats on success or -1 on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickHat - * \sa SDL_GetNumJoystickAxes - * \sa SDL_GetNumJoystickBalls - * \sa SDL_GetNumJoystickButtons - */ -extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickHats(SDL_Joystick *joystick); - -/** - * Get the number of buttons on a joystick. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \returns the number of buttons on success or -1 on failure; call - * SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetJoystickButton - * \sa SDL_GetNumJoystickAxes - * \sa SDL_GetNumJoystickBalls - * \sa SDL_GetNumJoystickHats - */ -extern SDL_DECLSPEC int SDLCALL SDL_GetNumJoystickButtons(SDL_Joystick *joystick); - -/** - * Set the state of joystick event processing. - * - * If joystick events are disabled, you must call SDL_UpdateJoysticks() - * yourself and check the state of the joystick when you want joystick - * information. - * - * \param enabled whether to process joystick events or not. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_JoystickEventsEnabled - * \sa SDL_UpdateJoysticks - */ -extern SDL_DECLSPEC void SDLCALL SDL_SetJoystickEventsEnabled(bool enabled); - -/** - * Query the state of joystick event processing. - * - * If joystick events are disabled, you must call SDL_UpdateJoysticks() - * yourself and check the state of the joystick when you want joystick - * information. - * - * \returns true if joystick events are being processed, false otherwise. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_SetJoystickEventsEnabled - */ -extern SDL_DECLSPEC bool SDLCALL SDL_JoystickEventsEnabled(void); - -/** - * Update the current state of the open joysticks. - * - * This is called automatically by the event loop if any joystick events are - * enabled. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC void SDLCALL SDL_UpdateJoysticks(void); - -/** - * Get the current state of an axis control on a joystick. - * - * SDL makes no promises about what part of the joystick any given axis refers - * to. Your game should have some sort of configuration UI to let users - * specify what each axis should be bound to. Alternately, SDL's higher-level - * Game Controller API makes a great effort to apply order to this lower-level - * interface, so you know that a specific axis is the "left thumb stick," etc. - * - * The value returned by SDL_GetJoystickAxis() is a signed integer (-32768 to - * 32767) representing the current position of the axis. It may be necessary - * to impose certain tolerances on these values to account for jitter. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \param axis the axis to query; the axis indices start at index 0. - * \returns a 16-bit signed integer representing the current position of the - * axis or 0 on failure; call SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetNumJoystickAxes - */ -extern SDL_DECLSPEC Sint16 SDLCALL SDL_GetJoystickAxis(SDL_Joystick *joystick, int axis); - -/** - * Get the initial state of an axis control on a joystick. - * - * The state is a value ranging from -32768 to 32767. - * - * The axis indices start at index 0. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \param axis the axis to query; the axis indices start at index 0. - * \param state upon return, the initial value is supplied here. - * \returns true if this axis has any initial value, or false if not. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickAxisInitialState(SDL_Joystick *joystick, int axis, Sint16 *state); - -/** - * Get the ball axis change since the last poll. - * - * Trackballs can only return relative motion since the last call to - * SDL_GetJoystickBall(), these motion deltas are placed into `dx` and `dy`. - * - * Most joysticks do not have trackballs. - * - * \param joystick the SDL_Joystick to query. - * \param ball the ball index to query; ball indices start at index 0. - * \param dx stores the difference in the x axis position since the last poll. - * \param dy stores the difference in the y axis position since the last poll. - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetNumJoystickBalls - */ -extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickBall(SDL_Joystick *joystick, int ball, int *dx, int *dy); - -/** - * Get the current state of a POV hat on a joystick. - * - * 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. - * \returns the current hat position. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetNumJoystickHats - */ -extern SDL_DECLSPEC Uint8 SDLCALL SDL_GetJoystickHat(SDL_Joystick *joystick, int hat); - -#define SDL_HAT_CENTERED 0x00u -#define SDL_HAT_UP 0x01u -#define SDL_HAT_RIGHT 0x02u -#define SDL_HAT_DOWN 0x04u -#define SDL_HAT_LEFT 0x08u -#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. - * - * \param joystick an SDL_Joystick structure containing joystick information. - * \param button the button index to get the state from; indices start at - * index 0. - * \returns true if the button is pressed, false otherwise. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_GetNumJoystickButtons - */ -extern SDL_DECLSPEC bool SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick, int button); - -/** - * Start a rumble effect. - * - * Each call to this function cancels any previous rumble effect, and calling - * it with 0 intensity stops any rumbling. - * - * This function requires you to process SDL events or call - * SDL_UpdateJoysticks() to update rumble state. - * - * \param joystick the joystick to vibrate. - * \param low_frequency_rumble the intensity of the low frequency (left) - * rumble motor, from 0 to 0xFFFF. - * \param high_frequency_rumble the intensity of the high frequency (right) - * rumble motor, from 0 to 0xFFFF. - * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns true, or false if rumble isn't supported on this joystick. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool 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. - * - * Each call to this function cancels any previous trigger rumble effect, and - * calling it with 0 intensity stops any rumbling. - * - * Note that this is rumbling of the _triggers_ and not the game controller as - * a whole. This is currently only supported on Xbox One controllers. If you - * want the (more common) whole-controller rumble, use SDL_RumbleJoystick() - * instead. - * - * This function requires you to process SDL events or call - * SDL_UpdateJoysticks() to update rumble state. - * - * \param joystick the joystick to vibrate. - * \param left_rumble the intensity of the left trigger rumble motor, from 0 - * to 0xFFFF. - * \param right_rumble the intensity of the right trigger rumble motor, from 0 - * to 0xFFFF. - * \param duration_ms the duration of the rumble effect, in milliseconds. - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_RumbleJoystick - */ -extern SDL_DECLSPEC bool SDLCALL SDL_RumbleJoystickTriggers(SDL_Joystick *joystick, Uint16 left_rumble, Uint16 right_rumble, Uint32 duration_ms); - -/** - * Update a joystick's LED color. - * - * An example of a joystick LED is the light on the back of a PlayStation 4's - * DualShock 4 controller. - * - * For joysticks with a single color LED, the maximum of the RGB values will - * be used as the LED brightness. - * - * \param joystick the joystick to update. - * \param red the intensity of the red LED. - * \param green the intensity of the green LED. - * \param blue the intensity of the blue LED. - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red, Uint8 green, Uint8 blue); - -/** - * Send a joystick specific effect packet. - * - * \param joystick the joystick to affect. - * \param data the data to send to the joystick. - * \param size the size of the data to send to the joystick. - * \returns true on success or false on failure; call SDL_GetError() for more - * information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC bool SDLCALL SDL_SendJoystickEffect(SDL_Joystick *joystick, const void *data, int size); - -/** - * Close a joystick previously opened with SDL_OpenJoystick(). - * - * \param joystick the joystick device to close. - * - * \since This function is available since SDL 3.2.0. - * - * \sa SDL_OpenJoystick - */ -extern SDL_DECLSPEC void SDLCALL SDL_CloseJoystick(SDL_Joystick *joystick); - -/** - * Get the connection state of a joystick. - * - * \param joystick the joystick to query. - * \returns the connection state on success or - * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() - * for more information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC SDL_JoystickConnectionState SDLCALL SDL_GetJoystickConnectionState(SDL_Joystick *joystick); - -/** - * Get the battery state of a joystick. - * - * You should never take a battery status as absolute truth. Batteries - * (especially failing batteries) are delicate hardware, and the values - * reported here are best estimates based on what that hardware reports. It's - * not uncommon for older batteries to lose stored power much faster than it - * reports, or completely drain when reporting it has 20 percent left, etc. - * - * \param joystick the joystick to query. - * \param percent a pointer filled in with the percentage of battery life - * left, between 0 and 100, or NULL to ignore. This will be - * filled in with -1 we can't determine a value or there is no - * battery. - * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; - * call SDL_GetError() for more information. - * - * \since This function is available since SDL 3.2.0. - */ -extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetJoystickPowerInfo(SDL_Joystick *joystick, int *percent); - -/* Ends C function definitions when using C++ */ -#ifdef __cplusplus -} -#endif -#include - -#endif /* SDL_joystick_h_ */ -- cgit v1.2.3