From 6247568a1b2a3c8dbafa0b89c0c07cf9bf832a84 Mon Sep 17 00:00:00 2001
From: Zack Middleton <[EMAIL REDACTED]>
Date: Fri, 2 Jan 2026 01:12:44 -0500
Subject: [PATCH] Improve hint documentation
---
include/SDL3/SDL_hints.h | 100 +++++++++++++++++++++++++++------------
1 file changed, 71 insertions(+), 29 deletions(-)
diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h
index 1e047dde79066..d9ed566dd01a6 100644
--- a/include/SDL3/SDL_hints.h
+++ b/include/SDL3/SDL_hints.h
@@ -1095,7 +1095,7 @@ extern "C" {
*
* This hint should be set before SDL is initialized.
*
- * \since This hint is available since SDL 3.2.0.
+ * \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_HIDAPI_LIBUSB_GAMECUBE "SDL_HIDAPI_LIBUSB_GAMECUBE"
@@ -1778,10 +1778,16 @@ extern "C" {
* A variable controlling whether the HIDAPI driver for HORI licensed Steam
* controllers should be used.
*
- * This variable can be set to the following values: "0" - HIDAPI driver is
- * not used "1" - HIDAPI driver is used
+ * The variable can be set to the following values:
*
- * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ * - "0": HIDAPI driver is not used.
+ * - "1": HIDAPI driver is used.
+ *
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI.
+ *
+ * This hint should be set before initializing joysticks and gamepads.
+ *
+ * \since This hint is available since SDL 3.2.0.
*/
#define SDL_HINT_JOYSTICK_HIDAPI_STEAM_HORI "SDL_JOYSTICK_HIDAPI_STEAM_HORI"
@@ -1789,12 +1795,16 @@ extern "C" {
* A variable controlling whether the HIDAPI driver for some Logitech wheels
* should be used.
*
- * This variable can be set to the following values:
+ * The variable can be set to the following values:
*
- * - "0": HIDAPI driver is not used
- * - "1": HIDAPI driver is used
+ * - "0": HIDAPI driver is not used.
+ * - "1": HIDAPI driver is used.
*
- * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI.
+ *
+ * This hint should be set before initializing joysticks and gamepads.
+ *
+ * \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_JOYSTICK_HIDAPI_LG4FF "SDL_JOYSTICK_HIDAPI_LG4FF"
@@ -1802,11 +1812,16 @@ extern "C" {
* A variable controlling whether the HIDAPI driver for 8BitDo controllers
* should be used.
*
- * This variable can be set to the following values:
+ * The variable can be set to the following values:
*
- * "0" - HIDAPI driver is not used. "1" - HIDAPI driver is used.
+ * - "0": HIDAPI driver is not used.
+ * - "1": HIDAPI driver is used.
*
- * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI.
+ *
+ * This hint should be set before initializing joysticks and gamepads.
+ *
+ * \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_JOYSTICK_HIDAPI_8BITDO "SDL_JOYSTICK_HIDAPI_8BITDO"
@@ -1816,11 +1831,16 @@ extern "C" {
*
* More info - https://github.com/HandHeldLegend/SInput-HID
*
- * This variable can be set to the following values:
+ * The variable can be set to the following values:
*
- * "0" - HIDAPI driver is not used. "1" - HIDAPI driver is used.
+ * - "0": HIDAPI driver is not used.
+ * - "1": HIDAPI driver is used.
*
- * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI.
+ *
+ * This hint should be set before initializing joysticks and gamepads.
+ *
+ * \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_JOYSTICK_HIDAPI_SINPUT "SDL_JOYSTICK_HIDAPI_SINPUT"
@@ -1828,11 +1848,16 @@ extern "C" {
* A variable controlling whether the HIDAPI driver for ZUIKI controllers
* should be used.
*
- * This variable can be set to the following values:
+ * The variable can be set to the following values:
*
- * "0" - HIDAPI driver is not used. "1" - HIDAPI driver is used.
+ * - "0": HIDAPI driver is not used.
+ * - "1": HIDAPI driver is used.
*
- * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI.
+ *
+ * This hint should be set before initializing joysticks and gamepads.
+ *
+ * \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_JOYSTICK_HIDAPI_ZUIKI "SDL_JOYSTICK_HIDAPI_ZUIKI"
@@ -1840,11 +1865,16 @@ extern "C" {
* A variable controlling whether the HIDAPI driver for Flydigi controllers
* should be used.
*
- * This variable can be set to the following values:
+ * The variable can be set to the following values:
*
- * "0" - HIDAPI driver is not used. "1" - HIDAPI driver is used.
+ * - "0": HIDAPI driver is not used.
+ * - "1": HIDAPI driver is used.
*
- * The default is the value of SDL_HINT_JOYSTICK_HIDAPI
+ * The default is the value of SDL_HINT_JOYSTICK_HIDAPI.
+ *
+ * This hint should be set before initializing joysticks and gamepads.
+ *
+ * \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_JOYSTICK_HIDAPI_FLYDIGI "SDL_JOYSTICK_HIDAPI_FLYDIGI"
@@ -3300,33 +3330,45 @@ extern "C" {
#define SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED "SDL_ROG_GAMEPAD_MICE_EXCLUDED"
/**
- * Variable controlling the width of the PS2's framebuffer in pixels
+ * A variable controlling the width of the PS2's framebuffer in pixels.
+ *
+ * By default, the variable is "640".
*
- * By default, this variable is "640"
+ * \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_PS2_GS_WIDTH "SDL_PS2_GS_WIDTH"
/**
- * Variable controlling the height of the PS2's framebuffer in pixels
+ * A variable controlling the height of the PS2's framebuffer in pixels.
+ *
+ * By default, the variable is "448".
*
- * By default, this variable is "448"
+ * \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_PS2_GS_HEIGHT "SDL_PS2_GS_HEIGHT"
/**
- * Variable controlling whether the signal is interlaced or progressive
+ * A variable controlling whether the signal is interlaced or progressive.
+ *
+ * The variable can be set to the following values:
*
* - "0": Image is interlaced. (default)
- * - "1": Image is progressive
+ * - "1": Image is progressive.
+ *
+ * \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_PS2_GS_PROGRESSIVE "SDL_PS2_GS_PROGRESSIVE"
/**
- * Variable controlling the video mode of the console
+ * A variable controlling the video mode of the console.
+ *
+ * The variable can be set to the following values:
*
* - "": Console-native. (default)
- * - "NTSC": 60hz region
- * - "PAL": 50hz region
+ * - "NTSC": 60hz region.
+ * - "PAL": 50hz region.
+ *
+ * \since This hint is available since SDL 3.4.0.
*/
#define SDL_HINT_PS2_GS_MODE "SDL_PS2_GS_MODE"