foo_out_sdl: SDL3/SDL_joystick.h comparison

comparison SDL3/SDL_joystick.h @ 1:20d02a178406 default tip

*: check in everything else yay

author	Paper <paper@tflc.us>
date	Mon, 05 Jan 2026 02:15:46 -0500
parents
children

comparison

equal deleted inserted replaced

-:e9bb126753e7
+:20d02a178406
+/*
+Simple DirectMedia Layer
+Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
+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
+*
+* SDL can provide virtual joysticks as well: the app defines an imaginary
+* controller with SDL_AttachVirtualJoystick(), and then can provide inputs
+* for it via SDL_SetJoystickVirtualAxis(), SDL_SetJoystickVirtualButton(),
+* etc. As this data is supplied, it will look like a normal joystick to SDL,
+* just not backed by a hardware driver. This has been used to make unusual
+* devices, like VR headset controllers, look like normal joysticks, or
+* provide recording/playback of game inputs, etc.
+*/
+#ifndef SDL_joystick_h_
+#define SDL_joystick_h_
+#include <SDL3/SDL_stdinc.h>
+#include <SDL3/SDL_error.h>
+#include <SDL3/SDL_guid.h>
+#include <SDL3/SDL_mutex.h>
+#include <SDL3/SDL_power.h>
+#include <SDL3/SDL_properties.h>
+#include <SDL3/SDL_sensor.h>
+#include <SDL3/SDL_begin_code.h>
+/* 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.
+*
+* You may refer to
+* [XInput Controller Types](https://learn.microsoft.com/en-us/windows/win32/xinput/xinput-and-controller-subtypes)
+* table for a general understanding of each joystick type.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety This should be called from the same thread that called
+*               SDL_LockJoysticks().
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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`.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* Apps can create virtual joysticks, that exist without hardware directly
+* backing them, and have program-supplied inputs. Once attached, a virtual
+* joystick looks like any other joystick that SDL can access. These can be
+* used to make other things look like joysticks, or provide pre-recorded
+* input, etc.
+*
+* Once attached, the app can send joystick inputs to the new virtual joystick
+* using SDL_SetJoystickVirtualAxis(), etc.
+*
+* When no longer needed, the virtual joystick can be removed by calling
+* SDL_DetachVirtualJoystick().
+*
+* \param desc joystick description, initialized using SDL_INIT_INTERFACE().
+* \returns the joystick instance ID, or 0 on failure; call SDL_GetError() for
+*          more information.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \since This function is available since SDL 3.2.0.
+*
+* \sa SDL_DetachVirtualJoystick
+* \sa SDL_SetJoystickVirtualAxis
+* \sa SDL_SetJoystickVirtualButton
+* \sa SDL_SetJoystickVirtualBall
+* \sa SDL_SetJoystickVirtualHat
+* \sa SDL_SetJoystickVirtualTouchpad
+* \sa SDL_SetJoystickVirtualSensorData
+*/
+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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \since This function is available since SDL 3.2.0.
+*
+* \sa SDL_SetJoystickVirtualButton
+* \sa SDL_SetJoystickVirtualBall
+* \sa SDL_SetJoystickVirtualHat
+* \sa SDL_SetJoystickVirtualTouchpad
+* \sa SDL_SetJoystickVirtualSensorData
+*/
+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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \since This function is available since SDL 3.2.0.
+*
+* \sa SDL_SetJoystickVirtualAxis
+* \sa SDL_SetJoystickVirtualButton
+* \sa SDL_SetJoystickVirtualHat
+* \sa SDL_SetJoystickVirtualTouchpad
+* \sa SDL_SetJoystickVirtualSensorData
+*/
+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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \since This function is available since SDL 3.2.0.
+*
+* \sa SDL_SetJoystickVirtualAxis
+* \sa SDL_SetJoystickVirtualBall
+* \sa SDL_SetJoystickVirtualHat
+* \sa SDL_SetJoystickVirtualTouchpad
+* \sa SDL_SetJoystickVirtualSensorData
+*/
+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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \since This function is available since SDL 3.2.0.
+*
+* \sa SDL_SetJoystickVirtualAxis
+* \sa SDL_SetJoystickVirtualButton
+* \sa SDL_SetJoystickVirtualBall
+* \sa SDL_SetJoystickVirtualTouchpad
+* \sa SDL_SetJoystickVirtualSensorData
+*/
+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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \since This function is available since SDL 3.2.0.
+*
+* \sa SDL_SetJoystickVirtualAxis
+* \sa SDL_SetJoystickVirtualButton
+* \sa SDL_SetJoystickVirtualBall
+* \sa SDL_SetJoystickVirtualHat
+* \sa SDL_SetJoystickVirtualSensorData
+*/
+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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \since This function is available since SDL 3.2.0.
+*
+* \sa SDL_SetJoystickVirtualAxis
+* \sa SDL_SetJoystickVirtualButton
+* \sa SDL_SetJoystickVirtualBall
+* \sa SDL_SetJoystickVirtualHat
+* \sa SDL_SetJoystickVirtualTouchpad
+*/
+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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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.
+*
+* \threadsafety It is safe to call this function from any thread.
+*
+* \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 <SDL3/SDL_close_code.h>
+#endif /* SDL_joystick_h_ */

Mercurial > foo_out_sdl

comparison SDL3/SDL_joystick.h @ 1:20d02a178406 default tip