include/SDL_hints.h
author Sam Lantinga <slouken@libsdl.org>
Sat, 05 Feb 2011 10:02:39 -0800
changeset 5189 6f6a9340fb93
child 5190 82a48f4d65f6
permissions -rw-r--r--
Added a hint system to allow configuration hints to be specified by the application.
     1 /*
     2     SDL - Simple DihintsMedia Layer
     3     Copyright (C) 1997-2010 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 
    55 /**
    56  *  \brief  An enumeration of hint priorities
    57  */
    58 typedef enum
    59 {
    60     SDL_HINT_DEFAULT,
    61     SDL_HINT_NORMAL,
    62     SDL_HINT_OVERRIDE
    63 } SDL_HintPriority;
    64 
    65 
    66 /**
    67  *  \brief Set a hint
    68  *
    69  *  The priority controls the behavior when setting a hint that already
    70  *  has a value.  Hints will replace existing hints of their priority and
    71  *  lower.  Environment variables are considered to have override priority.
    72  * 
    73  *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
    74  */
    75 extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
    76                                              const char *value,
    77                                              SDL_HintPriority priority);
    78 
    79 /**
    80  *  \brief Get a hint
    81  *  
    82  *  \return The string value of a hint variable.
    83  */
    84 extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
    85 
    86 /**
    87  *  \brief  Clear all hints
    88  *
    89  *  This function is called during SDL_Quit() to free stored hints.
    90  */
    91 extern DECLSPEC void SDLCALL SDL_ClearHints();
    92 
    93 
    94 /* Ends C function definitions when using C++ */
    95 #ifdef __cplusplus
    96 /* *INDENT-OFF* */
    97 }
    98 /* *INDENT-ON* */
    99 #endif
   100 #include "close_code.h"
   101 
   102 #endif /* _SDL_hints_h */
   103 
   104 /* vi: set ts=4 sw=4 expandtab: */