Module fermium::hints

SDL configuration variables

This file contains functions to set and get configuration hints, as well as listing each of them alphabetically.

The convention for naming hints is SDL_HINT_X, where “SDL_X” is the environment variable that can be used to override the default.

In general these hints are just that - they may or may not be supported or applicable on any given platform, but they provide a way for an application or user to give the library a hint as to how they would like the library to work.

Structs

• SDL_HintPriority
  An enumeration of hint priorities.

Constants

• SDL_HINT_ACCELEROMETER_AS_JOYSTICK
  A variable controlling whether the Android / iOS built-in accelerometer should be listed as a joystick device.
• SDL_HINT_ALLOW_TOPMOST
  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”
• SDL_HINT_ANDROID_APK_EXPANSION_MAIN_FILE_VERSION
  Android APK expansion main file version. Should be a string number like “1”, “2” etc.
• SDL_HINT_ANDROID_APK_EXPANSION_PATCH_FILE_VERSION
  Android APK expansion patch file version. Should be a string number like “1”, “2” etc.
• SDL_HINT_ANDROID_BLOCK_ON_PAUSE
  A variable to control whether the event loop will block itself when the app is paused.
• SDL_HINT_ANDROID_BLOCK_ON_PAUSE_PAUSEAUDIO
  A variable to control whether SDL will pause audio in background (Requires SDL_ANDROID_BLOCK_ON_PAUSE as “Non blocking”)
• SDL_HINT_ANDROID_TRAP_BACK_BUTTON
  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_KEYDOWN / SDL_KEYUP pair with a keycode of SDL_SCANCODE_AC_BACK.
• SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS
  A variable controlling whether controllers used with the Apple TV generate UI events.
• SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION
  A variable controlling whether the Apple TV remote’s joystick axes will automatically match the rotation of the remote.
• SDL_HINT_AUDIO_CATEGORY
  A variable controlling the audio category on iOS and Mac OS X
• SDL_HINT_AUDIO_DEVICE_APP_NAME
  Specify an application name for an audio device.
• SDL_HINT_AUDIO_DEVICE_STREAM_NAME
  Specify an application name for an audio device.
• SDL_HINT_AUDIO_DEVICE_STREAM_ROLE
  Specify an application role for an audio device.
• SDL_HINT_AUDIO_INCLUDE_MONITORS
  A variable that causes SDL to not ignore audio “monitors”
• SDL_HINT_AUDIO_RESAMPLING_MODE
  A variable controlling speed/quality tradeoff of audio resampling.
• SDL_HINT_AUTO_UPDATE_JOYSTICKS
  A variable controlling whether SDL updates joystick state when getting input events
• SDL_HINT_AUTO_UPDATE_SENSORS
  A variable controlling whether SDL updates sensor state when getting input events
• SDL_HINT_BMP_SAVE_LEGACY_FORMAT
  Prevent SDL from using version 4 of the bitmap header when saving BMPs.
• SDL_HINT_DEFAULT
• SDL_HINT_DISPLAY_USABLE_BOUNDS
  Override for SDL_GetDisplayUsableBounds
• SDL_HINT_EMSCRIPTEN_ASYNCIFY
  Disable giving back control to the browser automatically when running with asyncify
• SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT
  Override the binding element for keyboard inputs for Emscripten builds
• SDL_HINT_ENABLE_STEAM_CONTROLLERS
  A variable that controls whether Steam Controllers should be exposed using the SDL joystick and game controller APIs
• SDL_HINT_EVENT_LOGGING
  A variable controlling whether SDL logs all events pushed onto its internal queue.
• SDL_HINT_FRAMEBUFFER_ACCELERATION
  A variable controlling how 3D acceleration is used to accelerate the SDL screen surface.
• SDL_HINT_GAMECONTROLLERCONFIG
  A variable that lets you manually hint extra gamecontroller db entries.
• SDL_HINT_GAMECONTROLLERCONFIG_FILE
  A variable that lets you provide a file with extra gamecontroller db entries.
• SDL_HINT_GAMECONTROLLERTYPE
  A variable that overrides the automatic controller type detection
• SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES
  A variable containing a list of devices to skip when scanning for game controllers.
• SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT
  If set, all devices will be skipped when scanning for game controllers except for the ones listed in this variable.
• SDL_HINT_GAMECONTROLLER_USE_BUTTON_LABELS
  If set, game controller face buttons report their values according to their labels instead of their positional layout.
• SDL_HINT_GRAB_KEYBOARD
  A variable controlling whether grabbing input grabs the keyboard
• SDL_HINT_IDLE_TIMER_DISABLED
  A variable controlling whether the idle timer is disabled on iOS.
• SDL_HINT_IME_INTERNAL_EDITING
  A variable to control whether certain IMEs should handle text editing internally instead of sending SDL_TEXTEDITING events.
