include/SDL_hints.h
author Jørgen P. Tjernø <jorgen@valvesoftware.com>
Wed, 05 Jun 2013 15:11:38 -0700
changeset 7279 f7805b13b485
parent 7191 75360622e65f
child 7328 bbfc72c803df
permissions -rw-r--r--
Joystick: Only send joy events when focused.

This changes makes it so that you only receive joystick (and implicitly
gamecontroller) input events when your application has keyboard focus.
If you'd like to still receive events when your application is in the
background, set the SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS hint to "1".

This fixes http://bugzilla.libsdl.org/show_bug.cgi?id=1892
slouken@5189
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@6885
     3
  Copyright (C) 1997-2013 Sam Lantinga <slouken@libsdl.org>
slouken@5189
     4
slouken@5535
     5
  This software is provided 'as-is', without any express or implied
slouken@5535
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@5535
     7
  arising from the use of this software.
slouken@5189
     8
slouken@5535
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@5535
    10
  including commercial applications, and to alter it and redistribute it
slouken@5535
    11
  freely, subject to the following restrictions:
slouken@5189
    12
slouken@5535
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@5535
    14
     claim that you wrote the original software. If you use this software
slouken@5535
    15
     in a product, an acknowledgment in the product documentation would be
slouken@5535
    16
     appreciated but is not required.
slouken@5535
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@5535
    18
     misrepresented as being the original software.
slouken@5535
    19
  3. This notice may not be removed or altered from any source distribution.
slouken@5189
    20
*/
slouken@5189
    21
slouken@5189
    22
/**
slouken@5189
    23
 *  \file SDL_hints.h
slouken@7191
    24
 *
slouken@5189
    25
 *  Official documentation for SDL configuration variables
slouken@5189
    26
 *
slouken@5189
    27
 *  This file contains functions to set and get configuration hints,
slouken@5189
    28
 *  as well as listing each of them alphabetically.
slouken@5189
    29
 *
slouken@5189
    30
 *  The convention for naming hints is SDL_HINT_X, where "SDL_X" is
slouken@5189
    31
 *  the environment variable that can be used to override the default.
slouken@5189
    32
 *
slouken@5189
    33
 *  In general these hints are just that - they may or may not be
slouken@5189
    34
 *  supported or applicable on any given platform, but they provide
slouken@5189
    35
 *  a way for an application or user to give the library a hint as
slouken@5189
    36
 *  to how they would like the library to work.
slouken@5189
    37
 */
slouken@5189
    38
slouken@5189
    39
#ifndef _SDL_hints_h
slouken@5189
    40
#define _SDL_hints_h
slouken@5189
    41
slouken@5189
    42
#include "SDL_stdinc.h"
slouken@5189
    43
slouken@5189
    44
#include "begin_code.h"
slouken@5189
    45
/* Set up for C function definitions, even when using C++ */
slouken@5189
    46
#ifdef __cplusplus
slouken@5189
    47
