SDL_hints.h

00001 /*
00002   Simple DirectMedia Layer
00003   Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
00004 
00005   This software is provided 'as-is', without any express or implied
00006   warranty.  In no event will the authors be held liable for any damages
00007   arising from the use of this software.
00008 
00009   Permission is granted to anyone to use this software for any purpose,
00010   including commercial applications, and to alter it and redistribute it
00011   freely, subject to the following restrictions:
00012 
00013   1. The origin of this software must not be misrepresented; you must not
00014      claim that you wrote the original software. If you use this software
00015      in a product, an acknowledgment in the product documentation would be
00016      appreciated but is not required.
00017   2. Altered source versions must be plainly marked as such, and must not be
00018      misrepresented as being the original software.
00019   3. This notice may not be removed or altered from any source distribution.
00020 */
00021 
00022 /**
00023  *  \file SDL_hints.h
00024  *
00025  *  Official documentation for SDL configuration variables
00026  *
00027  *  This file contains functions to set and get configuration hints,
00028  *  as well as listing each of them alphabetically.
00029  *
00030  *  The convention for naming hints is SDL_HINT_X, where "SDL_X" is
00031  *  the environment variable that can be used to override the default.
00032  *
00033  *  In general these hints are just that - they may or may not be
00034  *  supported or applicable on any given platform, but they provide
00035  *  a way for an application or user to give the library a hint as
00036  *  to how they would like the library to work.
00037  */
00038 
00039 #ifndef _SDL_hints_h
00040 #define _SDL_hints_h
00041 
00042 #include "SDL_stdinc.h"
00043 
00044 #include "begin_code.h"
00045 /* Set up for C function definitions, even when using C++ */
00046 #ifdef __cplusplus
00047 extern "C" {
00048 #endif
00049 
00050 /**
00051  *  \brief  A variable controlling how 3D acceleration is used to accelerate the SDL screen surface.
00052  *
00053  *  SDL can try to accelerate the SDL screen surface by using streaming
00054  *  textures with a 3D rendering engine.  This variable controls whether and
00055  *  how this is done.
00056  *
00057  *  This variable can be set to the following values:
00058  *    "0"       - Disable 3D acceleration
00059  *    "1"       - Enable 3D acceleration, using the default renderer.
00060  *    "X"       - Enable 3D acceleration, using X where X is one of the valid rendering drivers.  (e.g. "direct3d", "opengl", etc.)
00061  *
00062  *  By default SDL tries to make a best guess for each platform whether
00063  *  to use acceleration or not.
00064  */
00065 #define SDL_HINT_FRAMEBUFFER_ACCELERATION   "SDL_FRAMEBUFFER_ACCELERATION"
00066 
00067 /**
00068  *  \brief  A variable specifying which render driver to use.
00069  *
00070  *  If the application doesn't pick a specific renderer to use, this variable
00071  *  specifies the name of the preferred renderer.  If the preferred renderer
00072  *  can't be initialized, the normal default renderer is used.
00073  *
00074  *  This variable is case insensitive and can be set to the following values:
00075  *    "direct3d"
00076  *    "opengl"
00077  *    "opengles2"
00078  *    "opengles"
00079  *    "software"
00080  *
00081  *  The default varies by platform, but it's the first one in the list that
00082  *  is available on the current platform.
00083  */
00084 #define SDL_HINT_RENDER_DRIVER              "SDL_RENDER_DRIVER"
00085 
00086 /**
00087  *  \brief  A variable controlling whether the OpenGL render driver uses shaders if they are available.
00088  *
00089  *  This variable can be set to the following values:
00090  *    "0"       - Disable shaders
00091  *    "1"       - Enable shaders
00092  *
00093  *  By default shaders are used if OpenGL supports them.
00094  */
00095 #define SDL_HINT_RENDER_OPENGL_SHADERS      "SDL_RENDER_OPENGL_SHADERS"
00096 
00097 /**
00098  *  \brief  A variable controlling whether the Direct3D device is initialized for thread-safe operations.
00099  *
00100  *  This variable can be set to the following values:
00101  *    "0"       - Thread-safety is not enabled (faster)
00102  *    "1"       - Thread-safety is enabled
00103  *
00104  *  By default the Direct3D device is created with thread-safety disabled.
00105  */
00106 #define SDL_HINT_RENDER_DIRECT3D_THREADSAFE "SDL_RENDER_DIRECT3D_THREADSAFE"
00107 
00108 /**
00109  *  \brief  A variable controlling the scaling quality
00110  *
00111  *  This variable can be set to the following values:
00112  *    "0" or "nearest" - Nearest pixel sampling
00113  *    "1" or "linear"  - Linear filtering (supported by OpenGL and Direct3D)
00114  *    "2" or "best"    - Currently this is the same as "linear"
00115  *
00116  *  By default nearest pixel sampling is used
00117  */
00118 #define SDL_HINT_RENDER_SCALE_QUALITY       "SDL_RENDER_SCALE_QUALITY"
00119 
00120 /**
00121  *  \brief  A variable controlling whether updates to the SDL screen surface should be synchronized with the vertical refresh, to avoid tearing.
00122  *
00123  *  This variable can be set to the following values:
00124  *    "0"       - Disable vsync
00125  *    "1"       - Enable vsync
00126  *
00127  *  By default SDL does not sync screen surface updates with vertical refresh.
00128  */
00129 #define SDL_HINT_RENDER_VSYNC               "SDL_RENDER_VSYNC"
00130 
00131 /**
00132  *  \brief  A variable controlling whether the screensaver is enabled. 
00133  *
00134  *  This variable can be set to the following values:
00135  *    "0"       - Disable screensaver
00136  *    "1"       - Enable screensaver
00137  *
00138  *  By default SDL will disable the screensaver.
00139  */
00140 #define SDL_HINT_VIDEO_ALLOW_SCREENSAVER    "SDL_VIDEO_ALLOW_SCREENSAVER"
00141 
00142 /**
00143  *  \brief  A variable controlling whether the X11 VidMode extension should be used.
00144  *
00145  *  This variable can be set to the following values:
00146  *    "0"       - Disable XVidMode
00147  *    "1"       - Enable XVidMode
00148  *
00149  *  By default SDL will use XVidMode if it is available.
00150  */
00151 #define SDL_HINT_VIDEO_X11_XVIDMODE         "SDL_VIDEO_X11_XVIDMODE"
00152 
00153 /**
00154  *  \brief  A variable controlling whether the X11 Xinerama extension should be used.
00155  *
00156  *  This variable can be set to the following values:
00157  *    "0"       - Disable Xinerama
00158  *    "1"       - Enable Xinerama
00159  *
00160  *  By default SDL will use Xinerama if it is available.
00161  */
00162 #define SDL_HINT_VIDEO_X11_XINERAMA         "SDL_VIDEO_X11_XINERAMA"
00163 
00164 /**
00165  *  \brief  A variable controlling whether the X11 XRandR extension should be used.
00166  *
00167  *  This variable can be set to the following values:
00168  *    "0"       - Disable XRandR
00169  *    "1"       - Enable XRandR
00170  *
00171  *  By default SDL will not use XRandR because of window manager issues.
00172  */
00173 #define SDL_HINT_VIDEO_X11_XRANDR           "SDL_VIDEO_X11_XRANDR"
00174 
00175 /**
00176  *  \brief  A variable controlling whether grabbing input grabs the keyboard
00177  *
00178  *  This variable can be set to the following values:
00179  *    "0"       - Grab will affect only the mouse
00180  *    "1"       - Grab will affect mouse and keyboard
00181  *
00182  *  By default SDL will not grab the keyboard so system shortcuts still work.
00183  */
00184 #define SDL_HINT_GRAB_KEYBOARD              "SDL_GRAB_KEYBOARD"
00185 
00186 /**
00187 *  \brief  A variable controlling whether relative mouse mode is implemented using mouse warping
00188 *
00189 *  This variable can be set to the following values:
00190 *    "0"       - Relative mouse mode uses raw input
00191 *    "1"       - Relative mouse mode uses mouse warping
00192 *
00193 *  By default SDL will use raw input for relative mouse mode
00194 */
00195 #define SDL_HINT_MOUSE_RELATIVE_MODE_WARP    "SDL_MOUSE_RELATIVE_MODE_WARP"
00196 
00197 /**
00198  *  \brief Minimize your SDL_Window if it loses key focus when in fullscreen mode. Defaults to true.
00199  *
00200  */
00201 #define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS   "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS"
00202 
00203 /**
00204  *  \brief  A variable controlling whether the idle timer is disabled on iOS.
00205  *
00206  *  When an iOS app does not receive touches for some time, the screen is
00207  *  dimmed automatically. For games where the accelerometer is the only input
00208  *  this is problematic. This functionality can be disabled by setting this
00209  *  hint.
00210  *
00211  *  This variable can be set to the following values:
00212  *    "0"       - Enable idle timer
00213  *    "1"       - Disable idle timer
00214  */
00215 #define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED"
00216 
00217 /**
00218  *  \brief  A variable controlling which orientations are allowed on iOS.
00219  *
00220  *  In some circumstances it is necessary to be able to explicitly control
00221  *  which UI orientations are allowed.
00222  *
00223  *  This variable is a space delimited list of the following values:
00224  *    "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown"
00225  */
00226 #define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS"
00227     
00228 /**
00229  *  \brief  A variable controlling whether an Android built-in accelerometer should be
00230  *  listed as a joystick device, rather than listing actual joysticks only.
00231  *
00232  *  This variable can be set to the following values:
00233  *    "0"       - List only real joysticks and accept input from them
00234  *    "1"       - List real joysticks along with the accelerometer as if it were a 3 axis joystick (the default).
00235  */
00236 #define SDL_HINT_ACCELEROMETER_AS_JOYSTICK "SDL_ACCELEROMETER_AS_JOYSTICK"
00237 
00238 
00239 /**
00240  *  \brief  A variable that lets you disable the detection and use of Xinput gamepad devices
00241  *
00242  *  The variable can be set to the following values:
00243  *    "0"       - Disable XInput detection (only uses direct input)
00244  *    "1"       - Enable XInput detection (the default)
00245  */
00246 #define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED"
00247 
00248 
00249 /**
00250  *  \brief  A variable that lets you manually hint extra gamecontroller db entries
00251  *
00252  *  The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h
00253  *
00254  *  This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
00255  *  You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
00256  */
00257 #define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG"
00258 
00259 
00260 /**
00261  *  \brief  A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background.
00262  *
00263  *  The variable can be set to the following values:
00264  *    "0"       - Disable joystick & gamecontroller input events when the
00265  *                application is in the background.
00266  *    "1"       - Enable joystick & gamecontroller input events when the
00267  *                application is in the background.
00268  *
00269  *  The default value is "0".  This hint may be set at any time.
00270  */
00271 #define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS"
00272 
00273 
00274 /**
00275  *  \brief If set to 0 then never set the top most bit on a SDL Window, even if the video mode expects it.
00276  *      This is a debugging aid for developers and not expected to be used by end users. The default is "1"
00277  *
00278  *  This variable can be set to the following values:
00279  *    "0"       - don't allow topmost
00280  *    "1"       - allow topmost
00281  */
00282 #define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST"
00283 
00284 
00285 /**
00286  *  \brief A variable that controls the timer resolution, in milliseconds.
00287  *
00288  *  The higher resolution the timer, the more frequently the CPU services
00289  *  timer interrupts, and the more precise delays are, but this takes up
00290  *  power and CPU time.  This hint is only used on Windows 7 and earlier.
00291  *
00292  *  See this blog post for more information:
00293  *  http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/
00294  *
00295  *  If this variable is set to "0", the system timer resolution is not set.
00296  *
00297  *  The default value is "1". This hint may be set at any time.
00298  */
00299 #define SDL_HINT_TIMER_RESOLUTION "SDL_TIMER_RESOLUTION"
00300 
00301 
00302 /**
00303  *  \brief If set to 1, then do not allow high-DPI windows. ("Retina" on Mac)
00304  */
00305 #define SDL_HINT_VIDEO_HIGHDPI_DISABLED "SDL_VIDEO_HIGHDPI_DISABLED"
00306 
00307 /**
00308  *  \brief A variable that determines whether ctrl+click should generate a right-click event on Mac
00309  *  
00310  *  If present, holding ctrl while left clicking will generate a right click
00311  *  event when on Mac.
00312  */
00313 #define SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK "SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK"
00314 
00315 /**
00316 *  \brief  A variable specifying which shader compiler to preload when using the Chrome ANGLE binaries
00317 *
00318 *  SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It
00319 *  can use two different sets of binaries, those compiled by the user from source
00320 *  or those provided by the Chrome browser. In the later case, these binaries require
00321 *  that SDL loads a DLL providing the shader compiler.
00322 *
00323 *  This variable can be set to the following values:
00324 *    "d3dcompiler_46.dll" - default, best for Vista or later.
00325 *    "d3dcompiler_43.dll" - for XP support.
00326 *    "none" - do not load any library, useful if you compiled ANGLE from source and included the compiler in your binaries.
00327 *
00328 */
00329 #define SDL_HINT_VIDEO_WIN_D3DCOMPILER              "SDL_VIDEO_WIN_D3DCOMPILER"
00330 
00331 /**
00332 *  \brief  A variable that is the address of another SDL_Window* (as a hex string formatted with "%p").
00333 *  
00334 *  If this hint is set before SDL_CreateWindowFrom() and the SDL_Window* it is set to has
00335 *  SDL_WINDOW_OPENGL set (and running on WGL only, currently), then two things will occur on the newly 
00336 *  created SDL_Window:
00337 
00338 *  1. Its pixel format will be set to the same pixel format as this SDL_Window.  This is
00339 *  needed for example when sharing an OpenGL context across multiple windows.
00340 *
00341 *  2. The flag SDL_WINDOW_OPENGL will be set on the new window so it can be used for
00342 *  OpenGL rendering.
00343 *
00344 *  This variable can be set to the following values:
00345 *    The address (as a string "%p") of the SDL_Window* that new windows created with SDL_CreateWindowFrom() should
00346 *    share a pixel format with.
00347 */
00348 #define SDL_HINT_VIDEO_WINDOW_SHARE_PIXEL_FORMAT    "SDL_VIDEO_WINDOW_SHARE_PIXEL_FORMAT"
00349 
00350 /**
00351  *  \brief  A variable that dictates policy for fullscreen Spaces on Mac OS X.
00352  *
00353  *  This hint only applies to Mac OS X.
00354  *
00355  *  The variable can be set to the following values:
00356  *    "0"       - Disable Spaces support (FULLSCREEN_DESKTOP won't use them and
00357  *                SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen"
00358  *                button on their titlebars).
00359  *    "1"       - Enable Spaces support (FULLSCREEN_DESKTOP will use them and
00360  *                SDL_WINDOW_RESIZABLE windows will offer the "fullscreen"
00361  *                button on their titlebars.
00362  *
00363  *  The default value is "1". Spaces are disabled regardless of this hint if
00364  *   the OS isn't at least Mac OS X Lion (10.7). This hint must be set before
00365  *   any windows are created.
00366  */
00367 #define SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES    "SDL_VIDEO_MAC_FULLSCREEN_SPACES"
00368 
00369 
00370 /**
00371  *  \brief  An enumeration of hint priorities
00372  */
00373 typedef enum
00374 {
00375     SDL_HINT_DEFAULT,
00376     SDL_HINT_NORMAL,
00377     SDL_HINT_OVERRIDE
00378 } SDL_HintPriority;
00379 
00380 
00381 /**
00382  *  \brief Set a hint with a specific priority
00383  *
00384  *  The priority controls the behavior when setting a hint that already
00385  *  has a value.  Hints will replace existing hints of their priority and
00386  *  lower.  Environment variables are considered to have override priority.
00387  *
00388  *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
00389  */
00390 extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name,
00391                                                          const char *value,
00392                                                          SDL_HintPriority priority);
00393 
00394 /**
00395  *  \brief Set a hint with normal priority
00396  *
00397  *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
00398  */
00399 extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
00400                                              const char *value);
00401 
00402 /**
00403  *  \brief Get a hint
00404  *
00405  *  \return The string value of a hint variable.
00406  */
00407 extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
00408 
00409 /**
00410  *  \brief Add a function to watch a particular hint
00411  *
00412  *  \param name The hint to watch
00413  *  \param callback The function to call when the hint value changes
00414  *  \param userdata A pointer to pass to the callback function
00415  */
00416 typedef void (*SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue);
00417 extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name,
00418                                                  SDL_HintCallback callback,
00419                                                  void *userdata);
00420 
00421 /**
00422  *  \brief Remove a function watching a particular hint
00423  *
00424  *  \param name The hint being watched
00425  *  \param callback The function being called when the hint value changes
00426  *  \param userdata A pointer being passed to the callback function
00427  */
00428 extern DECLSPEC void SDLCALL SDL_DelHintCallback(const char *name,
00429                                                  SDL_HintCallback callback,
00430                                                  void *userdata);
00431 
00432 /**
00433  *  \brief  Clear all hints
00434  *
00435  *  This function is called during SDL_Quit() to free stored hints.
00436  */
00437 extern DECLSPEC void SDLCALL SDL_ClearHints(void);
00438 
00439 
00440 /* Ends C function definitions when using C++ */
00441 #ifdef __cplusplus
00442 }
00443 #endif
00444 #include "close_code.h"
00445 
00446 #endif /* _SDL_hints_h */
00447 
00448 /* vi: set ts=4 sw=4 expandtab: */