include/SDL_hints.h
author Sam Lantinga <slouken@libsdl.org>
Sun, 13 Mar 2011 11:18:35 -0700
changeset 5484 e20c93bc9122
parent 5272 3c94c559f5c2
child 5535 96594ac5fd1a
permissions -rw-r--r--
Added the SDL_HINT_RENDER_SCALE_QUALITY hint, which defaults to nearest pixel sampling.
     1 /*
     2     SDL - Simple DihintsMedia Layer
     3     Copyright (C) 1997-2011 Sam Lantinga
     4 
     5     This library is free software; you can redistribute it and/or
     6     modify it under the terms of the GNU Lesser General Public
     7     License as published by the Free Software Foundation; either
     8     version 2.1 of the License, or (at your option) any later version.
     9 
    10     This library is distributed in the hope that it will be useful,
    11     but WITHOUT ANY WARRANTY; without even the implied warranty of
    12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    13     Lesser General Public License for more details.
    14 
    15     You should have received a copy of the GNU Lesser General Public
    16     License along with this library; if not, write to the Free Software
    17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    18 
    19     Sam Lantinga
    20     slouken@libsdl.org
    21 */
    22 
    23 /**
    24  *  \file SDL_hints.h
    25  *  
    26  *  Official documentation for SDL configuration variables
    27  *
    28  *  This file contains functions to set and get configuration hints,
    29  *  as well as listing each of them alphabetically.
    30  *
    31  *  The convention for naming hints is SDL_HINT_X, where "SDL_X" is
    32  *  the environment variable that can be used to override the default.
    33  *
    34  *  In general these hints are just that - they may or may not be
    35  *  supported or applicable on any given platform, but they provide
    36  *  a way for an application or user to give the library a hint as
    37  *  to how they would like the library to work.
    38  */
    39 
    40 #ifndef _SDL_hints_h
    41 #define _SDL_hints_h
    42 
    43 #include "SDL_stdinc.h"
    44 
    45 #include "begin_code.h"
    46 /* Set up for C function definitions, even when using C++ */
    47 #ifdef __cplusplus
    48 /* *INDENT-OFF* */
    49 extern "C" {
    50 /* *INDENT-ON* */
    51 #endif
    52 
    53 /**
    54  *  \brief  A variable controlling how 3D acceleration is used to accelerate the SDL 1.2 screen surface. 
    55  *
    56  *  SDL can try to accelerate the SDL 1.2 screen surface by using streaming
    57  *  textures with a 3D rendering engine.  This variable controls whether and
    58  *  how this is done.
    59  *
    60  *  This variable can be set to the following values:
    61  *    "0"       - Disable 3D acceleration
    62  *    "1"       - Enable 3D acceleration, using the default renderer.
    63  *    "X"       - Enable 3D acceleration, using X where X is one of the valid rendering drivers.  (e.g. "direct3d", "opengl", etc.)
    64  *
    65  *  By default SDL tries to make a best guess for each platform whether
    66  *  to use acceleration or not.
    67  */
    68 #define SDL_HINT_FRAMEBUFFER_ACCELERATION   "SDL_FRAMEBUFFER_ACCELERATION"
    69 
    70 /**
    71  *  \brief  A variable specifying which render driver to use.
    72  *
    73  *  If the application doesn't pick a specific renderer to use, this variable
    74  *  specifies the name of the preferred renderer.  If the preferred renderer
    75  *  can't be initialized, the normal default renderer is used.
    76  *
    77  *  This variable is case insensitive and can be set to the following values:
    78  *    "direct3d"
    79  *    "opengl"
    80  *    "opengles2"
    81  *    "opengles"
    82  *    "software"
    83  *
    84  *  The default varies by platform, but it's the first one in the list that
    85  *  is available on the current platform.
    86  */
    87 #define SDL_HINT_RENDER_DRIVER              "SDL_RENDER_DRIVER"
    88 
    89 /**
    90  *  \brief  A variable controlling whether the OpenGL render driver uses shaders if they are available.
    91  *
    92  *  This variable can be set to the following values:
    93  *    "0"       - Disable shaders
    94  *    "1"       - Enable shaders
    95  *
    96  *  By default shaders are used if OpenGL supports them.
    97  */
    98 #define SDL_HINT_RENDER_OPENGL_SHADERS      "SDL_RENDER_OPENGL_SHADERS"
    99 
   100 /**
   101  *  \brief  A variable controlling the scaling quality
   102  *
   103  *  This variable can be set to the following values:
   104  *    "0" or "nearest" - Nearest pixel sampling
   105  *    "1" or "linear"  - Linear filtering (supported by OpenGL and Direct3D)
   106  *    "2" or "best"    - Anisotropic filtering (supported by Direct3D)
   107  *
   108  *  By default nearest pixel sampling is used
   109  */
   110 #define SDL_HINT_RENDER_SCALE_QUALITY       "SDL_RENDER_SCALE_QUALITY"
   111 
   112 /**
   113  *  \brief  A variable controlling whether updates to the SDL 1.2 screen surface should be synchronized with the vertical refresh, to avoid tearing.
   114  *
   115  *  This variable can be set to the following values:
   116  *    "0"       - Disable vsync
   117  *    "1"       - Enable vsync
   118  *
   119  *  By default SDL does not sync screen surface updates with vertical refresh.
   120  */
   121 #define SDL_HINT_RENDER_VSYNC               "SDL_RENDER_VSYNC"
   122 
   123 
   124 /**
   125  *  \brief  An enumeration of hint priorities
   126  */
   127 typedef enum
   128 {
   129     SDL_HINT_DEFAULT,
   130     SDL_HINT_NORMAL,
   131     SDL_HINT_OVERRIDE
   132 } SDL_HintPriority;
   133 
   134 
   135 /**
   136  *  \brief Set a hint with a specific priority
   137  *
   138  *  The priority controls the behavior when setting a hint that already
   139  *  has a value.  Hints will replace existing hints of their priority and
   140  *  lower.  Environment variables are considered to have override priority.
   141  * 
   142  *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
   143  */
   144 extern DECLSPEC SDL_bool SDLCALL SDL_SetHintWithPriority(const char *name,
   145                                                          const char *value,
   146                                                          SDL_HintPriority priority);
   147 
   148 /**
   149  *  \brief Set a hint with normal priority
   150  * 
   151  *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
   152  */
   153 extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
   154                                              const char *value);
   155 
   156 
   157 /**
   158  *  \brief Get a hint
   159  *  
   160  *  \return The string value of a hint variable.
   161  */
   162 extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
   163 
   164 /**
   165  *  \brief  Clear all hints
   166  *
   167  *  This function is called during SDL_Quit() to free stored hints.
   168  */
   169 extern DECLSPEC void SDLCALL SDL_ClearHints(void);
   170 
   171 
   172 /* Ends C function definitions when using C++ */
   173 #ifdef __cplusplus
   174 /* *INDENT-OFF* */
   175 }
   176 /* *INDENT-ON* */
   177 #endif
   178 #include "close_code.h"
   179 
   180 #endif /* _SDL_hints_h */
   181 
   182 /* vi: set ts=4 sw=4 expandtab: */