extern "C" {
slouken@5189
    48
#endif
slouken@5189
    49
slouken@5190
    50
/**
slouken@7191
    51
 *  \brief  A variable controlling how 3D acceleration is used to accelerate the SDL 1.2 screen surface.
slouken@5190
    52
 *
slouken@5190
    53
 *  SDL can try to accelerate the SDL 1.2 screen surface by using streaming
slouken@5190
    54
 *  textures with a 3D rendering engine.  This variable controls whether and
slouken@5190
    55
 *  how this is done.
slouken@5190
    56
 *
slouken@5190
    57
 *  This variable can be set to the following values:
slouken@5190
    58
 *    "0"       - Disable 3D acceleration
slouken@5190
    59
 *    "1"       - Enable 3D acceleration, using the default renderer.
slouken@5190
    60
 *    "X"       - Enable 3D acceleration, using X where X is one of the valid rendering drivers.  (e.g. "direct3d", "opengl", etc.)
slouken@5190
    61
 *
slouken@5190
    62
 *  By default SDL tries to make a best guess for each platform whether
slouken@5190
    63
 *  to use acceleration or not.
slouken@5190
    64
 */
slouken@5190
    65
#define SDL_HINT_FRAMEBUFFER_ACCELERATION   "SDL_FRAMEBUFFER_ACCELERATION"
slouken@5189
    66
slouken@5192
    67
/**
slouken@5192
    68
 *  \brief  A variable specifying which render driver to use.
slouken@5192
    69
 *
slouken@5192
    70
 *  If the application doesn't pick a specific renderer to use, this variable
slouken@5192
    71
 *  specifies the name of the preferred renderer.  If the preferred renderer
slouken@5192
    72
 *  can't be initialized, the normal default renderer is used.
slouken@5192
    73
 *
slouken@5192
    74
 *  This variable is case insensitive and can be set to the following values:
slouken@5192
    75
 *    "direct3d"
slouken@5192
    76
 *    "opengl"
slouken@5233
    77
 *    "opengles2"
slouken@5192
    78
 *    "opengles"
slouken@5192
    79
 *    "software"
slouken@5233
    80
 *
slouken@5233
    81
 *  The default varies by platform, but it's the first one in the list that
slouken@5233
    82
 *  is available on the current platform.
slouken@5192
    83
 */
slouken@5192
    84
#define SDL_HINT_RENDER_DRIVER              "SDL_RENDER_DRIVER"
slouken@5192
    85
slouken@5192
    86
/**
slouken@5233
    87
 *  \brief  A variable controlling whether the OpenGL render driver uses shaders if they are available.
slouken@5233
    88
 *
slouken@5233
    89
 *  This variable can be set to the following values:
slouken@5233
    90
 *    "0"       - Disable shaders
slouken@5233
    91
 *    "1"       - Enable shaders
slouken@5233
    92
 *
slouken@5233
    93
 *  By default shaders are used if OpenGL supports them.
slouken@5233
    94
 */
slouken@5233
    95
#define SDL_HINT_RENDER_OPENGL_SHADERS      "SDL_RENDER_OPENGL_SHADERS"
slouken@5233
    96
slouken@5233
    97
/**
slouken@5484
    98
 *  \brief  A variable controlling the scaling quality
slouken@5484
    99
 *
slouken@5484
   100
 *  This variable can be set to the following values:
slouken@5484
   101
 *    "0" or "nearest" - Nearest pixel sampling
slouken@5484
   102
 *    "1" or "linear"  - Linear filtering (supported by OpenGL and Direct3D)
slouken@5484
   103
 *    "2" or "best"    - Anisotropic filtering (supported by Direct3D)
slouken@5484
   104
 *
slouken@5484
   105
 *  By default nearest pixel sampling is used
slouken@5484
   106
 */
slouken@5484
   107
#define SDL_HINT_RENDER_SCALE_QUALITY       "SDL_RENDER_SCALE_QUALITY"
slouken@5484
   108
slouken@5484
   109
/**
slouken@5192
   110
 *  \brief  A variable controlling whether updates to the SDL 1.2 screen surface should be synchronized with the vertical refresh, to avoid tearing.
slouken@5192
   111
 *
slouken@5192
   112
 *  This variable can be set to the following values:
slouken@5192
   113
 *    "0"       - Disable vsync
slouken@5192
   114
 *    "1"       - Enable vsync
slouken@5192
   115
 *
slouken@5192
   116
 *  By default SDL does not sync screen surface updates with vertical refresh.
slouken@5192
   117
 */
slouken@5192
   118
#define SDL_HINT_RENDER_VSYNC               "SDL_RENDER_VSYNC"
slouken@6472
   119
slouken@6472
   120
/**
slouken@6472
   121
 *  \brief  A variable controlling whether the X11 VidMode extension should be used.
slouken@6472
   122
 *
slouken@6472
   123
 *  This variable can be set to the following values:
slouken@6472
   124
 *    "0"       - Disable XVidMode
slouken@6472
   125
 *    "1"       - Enable XVidMode
slouken@6472
   126
 *
slouken@6472
   127
 *  By default SDL will use XVidMode if it is available.
slouken@6472
   128
 */
slouken@6472
   129
#define SDL_HINT_VIDEO_X11_XVIDMODE         "SDL_VIDEO_X11_XVIDMODE"
slouken@6472
   130
slouken@6472
   131
/**
slouken@6472
   132
 *  \brief  A variable controlling whether the X11 Xinerama extension should be used.
slouken@6472
   133
 *
slouken@6472
   134
 *  This variable can be set to the following values:
slouken@6472
   135
 *    "0"       - Disable Xinerama
slouken@6472
   136
 *    "1"       - Enable Xinerama
slouken@6472
   137
 *
slouken@6472
   138
 *  By default SDL will use Xinerama if it is available.
slouken@6472
   139
 */
slouken@6472
   140
#define SDL_HINT_VIDEO_X11_XINERAMA         "SDL_VIDEO_X11_XINERAMA"
slouken@6472
   141
slouken@6472
   142
/**
slouken@6472
   143
 *  \brief  A variable controlling whether the X11 XRandR extension should be used.
slouken@6472
   144
 *
slouken@6472
   145
 *  This variable can be set to the following values:
slouken@6472
   146
 *    "0"       - Disable XRandR
slouken@6472
   147
 *    "1"       - Enable XRandR
slouken@6472
   148
 *
slouken@6558
   149
 *  By default SDL will not use XRandR because of window manager issues.
slouken@6472
   150
 */
slouken@6472
   151
#define SDL_HINT_VIDEO_X11_XRANDR           "SDL_VIDEO_X11_XRANDR"
slouken@6472
   152
tim@5554
   153
/**
slouken@6662
   154
 *  \brief  A variable controlling whether grabbing input grabs the keyboard
slouken@6662
   155
 *
slouken@6662
   156
 *  This variable can be set to the following values:
slouken@6662
   157
 *    "0"       - Grab will affect only the mouse
slouken@6662
   158
 *    "1"       - Grab will affect mouse and keyboard
slouken@6662
   159
 *
slouken@6662
   160
 *  By default SDL will not grab the keyboard so system shortcuts still work.
slouken@6662
   161
 */
slouken@6662
   162
#define SDL_HINT_GRAB_KEYBOARD              "SDL_GRAB_KEYBOARD"
slouken@6662
   163
slouken@6662
   164
/**
slouken@6755
   165
 *  \brief Minimize your SDL_Window if it loses key focus when in Fullscreen mode. Defaults to true.
slouken@6755
   166
 *
slouken@6755
   167
 */
slouken@6755
   168
#define SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS   "SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS"
slouken@6755
   169
slouken@7191
   170
slouken@6755
   171
/**
tim@5555
   172
 *  \brief  A variable controlling whether the idle timer is disabled on iOS.
tim@5555
   173
 *
tim@5555
   174
 *  When an iOS app does not receive touches for some time, the screen is
tim@5555
   175
 *  dimmed automatically. For games where the accelerometer is the only input
tim@5555
   176
 *  this is problematic. This functionality can be disabled by setting this
tim@5555
   177
 *  hint.
tim@5555
   178
 *
tim@5555
   179
 *  This variable can be set to the following values:
tim@5555
   180
 *    "0"       - Enable idle timer
tim@5555
   181
 *    "1"       - Disable idle timer
tim@5555
   182
 */
tim@5555
   183
#define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED"
slouken@7191
   184
tim@5555
   185
/**
tim@5554
   186
 *  \brief  A variable controlling which orientations are allowed on iOS.
tim@5554
   187
 *
tim@5554
   188
 *  In some circumstances it is necessary to be able to explicitly control
tim@5554
   189
 *  which UI orientations are allowed.
tim@5554
   190
 *
tim@5554
   191
 *  This variable is a space delimited list of the following values:
tim@5554
   192
 *    "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown"
tim@5554
   193
 */
tim@5554
   194
#define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS"
slouken@5192
   195
slouken@5189
   196
slouken@5189
   197
/**
urkle@6965
   198
 *  \brief  A variable that lets you disable the detection and use of Xinput gamepad devices
urkle@6965
   199
 *
urkle@6965
   200
 *  The variable can be set to the following values:
urkle@6965
   201
 *    "0"       - Disable XInput timer (only uses direct input)
urkle@6965
   202
 *    "1"       - Enable XInput timer (the default)
urkle@6965
   203
 */
icculus@6990
   204
#define SDL_HINT_XINPUT_ENABLED "SDL_XINPUT_ENABLED"
urkle@6965
   205
slouken@6982
   206
urkle@6965
   207
/**
slouken@6690
   208
 *  \brief  A variable that lets you manually hint extra gamecontroller db entries
slouken@7191
   209
 *
slouken@6982
   210
 *  The variable should be newline delimited rows of gamecontroller config data, see SDL_gamecontroller.h
slouken@6980
   211
 *
slouken@6980
   212
 *  This hint must be set before calling SDL_Init(SDL_INIT_GAMECONTROLLER)
slouken@6982
   213
 *  You can update mappings after the system is initialized with SDL_GameControllerMappingForGUID() and SDL_GameControllerAddMapping()
slouken@6690
   214
 */
slouken@6690
   215
#define SDL_HINT_GAMECONTROLLERCONFIG "SDL_GAMECONTROLLERCONFIG"
slouken@6690
   216
slouken@6690
   217
slouken@6690
   218
/**
jorgen@7279
   219
 *  \brief  A variable that lets you enable joystick (and gamecontroller) events even when your app is in the background.
jorgen@7279
   220
 *
jorgen@7279
   221
 * The default value is "0".
jorgen@7279
   222
 *
jorgen@7279
   223
 *  The variable can be set to the following values:
jorgen@7279
   224
 *    "0"       - Disable joystick & gamecontroller input events when the
jorgen@7279
   225
 *                application is in the background.
jorgen@7279
   226
 *    "1"       - Enable joystick & gamecontroller input events when the
jorgen@7279
   227
 *                application is in the backgroumd.
jorgen@7279
   228
 */
jorgen@7279
   229
#define SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS "SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS"
jorgen@7279
   230
jorgen@7279
   231
jorgen@7279
   232
/**
slouken@6782
   233
 *  \brief If set to 0 then never set the top most bit on a SDL Window, even if the video mode expects it.
slouken@7191
   234
 *      This is a debugging aid for developers and not expected to be used by end users. The default is "1"
slouken@6782
   235
 *
slouken@6782
   236
 *  This variable can be set to the following values:
slouken@6782
   237
 *    "0"       - don't allow topmost
slouken@6782
   238
 *    "1"       - allow topmost
slouken@6782
   239
 */
slouken@6782
   240
#define SDL_HINT_ALLOW_TOPMOST "SDL_ALLOW_TOPMOST"
slouken@6782
   241
slouken@6782
   242
slouken@6782
   243
slouken@6782
   244
/**
slouken@5189
   245
 *  \brief  An enumeration of hint priorities
slouken@5189
   246
 */
slouken@5189
   247
typedef enum
slouken@5189
   248
{
slouken@5189
   249
    SDL_HINT_DEFAULT,
slouken@5189
   250
    SDL_HINT_NORMAL,
slouken@5189
   251
    SDL_HINT_OVERRIDE
slouken@5189
   252
} SDL_HintPriority;
slouken@5189
   253
slouken@5189
   254
slouken@5189
   255
/**
slouken@5200
   256
 *  \brief Set a hint with a specific priority
slouken@5189
   257
 *
slouken@5189
   258
 *  The priority controls the behavior when setting a hint that already
slouken@5189
   259
 *  has a value.  Hints will replace existing hints of their priority and
slouken@5189
   260
 *  lower.  Environment variables are considered to have override priority.
slouken@7191
   261
 *
slouken@5189
   262
 *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
slouken@5189
   263
 */
slouken@5200
   264
extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name,
slouken@5200
   265
                                                         const char *value,
slouken@5200
   266
                                                         SDL_HintPriority priority);
