include/SDL_hints.h
author Sam Lantinga <slouken@libsdl.org>
Thu, 04 Oct 2012 13:50:41 -0700
changeset 6558 90f231aa77b9
parent 6472 d4623b7209db
child 6662 698c2e533a7e
permissions -rw-r--r--
I'm becoming more and more convinced that the application should never use XRandR, and it's the window manager's responsibility to track and manage display modes for fullscreen windows.
Because it's so broken, I'm going to disable XRandR by default. You can still enable it via environment variable or application hint (SDL_HINT_VIDEO_X11_XRANDR)
slouken@5189
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@6138
     3
  Copyright (C) 1997-2012 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@5189
    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
/* *INDENT-OFF* */
slouken@5189
    48
extern "C" {
slouken@5189
    49
/* *INDENT-ON* */
slouken@5189
    50
#endif
slouken@5189
    51
slouken@5190
    52
/**
slouken@5190
    53
 *  \brief  A variable controlling how 3D acceleration is used to accelerate the SDL 1.2 screen surface. 
slouken@5190
    54
 *
slouken@5190
    55
 *  SDL can try to accelerate the SDL 1.2 screen surface by using streaming
slouken@5190
    56
 *  textures with a 3D rendering engine.  This variable controls whether and
slouken@5190
    57
 *  how this is done.
slouken@5190
    58
 *
slouken@5190
    59
 *  This variable can be set to the following values:
slouken@5190
    60
 *    "0"       - Disable 3D acceleration
slouken@5190
    61
 *    "1"       - Enable 3D acceleration, using the default renderer.
slouken@5190
    62
 *    "X"       - Enable 3D acceleration, using X where X is one of the valid rendering drivers.  (e.g. "direct3d", "opengl", etc.)
slouken@5190
    63
 *
slouken@5190
    64
 *  By default SDL tries to make a best guess for each platform whether
slouken@5190
    65
 *  to use acceleration or not.
slouken@5190
    66
 */
slouken@5190
    67
#define SDL_HINT_FRAMEBUFFER_ACCELERATION   "SDL_FRAMEBUFFER_ACCELERATION"
slouken@5189
    68
slouken@5192
    69
/**
slouken@5192
    70
 *  \brief  A variable specifying which render driver to use.
slouken@5192
    71
 *
slouken@5192
    72
 *  If the application doesn't pick a specific renderer to use, this variable
slouken@5192
    73
 *  specifies the name of the preferred renderer.  If the preferred renderer
slouken@5192
    74
 *  can't be initialized, the normal default renderer is used.
slouken@5192
    75
 *
slouken@5192
    76
 *  This variable is case insensitive and can be set to the following values:
slouken@5192
    77
 *    "direct3d"
slouken@5192
    78
 *    "opengl"
slouken@5233
    79
 *    "opengles2"
slouken@5192
    80
 *    "opengles"
slouken@5192
    81
 *    "software"
slouken@5233
    82
 *
slouken@5233
    83
 *  The default varies by platform, but it's the first one in the list that
slouken@5233
    84
 *  is available on the current platform.
slouken@5192
    85
 */
slouken@5192
    86
#define SDL_HINT_RENDER_DRIVER              "SDL_RENDER_DRIVER"
slouken@5192
    87
slouken@5192
    88
/**
slouken@5233
    89
 *  \brief  A variable controlling whether the OpenGL render driver uses shaders if they are available.
slouken@5233
    90
 *
slouken@5233
    91
 *  This variable can be set to the following values:
slouken@5233
    92
 *    "0"       - Disable shaders
slouken@5233
    93
 *    "1"       - Enable shaders
slouken@5233
    94
 *
slouken@5233
    95
 *  By default shaders are used if OpenGL supports them.
slouken@5233
    96
 */
slouken@5233
    97
#define SDL_HINT_RENDER_OPENGL_SHADERS      "SDL_RENDER_OPENGL_SHADERS"
slouken@5233
    98
slouken@5233
    99
/**
slouken@5484
   100
 *  \brief  A variable controlling the scaling quality
slouken@5484
   101
 *
slouken@5484
   102
 *  This variable can be set to the following values:
slouken@5484
   103
 *    "0" or "nearest" - Nearest pixel sampling
slouken@5484
   104
 *    "1" or "linear"  - Linear filtering (supported by OpenGL and Direct3D)
slouken@5484
   105
 *    "2" or "best"    - Anisotropic filtering (supported by Direct3D)
slouken@5484
   106
 *
slouken@5484
   107
 *  By default nearest pixel sampling is used
slouken@5484
   108
 */
slouken@5484
   109
#define SDL_HINT_RENDER_SCALE_QUALITY       "SDL_RENDER_SCALE_QUALITY"
slouken@5484
   110
slouken@5484
   111
/**
slouken@5192
   112
 *  \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
   113
 *
slouken@5192
   114
 *  This variable can be set to the following values:
slouken@5192
   115
 *    "0"       - Disable vsync
slouken@5192
   116
 *    "1"       - Enable vsync
slouken@5192
   117
 *
slouken@5192
   118
 *  By default SDL does not sync screen surface updates with vertical refresh.
slouken@5192
   119
 */
slouken@5192
   120
#define SDL_HINT_RENDER_VSYNC               "SDL_RENDER_VSYNC"
slouken@6472
   121
slouken@6472
   122
/**
slouken@6472
   123
 *  \brief  A variable controlling whether the X11 VidMode extension should be used.
slouken@6472
   124
 *
slouken@6472
   125
 *  This variable can be set to the following values:
slouken@6472
   126
 *    "0"       - Disable XVidMode
slouken@6472
   127
 *    "1"       - Enable XVidMode
slouken@6472
   128
 *
slouken@6472
   129
 *  By default SDL will use XVidMode if it is available.
slouken@6472
   130
 */
slouken@6472
   131
#define SDL_HINT_VIDEO_X11_XVIDMODE         "SDL_VIDEO_X11_XVIDMODE"
slouken@6472
   132
slouken@6472
   133
/**
slouken@6472
   134
 *  \brief  A variable controlling whether the X11 Xinerama extension should be used.
slouken@6472
   135
 *
slouken@6472
   136
 *  This variable can be set to the following values:
slouken@6472
   137
 *    "0"       - Disable Xinerama
slouken@6472
   138
 *    "1"       - Enable Xinerama
slouken@6472
   139
 *
slouken@6472
   140
 *  By default SDL will use Xinerama if it is available.
slouken@6472
   141
 */
slouken@6472
   142
#define SDL_HINT_VIDEO_X11_XINERAMA         "SDL_VIDEO_X11_XINERAMA"
slouken@6472
   143
slouken@6472
   144
/**
slouken@6472
   145
 *  \brief  A variable controlling whether the X11 XRandR extension should be used.
slouken@6472
   146
 *
slouken@6472
   147
 *  This variable can be set to the following values:
slouken@6472
   148
 *    "0"       - Disable XRandR
slouken@6472
   149
 *    "1"       - Enable XRandR
slouken@6472
   150
 *
slouken@6558
   151
 *  By default SDL will not use XRandR because of window manager issues.
slouken@6472
   152
 */
slouken@6472
   153
#define SDL_HINT_VIDEO_X11_XRANDR           "SDL_VIDEO_X11_XRANDR"
slouken@6472
   154
tim@5554
   155
/**
tim@5555
   156
 *  \brief  A variable controlling whether the idle timer is disabled on iOS.
tim@5555
   157
 *
tim@5555
   158
 *  When an iOS app does not receive touches for some time, the screen is
tim@5555
   159
 *  dimmed automatically. For games where the accelerometer is the only input
tim@5555
   160
 *  this is problematic. This functionality can be disabled by setting this
tim@5555
   161
 *  hint.
tim@5555
   162
 *
tim@5555
   163
 *  This variable can be set to the following values:
tim@5555
   164
 *    "0"       - Enable idle timer
tim@5555
   165
 *    "1"       - Disable idle timer
tim@5555
   166
 */
tim@5555
   167
#define SDL_HINT_IDLE_TIMER_DISABLED "SDL_IOS_IDLE_TIMER_DISABLED"
tim@5555
   168
	
tim@5555
   169
/**
tim@5554
   170
 *  \brief  A variable controlling which orientations are allowed on iOS.
tim@5554
   171
 *
tim@5554
   172
 *  In some circumstances it is necessary to be able to explicitly control
tim@5554
   173
 *  which UI orientations are allowed.
tim@5554
   174
 *
tim@5554
   175
 *  This variable is a space delimited list of the following values:
tim@5554
   176
 *    "LandscapeLeft", "LandscapeRight", "Portrait" "PortraitUpsideDown"
tim@5554
   177
 */
tim@5554
   178
#define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS"
slouken@5192
   179
slouken@5189
   180
slouken@5189
   181
/**
slouken@5189
   182
 *  \brief  An enumeration of hint priorities
slouken@5189
   183
 */
slouken@5189
   184
typedef enum
slouken@5189
   185
{
slouken@5189
   186
    SDL_HINT_DEFAULT,
slouken@5189
   187
    SDL_HINT_NORMAL,
slouken@5189
   188
    SDL_HINT_OVERRIDE
slouken@5189
   189
} SDL_HintPriority;
slouken@5189
   190
slouken@5189
   191
slouken@5189
   192
/**
slouken@5200
   193
 *  \brief Set a hint with a specific priority
slouken@5189
   194
 *
slouken@5189
   195
 *  The priority controls the behavior when setting a hint that already
slouken@5189
   196
 *  has a value.  Hints will replace existing hints of their priority and
slouken@5189
   197
 *  lower.  Environment variables are considered to have override priority.
slouken@5189
   198
 * 
slouken@5189
   199
 *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
slouken@5189
   200
 */
slouken@5200
   201
extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name,
slouken@5200
   202
                                                         const char *value,
slouken@5200
   203
                                                         SDL_HintPriority priority);