• SDL_HINT_IOS_HIDE_HOME_INDICATOR
  A variable controlling whether the home indicator bar on iPhone X should be hidden.
• SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS
  A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background.
• SDL_HINT_JOYSTICK_HIDAPI
  A variable controlling whether the HIDAPI joystick drivers should be used.
• SDL_HINT_JOYSTICK_HIDAPI_CORRELATE_XINPUT
  A variable controlling whether the HIDAPI driver for XBox controllers on Windows should pull correlated data from XInput.
• SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE
  A variable controlling whether the HIDAPI driver for Nintendo GameCube controllers should be used.
• SDL_HINT_JOYSTICK_HIDAPI_PS4
  A variable controlling whether the HIDAPI driver for PS4 controllers should be used.
• SDL_HINT_JOYSTICK_HIDAPI_PS4_RUMBLE
  A variable controlling whether extended input reports should be used for PS4 controllers when using the HIDAPI driver.
• SDL_HINT_JOYSTICK_HIDAPI_PS5
  A variable controlling whether the HIDAPI driver for PS5 controllers should be used.
• SDL_HINT_JOYSTICK_HIDAPI_STEAM
  A variable controlling whether the HIDAPI driver for Steam Controllers should be used.
• SDL_HINT_JOYSTICK_HIDAPI_SWITCH
  A variable controlling whether the HIDAPI driver for Nintendo Switch controllers should be used.
• SDL_HINT_JOYSTICK_HIDAPI_XBOX
  A variable controlling whether the HIDAPI driver for XBox controllers should be used.
• SDL_HINT_JOYSTICK_RAWINPUT
  A variable controlling whether the RAWINPUT joystick drivers should be used for better handling XInput-capable devices.
• SDL_HINT_JOYSTICK_THREAD
  A variable controlling whether a separate thread should be used for handling joystick detection and raw input messages on Windows
• SDL_HINT_LINUX_JOYSTICK_DEADZONES
  A variable controlling whether joysticks on Linux adhere to their HID-defined deadzones or return unfiltered values.
• SDL_HINT_MAC_BACKGROUND_APP
  When set don’t force the SDL app to become a foreground process
• SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK
  A variable that determines whether ctrl+click should generate a right-click event on Mac
• SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS
  A variable setting the double click radius, in pixels.
• SDL_HINT_MOUSE_DOUBLE_CLICK_TIME
  A variable setting the double click time, in milliseconds.
• SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH
  Allow mouse click events when clicking to focus an SDL window
• SDL_HINT_MOUSE_NORMAL_SPEED_SCALE
  A variable setting the speed scale for mouse motion, in floating point, when the mouse is not in relative mode
• SDL_HINT_MOUSE_RELATIVE_MODE_WARP
  A variable controlling whether relative mouse mode is implemented using mouse warping
• SDL_HINT_MOUSE_RELATIVE_SCALING
  A variable controlling whether relative mouse motion is affected by renderer scaling
• SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE
  A variable setting the scale for mouse motion, in floating point, when the mouse is in relative mode
• SDL_HINT_MOUSE_TOUCH_EVENTS
  A variable controlling whether mouse events should generate synthetic touch events
• SDL_HINT_NORMAL
• SDL_HINT_NO_SIGNAL_HANDLERS
  Tell SDL not to catch the SIGINT or SIGTERM signals.
• SDL_HINT_OPENGL_ES_DRIVER
  A variable controlling what driver to use for OpenGL ES contexts.
• SDL_HINT_ORIENTATIONS
  A variable controlling which orientations are allowed on iOS/Android.
• SDL_HINT_OVERRIDE
• SDL_HINT_PREFERRED_LOCALES
  Override for SDL_GetPreferredLocales()
• SDL_HINT_QTWAYLAND_CONTENT_ORIENTATION
  A variable describing the content orientation on QtWayland-based platforms.
• SDL_HINT_QTWAYLAND_WINDOW_FLAGS
  Flags to set on QtWayland windows to integrate with the native window manager.
• SDL_HINT_RENDER_BATCHING
  A variable controlling whether the 2D render API is compatible or efficient.
• SDL_HINT_RENDER_DIRECT3D11_DEBUG
  A variable controlling whether to enable Direct3D 11+’s Debug Layer.
• SDL_HINT_RENDER_DIRECT3D_THREADSAFE
  A variable controlling whether the Direct3D device is initialized for thread-safe operations.
• SDL_HINT_RENDER_DRIVER
  A variable specifying which render driver to use.
• SDL_HINT_RENDER_OPENGL_SHADERS
  A variable controlling whether the OpenGL render driver uses shaders if they are available.
• SDL_HINT_RENDER_SCALE_QUALITY
  A variable controlling the scaling quality
• SDL_HINT_RENDER_VSYNC
  A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing.
• SDL_HINT_RETURN_KEY_HIDES_IME
  A variable to control whether the return key on the soft keyboard should hide the soft keyboard on Android and iOS.