slouken@5200
   267
slouken@5200
   268
/**
slouken@5200
   269
 *  \brief Set a hint with normal priority
slouken@7191
   270
 *
slouken@5200
   271
 *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
slouken@5200
   272
 */
slouken@5189
   273
extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
slouken@5200
   274
                                             const char *value);
slouken@5200
   275
slouken@5189
   276
slouken@5189
   277
/**
slouken@5189
   278
 *  \brief Get a hint
slouken@7191
   279
 *
slouken@5189
   280
 *  \return The string value of a hint variable.
slouken@5189
   281
 */
slouken@5189
   282
extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
slouken@5189
   283
slouken@5189
   284
/**
slouken@5189
   285
 *  \brief  Clear all hints
slouken@5189
   286
 *
slouken@5189
   287
 *  This function is called during SDL_Quit() to free stored hints.
slouken@5189
   288
 */
slouken@5272
   289
extern DECLSPEC void SDLCALL SDL_ClearHints(void);
slouken@5189
   290
slouken@5189
   291
slouken@5189
   292
/* Ends C function definitions when using C++ */
slouken@5189
   293
#ifdef __cplusplus
slouken@5189
   294
}
slouken@5189
   295
#endif
slouken@5189
   296
#include "close_code.h"
slouken@5189
   297
slouken@5189
   298
#endif /* _SDL_hints_h */
slouken@5189
   299
slouken@5189
   300
/* vi: set ts=4 sw=4 expandtab: */