1 /* 2 Simple DirectMedia Layer 3 Copyright (C) 1997-2014 Sam Lantinga <slouken (at) libsdl.org> 4 5 This software is provided 'as-is', without any express or implied 6 warranty. In no event will the authors be held liable for any damages 7 arising from the use of this software. 8 9 Permission is granted to anyone to use this software for any purpose, 10 including commercial applications, and to alter it and redistribute it 11 freely, subject to the following restrictions: 12 13 1. The origin of this software must not be misrepresented; you must not 14 claim that you wrote the original software. If you use this software 15 in a product, an acknowledgment in the product documentation would be 16 appreciated but is not required. 17 2. Altered source versions must be plainly marked as such, and must not be 18 misrepresented as being the original software. 19 3. This notice may not be removed or altered from any source distribution. 20 */ 21 22 /** 23 * \file SDL_hints.h 24 * 25 * Official documentation for SDL configuration variables 26 * 27 * This file contains functions to set and get configuration hints, 28 * as well as listing each of them alphabetically. 29 * 30 * The convention for naming hints is SDL_HINT_X, where "SDL_X" is 31 * the environment variable that can be used to override the default. 32 * 33 * In general these hints are just that - they may or may not be 34 * supported or applicable on any given platform, but they provide 35 * a way for an application or user to give the library a hint as 36 * to how they would like the library to work. 37 */ 38 39 #ifndef _SDL_hints_h 40 #define _SDL_hints_h 41 42 #include "SDL_stdinc.h" 43 44 #include "begin_code.h" 45 /* Set up for C function definitions, even when using C++ */ 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * \brief A variable controlling how 3D acceleration is used to accelerate the SDL screen surface. 52 * 53 * SDL can try to accelerate the SDL screen surface by using streaming 54 * textures with a 3D rendering engine. This variable controls whether and 55 * how this is done. 56 * 57 * This variable can be set to the following values: 58 * "0" - Disable 3D acceleration 59 * "1" - Enable 3D acceleration, using the default renderer. 60 * "X" - Enable 3D acceleration, using X where X is one of the valid rendering drivers. (e.g. "direct3d", "opengl", etc.) 61 * 62 * By default SDL tries to make a best guess for each platform whether 63 * to use acceleration or not. 64 */ 65 #define SDL_HINT_FRAMEBUFFER_ACCELERATION "SDL_FRAMEBUFFER_ACCELERATION" 66 67 /** 68 * \brief A variable specifying which render driver to use. 69 * 70 * If the application doesn't pick a specific renderer to use, this variable 71 * specifies the name of the preferred renderer. If the preferred renderer 72 * can't be initialized, the normal default renderer is used. 73 * 74 * This variable is case insensitive and can be set to the following values: 75 * "direct3d" 76 * "opengl" 77 * "opengles2" 78 * "opengles" 79 * "software" 80 * 81 * The default varies by platform, but it's the first one in the list that 82 * is available on the current platform. 83 */ 84 #define SDL_HINT_RENDER_DRIVER "SDL_RENDER_DRIVER" 85 86 /** 87 * \brief A variable controlling whether the OpenGL render driver uses shaders if they are available. 88 * 89 * This variable can be set to the following values: 90 * "0" - Disable shaders 91 * "1" - Enable shaders 92 * 93 * By default shaders are used if OpenGL supports them. 94 */ 95 #define SDL_HINT_RENDER_OPENGL_SHADERS "SDL_RENDER_OPENGL_SHADERS" 96 97 /** 98 * \brief A variable controlling whether the Direct3D device is initialized for thread-safe operations. 99 * 100 * This variable can be set to the following values: 101 * "0" - Thread-safety is not enabled (faster) 102 * "1" - Thread-safety is enabled 103 * 104 * By default the Direct3D device is created with thread-safety disabled. 105 */ 106 #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE" 107 108 /** 109 * \brief A variable controlling the scaling quality 110 * 111 * This variable can be set to the following values: 112 * "0" or "nearest" - Nearest pixel sampling 113 * "1" or "linear" - Linear filtering (supported by OpenGL and Direct3D) 114 * "2" or "best" - Currently this is the same as "linear" 115 * 116 * By default nearest pixel sampling is used 117 */ 118 #define SDL_HINT_RENDER_SCALE_QUALITY "SDL_RENDER_SCALE_QUALITY" 119 120 /** 121 * \brief A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing. 122 * 123 * This variable can be set to the following values: 124 * "0" - Disable vsync 125 * "1" - Enable vsync 126 * 127 * By default SDL does not sync screen surface updates with vertical refresh. 128 */ 129 #define SDL_HINT_RENDER_VSYNC "SDL_RENDER_VSYNC" 130 131 /** 132 * \brief A variable controlling whether the screensaver is enabled. 133 * 134 * This variable can be set to the following values: 135 * "0" - Disable screensaver 136 * "1" - Enable screensaver 137 * 138 * By default SDL will disable the screensaver. 139 */ 140 #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER "SDL_VIDEO_ALLOW_SCREENSAVER" 141 142 /** 143 * \brief A variable controlling whether the X11 VidMode extension should be used. 144 * 145 * This variable can be set to the following values: 146 * "0" - Disable XVidMode 147 * "1" - Enable XVidMode 148 * 149 * By default SDL will use XVidMode if it is available. 150 */ 151 #define SDL_HINT_VIDEO_X11_XVIDMODE "SDL_VIDEO_X11_XVIDMODE" 152 153 /** 154 * \brief A variable controlling whether the X11 Xinerama extension should be used. 155 * 156 * This variable can be set to the following values: 157 * "0" - Disable Xinerama 158 * "1" - Enable Xinerama 159 * 160 * By default SDL will use Xinerama if it is available. 161 */ 162 #define SDL_HINT_VIDEO_X11_XINERAMA "SDL_VIDEO_X11_XINERAMA" 163 164 /** 165 * \brief A variable controlling whether the X11 XRandR extension should be used. 166 * 167 * This variable can be set to the following values: 168 * "0" - Disable XRandR 169 * "1" - Enable XRandR 170 * 171 * By default SDL will not use XRandR because of window manager issues. 172 */ 173 #define SDL_HINT_VIDEO_X11_XRANDR "SDL_VIDEO_X11_XRANDR" 174 175 /** 176 * \brief A variable controlling whether grabbing input grabs the keyboard 177 * 178 * This variable can be set to the following values: 179 * "0" - Grab will affect only the mouse 180 * "1" - Grab will affect mouse and keyboard 181 * 182 * By default SDL will not grab the keyboard so system shortcuts still work. 183 */ 184 #define SDL_HINT_GRAB_KEYBOARD "SDL_GRAB_KEYBOARD" 185 186 /** 187 * \brief A variable controlling whether relative mouse mode is implemented using mouse warping 188 * 189 * This variable can be set to the following values: 190 * "0" - Relative mouse mode uses raw input 191 * "1" - Relative mouse mode uses mouse warping 192 * 193 * By default SDL will use raw input for relative mouse mode 194 */ 195 #define SDL_HINT_MOUSE_RELATIVE_MODE_WARP "SDL_MOUSE_RELATIVE_MODE_WARP" 196 197 /** 198 * \brief Minimize your SDL_Window if it loses key focus when in fullscreen mode. Defaults to true. 199 * 200 */ 201 #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS" 202 203 /** 204 * \brief A variable controlling whether the idle timer is disabled on iOS. 205 * 206 * When an iOS app does not receive touches for some time, the screen is 207 * dimmed automatically. For games where the accelerometer is the only input 208 * this is problematic. This functionality can be disabled by setting this 209 * hint. 210 * 211 * This variable can be set to the following values: 212 * "0" - Enable idle timer 213 * "1" - Disable idle timer 214 */ 215 #define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED" 216 217 /** 218 * \brief A variable controlling which orientations are allowed on iOS. 219 * 220 * In some circumstances it is necessary to be able to explicitly control 221 * which UI orientations are allowed. 222 * 223 * This variable is a space delimited list of the following values: 224 * "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown" 225 */ 226 #define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS" 227 228 /** 229 * \brief A variable controlling whether an Android built-in accelerometer should be 230 * listed as a joystick device, rather than listing actual joysticks only. 231 * 232 * This variable can be set to the following values: 233 * "0" - List only real joysticks and accept input from them 234 * "1" - List real joysticks along with the accelerometer as if it were a 3 axis joystick (the default). 235 */ 236 #define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK" 237 238 239 /** 240 * \brief A variable that lets you disable the detection and use of Xinput gamepad devices 241 * 242 * The variable can be set to the following values: 243 * "0" - Disable XInput detection (only uses direct input) 244 * "1" - Enable XInput detection (the default) 245 */ 246 #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED" 247 248 249 /** 250 * \brief A variable that lets you manually hint extra gamecontroller db entries 251 * 252 * The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h 253 * 254 * This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER) 255 * You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping() 256 */ 257 #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG" 258 259 260 /** 261 * \brief A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background. 262 * 263 * The variable can be set to the following values: 264 * "0" - Disable joystick & gamecontroller input events when the 265 * application is in the background. 266 * "1" - Enable joystick & gamecontroller input events when the 267 * application is in the background. 268 * 269 * The default value is "0". This hint may be set at any time. 270 */ 271 #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS" 272 273 274 /** 275 * \brief If set to 0 then never set the top most bit on a SDL Window, even if the video mode expects it. 276 * This is a debugging aid for developers and not expected to be used by end users. The default is "1" 277 * 278 * This variable can be set to the following values: 279 * "0" - don't allow topmost 280 * "1" - allow topmost 281 */ 282 #define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST" 283 284 285 /** 286 * \brief A variable that controls the timer resolution, in milliseconds. 287 * 288 * The higher resolution the timer, the more frequently the CPU services 289 * timer interrupts, and the more precise delays are, but this takes up 290 * power and CPU time. This hint is only used on Windows 7 and earlier. 291 * 292 * See this blog post for more information: 293 * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ 294 * 295 * If this variable is set to "0", the system timer resolution is not set. 296 * 297 * The default value is "1". This hint may be set at any time. 298 */ 299 #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION" 300 301 302 /** 303 * \brief If set to 1, then do not allow high-DPI windows. ("Retina" on Mac) 304 */ 305 #define SDL_HINT_VIDEO_HIGHDPI_DISABLED "SDL_VIDEO_HIGHDPI_DISABLED" 306 307 /** 308 * \brief A variable that determines whether ctrl+click should generate a right-click event on Mac 309 * 310 * If present, holding ctrl while left clicking will generate a right click 311 * event when on Mac. 312 */ 313 #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK" 314 315 /** 316 * \brief A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries 317 * 318 * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It 319 * can use two different sets of binaries, those compiled by the user from source 320 * or those provided by the Chrome browser. In the later case, these binaries require 321 * that SDL loads a DLL providing the shader compiler. 322 * 323 * This variable can be set to the following values: 324 * "d3dcompiler_46.dll" - default, best for Vista or later. 325 * "d3dcompiler_43.dll" - for XP support. 326 * "none" - do not load any library, useful if you compiled ANGLE from source and included the compiler in your binaries. 327 * 328 */ 329 #define SDL_HINT_VIDEO_WIN_D3DCOMPILER "SDL_VIDEO_WIN_D3DCOMPILER" 330 331 /** 332 * \brief A variable that is the address of another SDL_Window* (as a hex string formatted with "%p"). 333 * 334 * If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is set to has 335 * SDL_WINDOW_OPENGL set (and running on WGL only, currently), then two things will occur on the newly 336 * created SDL_Window: 337 338 * 1. Its pixel format will be set to the same pixel format as this SDL_Window. This is 339 * needed for example when sharing an OpenGL context across multiple windows. 340 * 341 * 2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be used for 342 * OpenGL rendering. 343 * 344 * This variable can be set to the following values: 345 * The address (as a string "%p") of the SDL_Window* that new windows created with SDL_CreateWindowFrom() should 346 * share a pixel format with. 347 */ 348 #define SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT "SDL_VIDEO_WINDOW_SHARE_PIXEL_FORMAT" 349 350 /** 351 * \brief A variable that dictates policy for fullscreen Spaces on Mac OS X. 352 * 353 * This hint only applies to Mac OS X. 354 * 355 * The variable can be set to the following values: 356 * "0" - Disable Spaces support (FULLSCREEN_DESKTOP won't use them and 357 * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" 358 * button on their titlebars). 359 * "1" - Enable Spaces support (FULLSCREEN_DESKTOP will use them and 360 * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" 361 * button on their titlebars. 362 * 363 * The default value is "1". Spaces are disabled regardless of this hint if 364 * the OS isn't at least Mac OS X Lion (10.7). This hint must be set before 365 * any windows are created. 366 */ 367 #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES "SDL_VIDEO_MAC_FULLSCREEN_SPACES" 368 369 370 /** 371 * \brief An enumeration of hint priorities 372 */ 373 typedef enum 374 { 375 SDL_HINT_DEFAULT, 376 SDL_HINT_NORMAL, 377 SDL_HINT_OVERRIDE 378 } SDL_HintPriority; 379 380 381 /** 382 * \brief Set a hint with a specific priority 383 * 384 * The priority controls the behavior when setting a hint that already 385 * has a value. Hints will replace existing hints of their priority and 386 * lower. Environment variables are considered to have override priority. 387 * 388 * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise 389 */ 390 extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name, 391 const char *value, 392 SDL_HintPriority priority); 393 394 /** 395 * \brief Set a hint with normal priority 396 * 397 * \return SDL_TRUE if the hint was set, SDL_FALSE otherwise 398 */ 399 extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name, 400 const char *value); 401 402 /** 403 * \brief Get a hint 404 * 405 * \return The string value of a hint variable. 406 */ 407 extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name); 408 409 /** 410 * \brief Add a function to watch a particular hint 411 * 412 * \param name The hint to watch 413 * \param callback The function to call when the hint value changes 414 * \param userdata A pointer to pass to the callback function 415 */ 416 typedef void (*SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue); 417 extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name, 418 SDL_HintCallback callback, 419 void *userdata); 420 421 /** 422 * \brief Remove a function watching a particular hint 423 * 424 * \param name The hint being watched 425 * \param callback The function being called when the hint value changes 426 * \param userdata A pointer being passed to the callback function 427 */ 428 extern DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name, 429 SDL_HintCallback callback, 430 void *userdata); 431 432 /** 433 * \brief Clear all hints 434 * 435 * This function is called during SDL_Quit() to free stored hints. 436 */ 437 extern DECLSPEC void SDLCALL SDL_ClearHints(void); 438 439 440 /* Ends C function definitions when using C++ */ 441 #ifdef __cplusplus 442 } 443 #endif 444 #include "close_code.h" 445 446 #endif /* _SDL_hints_h */ 447 448 /* vi: set ts=4 sw=4 expandtab: */ 449
