From 4ce7ae31d4403de99e32495fcb2abd80f7352e6a Mon Sep 17 00:00:00 2001
From: Sam Lantinga <slouken@libsdl.org>
Date: Thu, 8 Feb 2024 10:43:00 -0800
Subject: [PATCH] Document that SDL_UpdateJoysticks() needs to be called to
 handle rumble processing

Related: https://github.com/libsdl-org/SDL/issues/4300
---
 include/SDL3/SDL_gamepad.h  | 4 ++++
 include/SDL3/SDL_joystick.h | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index 31ea9b6dd..24d09aa9c 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -1199,6 +1199,8 @@ extern DECLSPEC int SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_S
  * 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 gamepad The gamepad to vibrate
  * \param low_frequency_rumble The intensity of the low frequency (left)
  *                             rumble motor, from 0 to 0xFFFF
@@ -1221,6 +1223,8 @@ extern DECLSPEC int SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_f
  * whole. This is currently only supported on Xbox One gamepads. If you want
  * the (more common) whole-gamepad rumble, use SDL_RumbleGamepad() instead.
  *
+ * This function requires you to process SDL events or call SDL_UpdateJoysticks() to update rumble state.
+ *
  * \param gamepad The gamepad to vibrate
  * \param left_rumble The intensity of the left trigger rumble motor, from 0
  *                    to 0xFFFF
diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h
index 614012e55..279ef7ad9 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -905,6 +905,8 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick,
  * 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
@@ -928,6 +930,8 @@ extern DECLSPEC int SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 lo
  * 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