Skip to content

docs: Explain events for already plugged in controllers #11272

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

docs: Explain events for already plugged in controllers #11272

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions include/SDL3/SDL_events.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -549,7 +549,12 @@ typedef struct SDL_JoyButtonEvent
/**
* Joystick device event structure (event.jdevice.*)
*
* SDL will populate the event queue with JOYSTICK_ADDED events for devices that
* are already plugged in during SDL_Init.
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_GamepadDeviceEvent
*/
typedef struct SDL_JoyDeviceEvent
{
Expand Down Expand Up @@ -615,7 +620,27 @@ typedef struct SDL_GamepadButtonEvent
/**
* Gamepad device event structure (event.gdevice.*)
*
* Joysticks that are supported Gamepads receive both an SDL_JoyDeviceEvent and
* an SDL_GamepadDeviceEvent.
*
* SDL will populate the event queue with GAMEPAD_ADDED events for joysticks
* that are already plugged in duing SDL_Init and are recognized as Gamepads.
*
* GAMEPAD_ADDED events for controllers plugged in at the start of the program
* will not occur automatically if their mappings are added after calling
* SDL_Init.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I confirmed that this is not true in SDL3.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome, that's great news.

*
* If you rely on GAMEPAD_ADDED events to tell you about controllers that are
* already plugged in at the start of the program, and you use
* SDL_AddGamepadMappingsFromFile to add support for additional controllers,
* you can ensure that you get GAMEPAD_ADDED events for all controllers if you
* load the mappings before calling SDL_Init.
*
* \since This struct is available since SDL 3.0.0.
*
* \sa SDL_AddGamepadMappingsFromFile
* \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like it's still called GAMECONTROLLERCONFIG_FILE in SDL 3. Should it be renamed to GAMEPADCONFIG_FILE?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, that's intentional for compatibility between SDL2 and SDL3.

I'll double check, I think you're supposed to get events for gamepads when their mappings become available. If not, we can probably change that.

Copy link
Contributor Author

@xordspar0 xordspar0 Oct 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just noticed SDL 3 has SDL_ReloadGamepadMappings, so maybe that's a new feature in SDL 3? My testing has been with SDL 2, so I'm not sure.

This will generate gamepad events as needed if device mappings change.

* \sa SDL_JoyDeviceEvent
*/
typedef struct SDL_GamepadDeviceEvent
{
Expand Down
Loading