From a22baafcf43137b5a93bd385d62fbac150dcbac5 Mon Sep 17 00:00:00 2001
From: Jordan Christiansen <[EMAIL REDACTED]>
Date: Sun, 27 Oct 2024 15:41:43 -0500
Subject: [PATCH] docs: Explain events for already plugged in controllers
---
include/SDL_events.h | 11 +++++++++++
include/SDL_gamecontroller.h | 10 ++++++++++
2 files changed, 21 insertions(+)
diff --git a/include/SDL_events.h b/include/SDL_events.h
index 33d6da4b7eda1..6dcaa5cb1557a 100644
--- a/include/SDL_events.h
+++ b/include/SDL_events.h
@@ -412,6 +412,11 @@ typedef struct SDL_JoyButtonEvent
/**
* Joystick device event structure (event.jdevice.*)
+ *
+ * SDL will send JOYSTICK_ADDED events for devices that
+ * are already plugged in during SDL_Init.
+ *
+ * \sa SDL_ControllerDeviceEvent
*/
typedef struct SDL_JoyDeviceEvent
{
@@ -465,6 +470,12 @@ typedef struct SDL_ControllerButtonEvent
/**
* Controller device event structure (event.cdevice.*)
+ *
+ * Joysticks that are supported game controllers receive both an
+ * SDL_JoyDeviceEvent and an SDL_ControllerDeviceEvent.
+ *
+ * SDL will send CONTROLLERDEVICEADDED events for joysticks that are already plugged
+ * in during SDL_Init() and are recognized as game controllers.
*/
typedef struct SDL_ControllerDeviceEvent
{
diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h
index 030e0f01548ea..8ef27c53c91e5 100644
--- a/include/SDL_gamecontroller.h
+++ b/include/SDL_gamecontroller.h
@@ -146,6 +146,10 @@ typedef struct SDL_GameControllerButtonBind
* If a new mapping is loaded for an already known controller GUID, the later
* version will overwrite the one currently loaded.
*
+ * If this function is called before SDL_Init, SDL will generate
+ * an SDL_CONTROLLERDEVICEADDED event for matching controllers that are
+ * plugged in at the time that SDL_Init is called.
+ *
* 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
* Windows, etc).
@@ -164,6 +168,7 @@ typedef struct SDL_GameControllerButtonBind
* \sa SDL_GameControllerAddMapping
* \sa SDL_GameControllerAddMappingsFromFile
* \sa SDL_GameControllerMappingForGUID
+ * \sa SDL_CONTROLLERDEVICEADDED
*/
extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, int freerw);
@@ -193,6 +198,10 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
* "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7"
* ```
*
+ * If this function is called before SDL_Init, SDL will generate
+ * an SDL_CONTROLLERDEVICEADDED event for matching controllers that are
+ * plugged in at the time that SDL_Init is called.
+ *
* \param mappingString the mapping string.
* \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
* -1 on error; call SDL_GetError() for more information.
@@ -201,6 +210,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
*
* \sa SDL_GameControllerMapping
* \sa SDL_GameControllerMappingForGUID
+ * \sa SDL_CONTROLLERDEVICEADDED
*/
extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingString);