From 4becca4fc9b0c0e3c3d1e159b473dc65080aa7b4 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Thu, 19 Jan 2023 07:42:04 -0800
Subject: [PATCH] Clarify that SDL_GetJoystickFromInstanceID() and
SDL_GetGamepadFromInstanceID() return NULL if the associated device hasn't
been opened yet.
Fixes https://github.com/libsdl-org/SDL/issues/7100
---
include/SDL3/SDL_gamepad.h | 5 ++---
include/SDL3/SDL_joystick.h | 5 ++---
2 files changed, 4 insertions(+), 6 deletions(-)
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index 5c3190669243..a5d5bb3ba162 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -446,11 +446,10 @@ extern DECLSPEC char *SDLCALL SDL_GetGamepadInstanceMapping(SDL_JoystickID insta
extern DECLSPEC SDL_Gamepad *SDLCALL SDL_OpenGamepad(SDL_JoystickID instance_id);
/**
- * Get the SDL_Gamepad associated with a joystick instance ID.
+ * Get the SDL_Gamepad associated with a joystick instance ID, if it has been opened.
*
* \param instance_id the joystick instance ID of the gamepad
- * \returns an SDL_Gamepad on success or NULL on failure; call
- * SDL_GetError() for more information.
+ * \returns an SDL_Gamepad on success or NULL on failure or if it hasn't been opened yet; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h
index 5f67994b927a..5026c62ed493 100644
--- a/include/SDL3/SDL_joystick.h
+++ b/include/SDL3/SDL_joystick.h
@@ -283,11 +283,10 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickInstanceType(SDL_Joystic
extern DECLSPEC SDL_Joystick *SDLCALL SDL_OpenJoystick(SDL_JoystickID instance_id);
/**
- * Get the SDL_Joystick associated with an instance ID.
+ * Get the SDL_Joystick associated with an instance ID, if it has been opened.
*
* \param instance_id the instance ID to get the SDL_Joystick for
- * \returns an SDL_Joystick on success or NULL on failure; call SDL_GetError()
- * for more information.
+ * \returns an SDL_Joystick on success or NULL on failure or if it hasn't been opened yet; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/