SDL: Cleaned up and organized hint documentation

From ef8791cba848acfcdf803a7139314d350aad336d Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Sun, 11 Feb 2024 09:49:28 -0800
Subject: [PATCH] Cleaned up and organized hint documentation

---
 include/SDL3/SDL_hints.h | 2928 ++++++++++++++++++--------------------
 1 file changed, 1356 insertions(+), 1572 deletions(-)

diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h
index b72ac5e0ee19..53ebac381f24 100644
--- a/include/SDL3/SDL_hints.h
+++ b/include/SDL3/SDL_hints.h
@@ -55,21 +55,25 @@ extern "C" {
  * your application if you've enabled keyboard grab.
  *
  * The variable can be set to the following values:
- *   "0"       - SDL will not handle Alt+Tab. Your application is responsible
-                 for handling Alt+Tab while the keyboard is grabbed.
+ *   "0"       - SDL will not handle Alt+Tab. Your application is responsible for handling Alt+Tab while the keyboard is grabbed.
  *   "1"       - SDL will minimize your window when Alt+Tab is pressed (default)
-*/
+ *
+ * This hint can be set anytime.
+ */
 #define SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED "SDL_ALLOW_ALT_TAB_WHILE_GRABBED"
 
 /**
- *  If set to "0" then never set the top most bit on a SDL Window, even if the video mode expects it.
- *      This is a debugging aid for developers and not expected to be used by end users. The default is "1"
+ * A variable to control whether the SDL activity is allowed to be re-created.
+ *
+ * If this hint is true, the activity can be recreated on demand by the OS, and Java static data and C++ static data remain with their current values. If this hint is false, then SDL will call exit() when you return from your main function and the application will be terminated and then started fresh each time.
  *
- *  This variable can be set to the following values:
- *    "0"       - don't allow topmost
- *    "1"       - allow topmost
+ * The variable can be set to the following values:
+ *   "0"       - The application starts fresh at each launch. (default)
+ *   "1"       - The application activity can be recreated by the OS.
+ *
+ * This hint can be set anytime.
  */
-#define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST"
+#define SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY "SDL_ANDROID_ALLOW_RECREATE_ACTIVITY"
 
 /**
  * A variable to control whether the event loop will block itself when the app is paused.
@@ -78,28 +82,25 @@ extern "C" {
  *   "0"       - Non blocking.
  *   "1"       - Blocking. (default)
  *
- * The value should be set before SDL is initialized.
+ * This hint should be set before SDL is initialized.
  */
 #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE "SDL_ANDROID_BLOCK_ON_PAUSE"
 
 /**
- * A variable to control whether SDL will pause audio in background
- *        (Requires SDL_ANDROID_BLOCK_ON_PAUSE as "Non blocking")
+ * A variable to control whether SDL will pause audio in background.
  *
  * The variable can be set to the following values:
- *   "0"       - Non paused.
+ *   "0"       - Not paused, requires that SDL_HINT_ANDROID_BLOCK_ON_PAUSE be set to "0"
  *   "1"       - Paused. (default)
  *
- * The value should be set before SDL is initialized.
+ * This hint should be set before SDL is initialized.
  */
 #define SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO "SDL_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO"
 
 /**
  * A variable to control whether we trap the Android back button to handle it manually.
- *        This is necessary for the right mouse button to work on some Android devices, or
- *        to be able to trap the back button for use in your code reliably.  If set to true,
- *        the back button will show up as an SDL_EVENT_KEY_DOWN / SDL_EVENT_KEY_UP pair with a keycode of
- *        SDL_SCANCODE_AC_BACK.
+ *
+ * This is necessary for the right mouse button to work on some Android devices, or to be able to trap the back button for use in your code reliably. If this hint is true, the back button will show up as an SDL_EVENT_KEY_DOWN / SDL_EVENT_KEY_UP pair with a keycode of SDL_SCANCODE_AC_BACK.
  *
  * The variable can be set to the following values:
  *   "0"       - Back button will be handled as usual for system. (default)
@@ -107,78 +108,50 @@ extern "C" {
  *               manually.  (This will also let right mouse click work on systems
  *               where the right mouse button functions as back.)
  *
- * The value of this hint is used at runtime, so it can be changed at any time.
+ * This hint can be set anytime.
  */
 #define SDL_HINT_ANDROID_TRAP_BACK_BUTTON "SDL_ANDROID_TRAP_BACK_BUTTON"
 
 /**
- * A variable to control whether SDL activity is allowed to be re-created.
- *        If so, java static datas and static datas from native libraries remain with their current values.
- *        When not allowed, the activity terminates with exit(0) to be fully re-initialized afterward.
- *
- * The variable can be set to the following values:
- *   "0"       - Not allowed. (default)
- *   "1"       - Allowed.
+ * A variable setting the app ID string.
  *
- * The value of this hint is used at runtime, so it can be changed at any time.
- */
-#define SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY "SDL_ANDROID_ALLOW_RECREATE_ACTIVITY"
-
-/**
- *  A variable setting the app ID string.
- *          This string is used by desktop compositors to identify and group windows
- *          together, as well as match applications with associated desktop settings
- *          and icons.
+ * This string is used by desktop compositors to identify and group windows together, as well as match applications with associated desktop settings and icons.
  *
- *          On Wayland this corresponds to the "app ID" window property and on X11 this
- *          corresponds to the WM_CLASS property. Windows inherit the value of this hint
- *          at creation time. Changing this hint after a window has been created will not
- *          change the app ID or class of existing windows.
+ * On Wayland this corresponds to the "app ID" window property and on X11 this corresponds to the WM_CLASS property. Windows inherit the value of this hint at creation time. Changing this hint after a window has been created will not change the app ID or class of existing windows.
  *
- *          For *nix platforms, this string should be formatted in reverse-DNS notation
- *          and follow some basic rules to be valid:
+ * For *nix platforms, this string should be formatted in reverse-DNS notation and follow some basic rules to be valid:
  *
- *          - The application ID must be composed of two or more elements separated by a
- *            period (‘.’) character.
+ * - The application ID must be composed of two or more elements separated by a period (‘.’) character.
  *
- *          - Each element must contain one or more of the alphanumeric characters
- *            (A-Z, a-z, 0-9) plus underscore (‘_’) and hyphen (‘-’) and must not start
- *            with a digit. Note that hyphens, while technically allowed, should not be
- *            used if possible, as they are not supported by all components that use the ID,
- *            such as D-Bus. For maximum compatibility, replace hyphens with an underscore.
+ * - Each element must contain one or more of the alphanumeric characters (A-Z, a-z, 0-9) plus underscore (‘_’) and hyphen (‘-’) and must not start with a digit. Note that hyphens, while technically allowed, should not be used if possible, as they are not supported by all components that use the ID, such as D-Bus. For maximum compatibility, replace hyphens with an underscore.
  *
- *          - The empty string is not a valid element (ie: your application ID may not
- *            start or end with a period and it is not valid to have two periods in a row).
+ * - The empty string is not a valid element (ie: your application ID may not start or end with a period and it is not valid to have two periods in a row).
  *
- *          - The entire ID must be less than 255 characters in length.
+ * - The entire ID must be less than 255 characters in length.
  *
- *          Examples of valid app ID strings:
+ * Examples of valid app ID strings:
  *
- *          - org.MyOrg.MyApp
- *          - com.your_company.your_app
+ * - org.MyOrg.MyApp
+ * - com.your_company.your_app
  *
- *          Desktops such as GNOME and KDE require that the app ID string matches your
- *          application's .desktop file name (e.g. if the app ID string is 'org.MyOrg.MyApp',
- *          your application's .desktop file should be named 'org.MyOrg.MyApp.desktop').
+ * Desktops such as GNOME and KDE require that the app ID string matches your application's .desktop file name (e.g. if the app ID string is 'org.MyOrg.MyApp', your application's .desktop file should be named 'org.MyOrg.MyApp.desktop').
  *
- *          If you plan to package your application in a container such as Flatpak, the
- *          app ID should match the name of your Flatpak container as well.
+ * If you plan to package your application in a container such as Flatpak, the app ID should match the name of your Flatpak container as well.
  *
- *  If not set, SDL will attempt to use the application executable name.
- *  If the executable name cannot be retrieved, the generic string "SDL_App" will be used.
+ * If not set, SDL will attempt to use the application executable name.
+ * If the executable name cannot be retrieved, the generic string "SDL_App" will be used.
  *
- *  On targets where this is not supported, this hint does nothing.
+ * This hint should be set before SDL is initialized.
  */
 #define SDL_HINT_APP_ID      "SDL_APP_ID"
 
 /**
- *  Specify an application name.
+ * Specify an application name.
  *
  * This hint lets you specify the application name sent to the OS when
  * required. For example, this will often appear in volume control applets for
  * audio streams, and in lists of applications which are inhibiting the
- * screensaver.  You should use a string that describes your program ("My Game
- * 2: The Revenge")
+ * screensaver. You should use a string that describes your program ("My Game 2: The Revenge")
  *
  * Setting this to "" or leaving it unset will have SDL use a reasonable
  * default: probably the application's name or "SDL Application" if SDL
@@ -187,13 +160,12 @@ extern "C" {
  * Note that, for audio streams, this can be overridden with
  * SDL_HINT_AUDIO_DEVICE_APP_NAME.
  *
- * On targets where this is not supported, this hint does nothing.
+ * This hint should be set before SDL is initialized.
  */
 #define SDL_HINT_APP_NAME "SDL_APP_NAME"
 
 /**
- *  A variable controlling whether controllers used with the Apple TV
- *  generate UI events.
+ * A variable controlling whether controllers used with the Apple TV generate UI events.
  *
  * When UI events are generated by controller input, the app will be
  * backgrounded when the Apple TV remote's menu button is pressed, and when the
@@ -203,37 +175,41 @@ extern "C" {
  * can be found here:
  * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/
  *
- *  This variable can be set to the following values:
- *    "0"       - Controller input does not generate UI events (the default).
- *    "1"       - Controller input generates UI events.
+ * The variable can be set to the following values:
+ *   "0"       - Controller input does not generate UI events. (default)
+ *   "1"       - Controller input generates UI events.
+ *
+ * This hint can be set anytime.
  */
 #define SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS "SDL_APPLE_TV_CONTROLLER_UI_EVENTS"
 
 /**
- * A variable controlling whether the Apple TV remote's joystick axes
- *         will automatically match the rotation of the remote.
+ * A variable controlling whether the Apple TV remote's joystick axes will automatically match the rotation of the remote.
+ *
+ * The variable can be set to the following values:
+ *   "0"       - Remote orientation does not affect joystick axes. (default)
+ *   "1"       - Joystick axes are based on the orientation of the remote.
  *
- *  This variable can be set to the following values:
- *    "0"       - Remote orientation does not affect joystick axes (the default).
- *    "1"       - Joystick axes are based on the orientation of the remote.
+ * This hint can be set anytime.
  */
 #define SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION "SDL_APPLE_TV_REMOTE_ALLOW_ROTATION"
 
 /**
- *  A variable controlling the audio category on iOS and macOS
- *
- *  This variable can be set to the following values:
+ * A variable controlling the audio category on iOS and macOS.
  *
- *    "ambient"     - Use the AVAudioSessionCategoryAmbient audio category, will be muted by the phone mute switch (default)
- *    "playback"    - Use the AVAudioSessionCategoryPlayback category
+ * The variable can be set to the following values:
+ *   "ambient"     - Use the AVAudioSessionCategoryAmbient audio category, will be muted by the phone mute switch (default)
+ *   "playback"    - Use the AVAudioSessionCategoryPlayback category.
  *
  *  For more information, see Apple's documentation:
  *  https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html
+ *
+ * This hint should be set before an audio device is opened.
  */
 #define SDL_HINT_AUDIO_CATEGORY   "SDL_AUDIO_CATEGORY"
 
 /**
- *  Specify an application name for an audio device.
+ * Specify an application name for an audio device.
  *
  * Some audio backends (such as PulseAudio) allow you to describe your audio
  * stream. Among other things, this description might show up in a system
@@ -249,12 +225,32 @@ extern "C" {
  * set. Otherwise, it'll probably the application's name or "SDL Application"
  * if SDL doesn't have any better information.
  *
- * On targets where this is not supported, this hint does nothing.
+ * This hint should be set before an audio device is opened.
  */
 #define SDL_HINT_AUDIO_DEVICE_APP_NAME "SDL_AUDIO_DEVICE_APP_NAME"
 
 /**
- *  Specify an application name for an audio device.
+ * A variable controlling device buffer size.
+ *
+ * This hint is an integer > 0, that represents the size of the device's
+ * buffer in sample frames (stereo audio data in 16-bit format is 4 bytes
+ * per sample frame, for example).
+ *
+ * SDL3 generally decides this value on behalf of the app, but if for some
+ * reason the app needs to dictate this (because they want either lower
+ * latency or higher throughput AND ARE WILLING TO DEAL WITH what that
+ * might require of the app), they can specify it.
+ *
+ * SDL will try to accomodate this value, but there is no promise you'll
+ * get the buffer size requested. Many platforms won't honor this request
+ * at all, or might adjust it.
+ *
+ * This hint should be set before an audio device is opened.
+ */
+#define SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES "SDL_AUDIO_DEVICE_SAMPLE_FRAMES"
+
+/**
+ * Specify an audio stream name for an audio device.
  *
  * Some audio backends (such as PulseAudio) allow you to describe your audio
  * stream. Among other things, this description might show up in a system
@@ -270,12 +266,12 @@ extern "C" {
  * Setting this to "" or leaving it unset will have SDL use a reasonable
  * default: "audio stream" or something similar.
  *
- * On targets where this is not supported, this hint does nothing.
+ * This hint should be set before an audio device is opened.
  */
 #define SDL_HINT_AUDIO_DEVICE_STREAM_NAME "SDL_AUDIO_DEVICE_STREAM_NAME"
 
 /**
- *  Specify an application role for an audio device.
+ * Specify an application role for an audio device.
  *
  * Some audio backends (such as Pipewire) allow you to describe the role of
  * your audio stream. Among other things, this description might show up in
@@ -290,36 +286,58 @@ extern "C" {
  * Setting this to "" or leaving it unset will have SDL use a reasonable
  * default: "Game" or something similar.
  *
- * On targets where this is not supported, this hint does nothing.
+ * This hint should be set before an audio device is opened.
  */
 #define SDL_HINT_AUDIO_DEVICE_STREAM_ROLE "SDL_AUDIO_DEVICE_STREAM_ROLE"
 
 /**
- *  A variable controlling whether SDL updates joystick state when getting input events
+ * A variable that specifies an audio backend to use.
+ *
+ * By default, SDL will try all available audio backends in a reasonable order until it finds one that can work, but this hint allows the app or user to force a specific driver, such as "pipewire" if, say, you are on PulseAudio but want to try talking to the lower level instead.
+ *
+ * This hint should be set before SDL is initialized.
+ */
+#define SDL_HINT_AUDIO_DRIVER "SDL_AUDIO_DRIVER"
+
+/**
+ * A variable that causes SDL to not ignore audio "monitors"
+ *
+ * This is currently only used by the PulseAudio driver.
+ *
+ * By default, SDL ignores audio devices that aren't associated with physical hardware. Changing this hint to "1" will expose anything SDL sees that appears to be an audio source or sink. This will add "devices" to the list that the user probably doesn't want or need, but it can be useful in scenarios where you want to hook up SDL to some sort of virtual device, etc.
  *
- *  This variable can be set to the following values:
+ * The variable can be set to the following values:
+ *   "0"       - Audio monitor devices will be ignored. (default)
+ *   "1"       - Audio monitor devices will show up in the device list.
+ *
+ * This hint should be set before SDL is initialized.
+ */
+#define SDL_HINT_AUDIO_INCLUDE_MONITORS "SDL_AUDIO_INCLUDE_MONITORS"
+
+/**
+ * A variable controlling whether SDL updates joystick state when getting input events.
  *
- *    "0"     - You'll call SDL_UpdateJoysticks() manually
- *    "1"     - SDL will automatically call SDL_UpdateJoysticks() (default)
+ * The variable can be set to the following values:
+ *   "0"       - You'll call SDL_UpdateJoysticks() manually.
+ *   "1"       - SDL will automatically call SDL_UpdateJoysticks(). (default)
  *
- *  This hint can be toggled on and off at runtime.
+ * This hint can be set anytime.
  */
 #define SDL_HINT_AUTO_UPDATE_JOYSTICKS  "SDL_AUTO_UPDATE_JOYSTICKS"
 
 /**
- *  A variable controlling whether SDL updates sensor state when getting input events
- *
- *  This variable can be set to the following values:
+ * A variable controlling whether SDL updates sensor state when getting input events
  *
- *    "0"     - You'll call SDL_UpdateSensors() manually
- *    "1"     - SDL will automatically call SDL_UpdateSensors() (default)
+ * The variable can be set to the following values:
+ *   "0"       - You'll call SDL_UpdateSensors() manually.
+ *   "1"       - SDL will automatically call SDL_UpdateSensors(). (default)
  *
- *  This hint can be toggled on and off at runtime.
+ * This hint can be set anytime.
  */
 #define SDL_HINT_AUTO_UPDATE_SENSORS    "SDL_AUTO_UPDATE_SENSORS"
 
 /**
- *  Prevent SDL from using version 4 of the bitmap header when saving BMPs.
+ * Prevent SDL from using version 4 of the bitmap header when saving BMPs.
  *
  * The bitmap header version 4 is required for proper alpha channel support and
  * SDL will use it when required. Should this not be desired, this hint can
@@ -328,252 +346,302 @@ extern "C" {
  * The variable can be set to the following values:
  *   "0"       - Surfaces with a colorkey or an alpha channel are saved to a
  *               32-bit BMP file with an alpha mask. SDL will use the bitmap
- *               header version 4 and set the alpha mask accordingly.
+ *               header version 4 and set the alpha mask accordingly. (default)
  *   "1"       - Surfaces with a colorkey or an alpha channel are saved to a
  *               32-bit BMP file without an alpha mask. The alpha channel data
  *               will be in the file, but applications are going to ignore it.
  *
- * The default value is "0".
+ * This hint can be set anytime.
  */
 #define SDL_HINT_BMP_SAVE_LEGACY_FORMAT "SDL_BMP_SAVE_LEGACY_FORMAT"
 
 /**
- *  Override for SDL_GetDisplayUsableBounds()
+ * A variable controlling whether DirectInput should be used for controllers
+ *
+ * The variable can be set to the following values:
+ *   "0"       - Disable DirectInput detection.
+ *   "1"       - Enable DirectInput detection. (default)
+ *
+ * This hint should be set before SDL is initialized.
+ */
+#define SDL_HINT_DIRECTINPUT_ENABLED "SDL_DIRECTINPUT_ENABLED"
+
+/**
+ * Override for SDL_GetDisplayUsableBounds()
  *
- *  If set, this hint will override the expected results for
- *  SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want
- *  to do this, but this allows an embedded system to request that some of the
- *  screen be reserved for other uses when paired with a well-behaved
- *  application.
+ * If set, this hint will override the expected results for SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want to do this, but this allows an embedded system to request that some of the screen be reserved for other uses when paired with a well-behaved application.
  *
- *  The contents of this hint must be 4 comma-separated integers, the first
- *  is the bounds x, then y, width and height, in that order.
+ * The contents of this hint must be 4 comma-separated integers, the first is the bounds x, then y, width and height, in that order.
+ *
+ * This hint can be set anytime.
  */
 #define SDL_HINT_DISPLAY_USABLE_BOUNDS "SDL_DISPLAY_USABLE_BOUNDS"
 
 /**
- *  Disable giving back control to the browser automatically
- *  when running with asyncify
+ * Disable giving back control to the browser automatically when running with asyncify.
  *
- * With -s ASYNCIFY, SDL calls emscripten_sleep during operations
- * such as refreshing the screen or polling events.
+ * With -s ASYNCIFY, SDL calls emscripten_sleep during operations such as refreshing the screen or polling events.
  *
- * This hint only applies to the emscripten platform
+ * This hint only applies to the emscripten platform.
  *
  * The variable can be set to the following values:
- *    "0"       - Disable emscripten_sleep calls (if you give back browser control manually or use asyncify for other purposes)
- *    "1"       - Enable emscripten_sleep calls (the default)
+ *   "0"       - Disable emscripten_sleep calls (if you give back browser control manually or use asyncify for other purposes).
+ *   "1"       - Enable emscripten_sleep calls. (default)
+ *
+ * This hint can be set anytime.
  */
 #define SDL_HINT_EMSCRIPTEN_ASYNCIFY   "SDL_EMSCRIPTEN_ASYNCIFY"
 
 /**
- *  Specify the CSS selector used for the "default" window/canvas
+ * Specify the CSS selector used for the "default" window/canvas.
  *
- * This hint only applies to the emscripten platform
+ * This hint only applies to the emscripten platform.
  *
  * The default value is "#canvas"
+ *
+ * This hint should be set before creating a window.
  */
 #define SDL_HINT_EMSCRIPTEN_CANVAS_SELECTOR "SDL_EMSCRIPTEN_CANVAS_SELECTOR"
 
 /**
- *  override the binding element for keyboard inputs for Emscripten builds
+ * Override the binding element for keyboard inputs for Emscripten builds.
  *
- * This hint only applies to the emscripten platform
+ * This hint only applies to the emscripten platform.
  *
  * The variable can be one of
- *    "#window"      - The javascript window object (this is the default)
+ *    "#window"      - The javascript window object (default)
  *    "#document"    - The javascript document object
  *    "#screen"      - the javascript window.screen object
  *    "#canvas"      - the WebGL canvas element
  *    any other string without a leading # sign applies to the element on the page with that ID.
+ *
+ * This hint should be set before creating a window.
  */
 #define SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT   "SDL_EMSCRIPTEN_KEYBOARD_ELEMENT"
 
 /**
- *  A variable that controls whether the on-screen keyboard should be shown when text input is active
+ * A variable that controls whether the on-screen keyboard should be shown when text input is active
  *
- *  The variable can be set to the following values:
- *    "0"       - Do not show the on-screen keyboard
- *    "1"       - Show the on-screen keyboard
+ * The variable can be set to the following values:
+ *   "0"       - Do not show the on-screen keyboard.
+ *   "1"       - Show the on-screen keyboard. (default)
  *
- *  The default value is "1". This hint must be set before text input is activated.
+ * This hint must be set before text input is activated.
  */
 #define SDL_HINT_ENABLE_SCREEN_KEYBOARD "SDL_ENABLE_SCREEN_KEYBOARD"
 
 /**
- *  A variable controlling verbosity of the logging of SDL events pushed onto the internal queue.
+ * A variable controlling verbosity of the logging of SDL events pushed onto the internal queue.
  *
- *  This variable can be set to the following values, from least to most verbose:
+ * The variable can be set to the following values, from least to most verbose:
+ *   "0"       - Don't log any events. (default)
+ *   "1"       - Log most events (other than the really spammy ones).
+ *   "2"       - Include mouse and finger motion events.
  *
- *    "0"     - Don't log any events (default)
- *    "1"     - Log most events (other than the really spammy ones).
- *    "2"     - Include mouse and finger motion events.
+ * This is generally meant to be used to debug SDL itself, but can be useful for application developers that need better visibility into what is going on in the event queue. Logged events are sent through SDL_Log(), which means by default they appear on stdout on most platforms or maybe OutputDebugString() on Windows, and can be funneled by the app with SDL_LogSetOutputFunction(), etc.
  *
- *  This is generally meant to be used to debug SDL itself, but can be useful
- *  for application developers that need better visibility into what is going
- *  on in the event queue. Logged events are sent through SDL_Log(), which
- *  means by default they appear on stdout on most platforms or maybe
- *  OutputDebugString() on Windows, and can be funneled by the app with
- *  SDL_LogSetOutputFunction(), etc.
- *
- *  This hint can be toggled on and off at runtime, if you only need to log
- *  events for a small subset of program execution.
+ * This hint can be set anytime.
  */
 #define SDL_HINT_EVENT_LOGGING   "SDL_EVENT_LOGGING"
 
 /**
- *  A variable controlling whether raising the window should be done more forcefully
+ * A variable controlling whether raising the window should be done more forcefully.
+ *
+ * The variable can be set to the following values:
+ *   "0"       - Honor the OS policy for raising windows. (default)
+ *   "1"       - Force the window to be raised, overriding any OS policy.
  *
- *  This variable can be set to the following values:
- *    "0"       - No forcing (the default)
- *    "1"       - Extra level of forcing
+ * At present, this is only an issue under MS Windows, which makes it nearly impossible to programmatically move a window to the foreground, for "security" reasons. See http://stackoverflow.com/a/34414846 for a discussion.
  *
- *  At present, this is only an issue under MS Windows, which makes it nearly impossible to
- *  programmatically move a window to the foreground, for "security" reasons. See
- *  http://stackoverflow.com/a/34414846 for a discussion.
+ * This hint can be set anytime.
  */
 #define SDL_HINT_FORCE_RAISEWINDOW    "SDL_HINT_FORCE_RAISEWINDOW"
 
 /**
-*  A variable controlling whether the window is activated when the SDL_RaiseWindow function is called
-*
-*  This variable can be set to the following values:
-*    "0"       - The window is not activated when the SDL_RaiseWindow function is called
-*    "1"       - The window is activated when the SDL_RaiseWindow function is called
-*
-*  By default SDL will activate the window when the SDL_RaiseWindow function is called.
-*  At present this is only available for MS Windows.
-*/
-#define SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED    "SDL_WINDOW_ACTIVATE_WHEN_RAISED"
-
-/**
- *  A variable controlling how 3D acceleration is used to accelerate the SDL screen surface.
+ * A variable controlling how 3D acceleration is used to accelerate the SDL screen surface.
  *
- *  SDL can try to accelerate the SDL screen surface by using streaming
- *  textures with a 3D rendering engine.  This variable controls whether and
- *  how this is done.
+ * SDL can try to accelerate the SDL screen surface by using streaming textures with a 3D rendering engine.  This variable controls whether and how this is done.
  *
- *  This variable can be set to the following values:
- *    "0"       - Disable 3D acceleration
- *    "1"       - Enable 3D acceleration, using the default renderer.
- *    "X"       - Enable 3D acceleration, using X where X is one of the valid rendering drivers.  (e.g. "direct3d", "opengl", etc.)
+ * The variable can be set to the following values:
+ *   "0"       - Disable 3D acceleration
+ *   "1"       - Enable 3D acceleration, using the default renderer. (default)
+ *   "X"       - Enable 3D acceleration, using X where X is one of the valid rendering drivers.  (e.g. "direct3d", "opengl", etc.)
  *
- *  By default SDL tries to make a best guess for each platform whether
- *  to use acceleration or not.
+ * This hint should be set before calling SDL_GetWindowSurface()
  */
 #define SDL_HINT_FRAMEBUFFER_ACCELERATION   "SDL_FRAMEBUFFER_ACCELERATION"
 
 /**
- *  A variable that lets you manually hint extra gamecontroller db entries.
+ * A variable that lets you manually hint extra gamecontroller db entries.
  *
- *  The variable should be newline delimited rows of gamecontroller config data, see SDL_gamepad.h
+ * The variable should be newline delimited rows of gamecontroller config data, see SDL_gamepad.h
  *
- *  This hint must be set before calling SDL_Init(SDL_INIT_GAMEPAD)
- *  You can update mappings after the system is initialized with SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping()
+ * You can update mappings after SDL is initialized with SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping()
+ *
+ * This hint should be set before SDL is initialized.
  */
 #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG"
 
 /**
- *  A variable that lets you provide a file with extra gamecontroller db entries.
+ * A variable that lets you provide a file with extra gamecontroller db entries.
+ *
+ * The file should contain lines of gamecontroller config data, see SDL_gamepad.h
  *
- *  The file should contain lines of gamecontroller config data, see SDL_gamepad.h
+ * You can update mappings after SDL is initialized with SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping()
  *
- *  This hint must be set before calling SDL_Init(SDL_INIT_GAMEPAD)
- *  You can update mappings after the system is initialized with SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping()
+ * This hint should be set before SDL is initialized.
  */
 #define SDL_HINT_GAMECONTROLLERCONFIG_FILE "SDL_GAMECONTROLLERCONFIG_FILE"
 
 /**
- *  A variable that overrides the automatic controller type detection
+ * A variable that overrides the automatic controller type detection
  *
- *  The variable should be comma separated entries, in the form: VID/PID=type
+ * The variable should be comma separated entries, in the form: VID/PID=type
  *
- *  The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd
+ * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd
  *
- *  The type should be one of:
- *      Xbox360
- *      XboxOne
- *      PS3
- *      PS4
- *      PS5
- *      SwitchPro
+ * This hint affects what low level protocol is used with the HIDAP

(Patch may be truncated, please check the link at the top of this post.)