slouken@5200
   204
slouken@5200
   205
/**
slouken@5200
   206
 *  \brief Set a hint with normal priority
slouken@5200
   207
 * 
slouken@5200
   208
 *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
slouken@5200
   209
 */
slouken@5189
   210
extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
slouken@5200
   211
                                             const char *value);
slouken@5200
   212
slouken@5189
   213
slouken@5189
   214
/**
slouken@5189
   215
 *  \brief Get a hint
slouken@5189
   216
 *  
slouken@5189
   217
 *  \return The string value of a hint variable.
slouken@5189
   218
 */
slouken@5189
   219
extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
slouken@5189
   220
slouken@5189
   221
/**
slouken@5189
   222
 *  \brief  Clear all hints
slouken@5189
   223
 *
slouken@5189
   224
 *  This function is called during SDL_Quit() to free stored hints.
slouken@5189
   225
 */
slouken@5272
   226
extern DECLSPEC void SDLCALL SDL_ClearHints(void);
slouken@5189
   227
slouken@5189
   228
slouken@5189
   229
/* Ends C function definitions when using C++ */
slouken@5189
   230
#ifdef __cplusplus
slouken@5189
   231
/* *INDENT-OFF* */
slouken@5189
   232
}
slouken@5189
   233
/* *INDENT-ON* */
slouken@5189
   234
#endif
slouken@5189
   235
#include "close_code.h"
slouken@5189
   236
slouken@5189
   237
#endif /* _SDL_hints_h */
slouken@5189
   238
slouken@5189
   239
/* vi: set ts=4 sw=4 expandtab: */