gitea/SDL3_fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Explain events for already plugged in controllers (#11286)

Browse Source
This commit is contained in:
Jordan Christiansen
2024-10-21 13:06:05 -05:00
committed by GitHub
parent 26567df878
commit 9c848e08e4
2 changed files with 33 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
include/SDL3/SDL_events.h
View File

@@ -549,7 +549,12 @@ typedef struct SDL_JoyButtonEvent
/** /**
* Joystick device event structure (event.jdevice.*) * Joystick device event structure (event.jdevice.*)
* *
* SDL will send JOYSTICK_ADDED events for devices that
* are already plugged in during SDL_Init.
*
* \since This struct is available since SDL 3.0.0. * \since This struct is available since SDL 3.0.0.
*
* \sa SDL_GamepadDeviceEvent
*/ */
typedef struct SDL_JoyDeviceEvent typedef struct SDL_JoyDeviceEvent
{ {
@@ -615,7 +620,15 @@ typedef struct SDL_GamepadButtonEvent
/** /**
* Gamepad device event structure (event.gdevice.*) * Gamepad device event structure (event.gdevice.*)
* *
* Joysticks that are supported gamepads receive both an SDL_JoyDeviceEvent and
* an SDL_GamepadDeviceEvent.
*
* SDL will send GAMEPAD_ADDED events for joysticks
* that are already plugged in during SDL_Init() and are recognized as gamepads. It will also send events for joysticks that get gamepad mappings at runtime.
*
* \since This struct is available since SDL 3.0.0. * \since This struct is available since SDL 3.0.0.
*
* \sa SDL_JoyDeviceEvent
*/ */
typedef struct SDL_GamepadDeviceEvent typedef struct SDL_GamepadDeviceEvent
{ {

20
include/SDL3/SDL_gamepad.h
View File

@@ -295,6 +295,9 @@ typedef struct SDL_GamepadBinding
* *
* Buttons can be used as a gamepad axes and vice versa. * Buttons can be used as a gamepad axes and vice versa.
* *
* If a device with this GUID is already plugged in, SDL will generate an
* SDL_EVENT_GAMEPAD_ADDED event.
*
* This string shows an example of a valid mapping for a gamepad: * This string shows an example of a valid mapping for a gamepad:
* *
* ```c * ```c
@@ -309,8 +312,13 @@ typedef struct SDL_GamepadBinding
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_AddGamepadMappingsFromFile
* \sa SDL_AddGamepadMappingsFromIO
* \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMapping
* \sa SDL_GetGamepadMappingForGUID * \sa SDL_GetGamepadMappingForGUID
* \sa SDL_HINT_GAMECONTROLLERCONFIG
* \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE
* \sa SDL_EVENT_GAMEPAD_ADDED
*/ */
extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping); extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping);
@@ -323,6 +331,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping);
* If a new mapping is loaded for an already known gamepad GUID, the later * If a new mapping is loaded for an already known gamepad GUID, the later
* version will overwrite the one currently loaded. * version will overwrite the one currently loaded.
* *
* Any new mappings for already plugged in controllers will generate
* SDL_EVENT_GAMEPAD_ADDED events.
*
* Mappings not belonging to the current platform or with no platform field * Mappings not belonging to the current platform or with no platform field
* specified will be ignored (i.e. mappings for Linux will be ignored in * specified will be ignored (i.e. mappings for Linux will be ignored in
* Windows, etc). * Windows, etc).
@@ -345,6 +356,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping);
* \sa SDL_AddGamepadMappingsFromFile * \sa SDL_AddGamepadMappingsFromFile
* \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMapping
* \sa SDL_GetGamepadMappingForGUID * \sa SDL_GetGamepadMappingForGUID
* \sa SDL_HINT_GAMECONTROLLERCONFIG
* \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE
* \sa SDL_EVENT_GAMEPAD_ADDED
*/ */
extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, bool closeio); extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src, bool closeio);
@@ -357,6 +371,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src,
* If a new mapping is loaded for an already known gamepad GUID, the later * If a new mapping is loaded for an already known gamepad GUID, the later
* version will overwrite the one currently loaded. * version will overwrite the one currently loaded.
* *
* Any new mappings for already plugged in controllers will generate
* SDL_EVENT_GAMEPAD_ADDED events.
*
* Mappings not belonging to the current platform or with no platform field * Mappings not belonging to the current platform or with no platform field
* specified will be ignored (i.e. mappings for Linux will be ignored in * specified will be ignored (i.e. mappings for Linux will be ignored in
* Windows, etc). * Windows, etc).
@@ -373,6 +390,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src,
* \sa SDL_AddGamepadMappingsFromIO * \sa SDL_AddGamepadMappingsFromIO
* \sa SDL_GetGamepadMapping * \sa SDL_GetGamepadMapping
* \sa SDL_GetGamepadMappingForGUID * \sa SDL_GetGamepadMappingForGUID
* \sa SDL_HINT_GAMECONTROLLERCONFIG
* \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE
* \sa SDL_EVENT_GAMEPAD_ADDED
*/ */
extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file); extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromFile(const char *file);