From 9c848e08e479162fd423784d2814fd5c60391550 Mon Sep 17 00:00:00 2001
From: Jordan Christiansen <xordspar0@gmail.com>
Date: Mon, 21 Oct 2024 13:06:05 -0500
Subject: [PATCH] docs: Explain events for already plugged in controllers
 (#11286)

---
 include/SDL3/SDL_events.h  | 13 +++++++++++++
 include/SDL3/SDL_gamepad.h | 20 ++++++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index bc5becb5f2..41f9eeab6d 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -549,7 +549,12 @@ 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.
+ *
  * \since This struct is available since SDL 3.0.0.
+ *
+ * \sa SDL_GamepadDeviceEvent
  */
 typedef struct SDL_JoyDeviceEvent
 {
@@ -615,7 +620,15 @@ 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 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.
+ *
+ * \sa SDL_JoyDeviceEvent
  */
 typedef struct SDL_GamepadDeviceEvent
 {
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index 93d18bb141..c4c8ac7f9d 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -295,6 +295,9 @@ typedef struct SDL_GamepadBinding
  *
  * 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:
  *
  * ```c
@@ -309,8 +312,13 @@ typedef struct SDL_GamepadBinding
  *
  * \since This function is available since SDL 3.0.0.
  *
+ * \sa SDL_AddGamepadMappingsFromFile
+ * \sa SDL_AddGamepadMappingsFromIO
  * \sa SDL_GetGamepadMapping
  * \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);
 
@@ -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
  * 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
  * specified will be ignored (i.e. mappings for Linux will be ignored in
  * Windows, etc).
@@ -345,6 +356,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping);
  * \sa SDL_AddGamepadMappingsFromFile
  * \sa SDL_GetGamepadMapping
  * \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);
 
@@ -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
  * 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
  * specified will be ignored (i.e. mappings for Linux will be ignored in
  * Windows, etc).
@@ -373,6 +390,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src,
  * \sa SDL_AddGamepadMappingsFromIO
  * \sa SDL_GetGamepadMapping
  * \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);