• SDL_HINT_RPI_VIDEO_LAYER
  Tell SDL which Dispmanx layer to use on a Raspberry PI
• SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL
  Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as realtime.
• SDL_HINT_THREAD_PRIORITY_POLICY
  A string specifying additional information to use with SDL_SetThreadPriority.
• SDL_HINT_THREAD_STACK_SIZE
  A string specifying SDL’s threads stack size in bytes or “0” for the backend’s default size
• SDL_HINT_TIMER_RESOLUTION
  A variable that controls the timer resolution, in milliseconds.
• SDL_HINT_TOUCH_MOUSE_EVENTS
  A variable controlling whether touch events should generate synthetic mouse events
• SDL_HINT_TV_REMOTE_AS_JOYSTICK
  A variable controlling whether the Android / tvOS remotes should be listed as joystick devices, instead of sending keyboard events.
• SDL_HINT_VIDEO_ALLOW_SCREENSAVER
  A variable controlling whether the screensaver is enabled.
• SDL_HINT_VIDEO_DOUBLE_BUFFER
  Tell the video driver that we only want a double buffer.
• SDL_HINT_VIDEO_EXTERNAL_CONTEXT
  A variable controlling whether the graphics context is externally managed.
• SDL_HINT_VIDEO_HIGHDPI_DISABLED
  If set to 1, then do not allow high-DPI windows. (“Retina” on Mac and iOS)
• SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES
  A variable that dictates policy for fullscreen Spaces on Mac OS X.
• SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS
  Minimize your SDL_Window if it loses key focus when in fullscreen mode.
• SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT
  A variable that is the address of another SDL_Window (as a hex string).
• SDL_HINT_VIDEO_WIN_D3DCOMPILER
  A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries
• SDL_HINT_VIDEO_X11_FORCE_EGL
  A variable controlling whether X11 should use GLX or EGL by default
• SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR
  A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint should be used.
• SDL_HINT_VIDEO_X11_NET_WM_PING
  A variable controlling whether the X11 _NET_WM_PING protocol should be supported.
• SDL_HINT_VIDEO_X11_WINDOW_VISUALID
  A variable forcing the visual ID chosen for new X11 windows
• SDL_HINT_VIDEO_X11_XINERAMA
  A variable controlling whether the X11 Xinerama extension should be used.
• SDL_HINT_VIDEO_X11_XRANDR
  A variable controlling whether the X11 XRandR extension should be used.
• SDL_HINT_VIDEO_X11_XVIDMODE
  A variable controlling whether the X11 VidMode extension should be used.
• SDL_HINT_WAVE_FACT_CHUNK
  Controls how the fact chunk affects the loading of a WAVE file.
• SDL_HINT_WAVE_RIFF_CHUNK_SIZE
  Controls how the size of the RIFF chunk affects the loading of a WAVE file.
• SDL_HINT_WAVE_TRUNCATION
  Controls how a truncated WAVE file is handled.
• SDL_HINT_WINDOWS_DISABLE_THREAD_NAMING
  Tell SDL not to name threads on Windows with the 0x406D1388 Exception.
• SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP
  A variable controlling whether the windows message loop is processed by SDL
• SDL_HINT_WINDOWS_INTRESOURCE_ICON
  A variable to specify custom icon resource id from RC file on Windows platform
• SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL
  A variable to specify custom icon resource id from RC file on Windows platform (small version)
• SDL_HINT_WINDOWS_NO_CLOSE_ON_ALT_F4
  Tell SDL not to generate window-close events for Alt+F4 on Windows.
• SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN
  A variable controlling whether the window frame and title bar are interactive when the cursor is hidden
• SDL_HINT_WINRT_HANDLE_BACK_BUTTON
  Allows back-button-press events on Windows Phone to be marked as handled
• SDL_HINT_WINRT_PRIVACY_POLICY_LABEL
  Label text for a WinRT app’s privacy policy link
• SDL_HINT_WINRT_PRIVACY_POLICY_URL
  A URL to a WinRT app’s privacy policy
• SDL_HINT_XINPUT_ENABLED
  A variable that lets you disable the detection and use of Xinput gamepad devices
• SDL_HINT_XINPUT_USE_OLD_JOYSTICK_MAPPING
  A variable that causes SDL to use the old axis and button mapping for XInput devices.

Functions

• SDL_AddHintCallback^⚠
  Add a function to watch a particular hint
• SDL_ClearHints^⚠
  Clear all hints
• SDL_DelHintCallback^⚠
  Remove a function watching a particular hint
• SDL_GetHint^⚠
  Get a hint
• SDL_GetHintBoolean^⚠
  Get a hint
• SDL_SetHint^⚠
  Set a hint with normal priority
• SDL_SetHintWithPriority^⚠
  Set a hint with a specific priority

Type Definitions

• SDL_HintCallback
  See SDL_AddHintCallback and SDL_DelHintCallback.