Added a hint system to allow configuration hints to be specified by the application.
authorSam Lantinga <slouken@libsdl.org>
Sat, 05 Feb 2011 10:02:39 -0800
changeset 51896f6a9340fb93
parent 5188 59e0688d766f
child 5190 82a48f4d65f6
Added a hint system to allow configuration hints to be specified by the application.
Makefile.in
include/SDL.h
include/SDL_hints.h
src/SDL.c
src/SDL_hints.c
     1.1 --- a/Makefile.in	Sat Feb 05 01:03:51 2011 -0800
     1.2 +++ b/Makefile.in	Sat Feb 05 10:02:39 2011 -0800
     1.3 @@ -53,6 +53,7 @@
     1.4  	SDL_events.h \
     1.5  	SDL_gesture.h \
     1.6  	SDL_haptic.h \
     1.7 +	SDL_hints.h \
     1.8  	SDL_input.h \
     1.9  	SDL_joystick.h \
    1.10  	SDL_keyboard.h \
     2.1 --- a/include/SDL.h	Sat Feb 05 01:03:51 2011 -0800
     2.2 +++ b/include/SDL.h	Sat Feb 05 10:02:39 2011 -0800
     2.3 @@ -79,6 +79,7 @@
     2.4  #include "SDL_endian.h"
     2.5  #include "SDL_error.h"
     2.6  #include "SDL_events.h"
     2.7 +#include "SDL_hints.h"
     2.8  #include "SDL_loadso.h"
     2.9  #include "SDL_mutex.h"
    2.10  #include "SDL_power.h"
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/include/SDL_hints.h	Sat Feb 05 10:02:39 2011 -0800
     3.3 @@ -0,0 +1,104 @@
     3.4 +/*
     3.5 +    SDL - Simple DihintsMedia Layer
     3.6 +    Copyright (C) 1997-2010 Sam Lantinga
     3.7 +
     3.8 +    This library is free software; you can redistribute it and/or
     3.9 +    modify it under the terms of the GNU Lesser General Public
    3.10 +    License as published by the Free Software Foundation; either
    3.11 +    version 2.1 of the License, or (at your option) any later version.
    3.12 +
    3.13 +    This library is distributed in the hope that it will be useful,
    3.14 +    but WITHOUT ANY WARRANTY; without even the implied warranty of
    3.15 +    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    3.16 +    Lesser General Public License for more details.
    3.17 +
    3.18 +    You should have received a copy of the GNU Lesser General Public
    3.19 +    License along with this library; if not, write to the Free Software
    3.20 +    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    3.21 +
    3.22 +    Sam Lantinga
    3.23 +    slouken@libsdl.org
    3.24 +*/
    3.25 +
    3.26 +/**
    3.27 + *  \file SDL_hints.h
    3.28 + *  
    3.29 + *  Official documentation for SDL configuration variables
    3.30 + *
    3.31 + *  This file contains functions to set and get configuration hints,
    3.32 + *  as well as listing each of them alphabetically.
    3.33 + *
    3.34 + *  The convention for naming hints is SDL_HINT_X, where "SDL_X" is
    3.35 + *  the environment variable that can be used to override the default.
    3.36 + *
    3.37 + *  In general these hints are just that - they may or may not be
    3.38 + *  supported or applicable on any given platform, but they provide
    3.39 + *  a way for an application or user to give the library a hint as
    3.40 + *  to how they would like the library to work.
    3.41 + */
    3.42 +
    3.43 +#ifndef _SDL_hints_h
    3.44 +#define _SDL_hints_h
    3.45 +
    3.46 +#include "SDL_stdinc.h"
    3.47 +
    3.48 +#include "begin_code.h"
    3.49 +/* Set up for C function definitions, even when using C++ */
    3.50 +#ifdef __cplusplus
    3.51 +/* *INDENT-OFF* */
    3.52 +extern "C" {
    3.53 +/* *INDENT-ON* */
    3.54 +#endif
    3.55 +
    3.56 +
    3.57 +
    3.58 +/**
    3.59 + *  \brief  An enumeration of hint priorities
    3.60 + */
    3.61 +typedef enum
    3.62 +{
    3.63 +    SDL_HINT_DEFAULT,
    3.64 +    SDL_HINT_NORMAL,
    3.65 +    SDL_HINT_OVERRIDE
    3.66 +} SDL_HintPriority;
    3.67 +
    3.68 +
    3.69 +/**
    3.70 + *  \brief Set a hint
    3.71 + *
    3.72 + *  The priority controls the behavior when setting a hint that already
    3.73 + *  has a value.  Hints will replace existing hints of their priority and
    3.74 + *  lower.  Environment variables are considered to have override priority.
    3.75 + * 
    3.76 + *  \return SDL_TRUE if the hint was set, SDL_FALSE otherwise
    3.77 + */
    3.78 +extern DECLSPEC SDL_bool SDLCALL SDL_SetHint(const char *name,
    3.79 +                                             const char *value,
    3.80 +                                             SDL_HintPriority priority);
    3.81 +
    3.82 +/**
    3.83 + *  \brief Get a hint
    3.84 + *  
    3.85 + *  \return The string value of a hint variable.
    3.86 + */
    3.87 +extern DECLSPEC const char * SDLCALL SDL_GetHint(const char *name);
    3.88 +
    3.89 +/**
    3.90 + *  \brief  Clear all hints
    3.91 + *
    3.92 + *  This function is called during SDL_Quit() to free stored hints.
    3.93 + */
    3.94 +extern DECLSPEC void SDLCALL SDL_ClearHints();
    3.95 +
    3.96 +
    3.97 +/* Ends C function definitions when using C++ */
    3.98 +#ifdef __cplusplus
    3.99 +/* *INDENT-OFF* */
   3.100 +}
   3.101 +/* *INDENT-ON* */
   3.102 +#endif
   3.103 +#include "close_code.h"
   3.104 +
   3.105 +#endif /* _SDL_hints_h */
   3.106 +
   3.107 +/* vi: set ts=4 sw=4 expandtab: */
     4.1 --- a/src/SDL.c	Sat Feb 05 01:03:51 2011 -0800
     4.2 +++ b/src/SDL.c	Sat Feb 05 10:02:39 2011 -0800
     4.3 @@ -246,6 +246,7 @@
     4.4      /* Uninstall any parachute signal handlers */
     4.5      SDL_UninstallParachute();
     4.6  
     4.7 +    SDL_ClearHints();
     4.8      SDL_AssertionsQuit();
     4.9  
    4.10  #ifdef DEBUG_BUILD
     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/src/SDL_hints.c	Sat Feb 05 10:02:39 2011 -0800
     5.3 @@ -0,0 +1,115 @@
     5.4 +/*
     5.5 +    SDL - Simple DirectMedia Layer
     5.6 +    Copyright (C) 1997-2010 Sam Lantinga
     5.7 +
     5.8 +    This library is free software; you can redistribute it and/or
     5.9 +    modify it under the terms of the GNU Lesser General Public
    5.10 +    License as published by the Free Software Foundation; either
    5.11 +    version 2.1 of the License, or (at your option) any later version.
    5.12 +
    5.13 +    This library is distributed in the hope that it will be useful,
    5.14 +    but WITHOUT ANY WARRANTY; without even the implied warranty of
    5.15 +    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    5.16 +    Lesser General Public License for more details.
    5.17 +
    5.18 +    You should have received a copy of the GNU Lesser General Public
    5.19 +    License along with this library; if not, write to the Free Software
    5.20 +    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    5.21 +
    5.22 +    Sam Lantinga
    5.23 +    slouken@libsdl.org
    5.24 +*/
    5.25 +#include "SDL_config.h"
    5.26 +
    5.27 +#include "SDL_hints.h"
    5.28 +
    5.29 +
    5.30 +/* Assuming there aren't many hints set and they aren't being queried in
    5.31 +   critical performance paths, we'll just use a linked list here.
    5.32 + */
    5.33 +typedef struct SDL_Hint {
    5.34 +    char *name;
    5.35 +    char *value;
    5.36 +    SDL_HintPriority priority;
    5.37 +    struct SDL_Hint *next;
    5.38 +} SDL_Hint;
    5.39 +
    5.40 +static SDL_Hint *SDL_hints;
    5.41 +
    5.42 +
    5.43 +SDL_bool
    5.44 +SDL_SetHint(const char *name, const char *value, SDL_HintPriority priority)
    5.45 +{
    5.46 +    const char *env;
    5.47 +    SDL_Hint *prev, *hint;
    5.48 +
    5.49 +    if (!name || !value) {
    5.50 +        return SDL_FALSE;
    5.51 +    }
    5.52 +
    5.53 +    env = SDL_getenv(name);
    5.54 +    if (env && priority < SDL_HINT_OVERRIDE) {
    5.55 +        return SDL_FALSE;
    5.56 +    }
    5.57 +
    5.58 +    prev = NULL;
    5.59 +    for (hint = SDL_hints; hint; prev = hint, hint = hint->next) {
    5.60 +        if (SDL_strcmp(name, hint->name) == 0) {
    5.61 +            if (priority < hint->priority) {
    5.62 +                return SDL_FALSE;
    5.63 +            }
    5.64 +            if (SDL_strcmp(hint->value, value) != 0) {
    5.65 +                SDL_free(hint->value);
    5.66 +                hint->value = SDL_strdup(value);
    5.67 +            }
    5.68 +            hint->priority = priority;
    5.69 +            return SDL_TRUE;
    5.70 +        }
    5.71 +    }
    5.72 +
    5.73 +    /* Couldn't find the hint, add a new one */
    5.74 +    hint = (SDL_Hint *)SDL_malloc(sizeof(*hint));
    5.75 +    if (!hint) {
    5.76 +        return SDL_FALSE;
    5.77 +    }
    5.78 +    hint->name = SDL_strdup(name);
    5.79 +    hint->value = SDL_strdup(value);
    5.80 +    hint->priority = priority;
    5.81 +    hint->next = SDL_hints;
    5.82 +    SDL_hints = hint;
    5.83 +    return SDL_TRUE;
    5.84 +}
    5.85 +
    5.86 +const char *
    5.87 +SDL_GetHint(const char *name)
    5.88 +{
    5.89 +    const char *env;
    5.90 +    SDL_Hint *hint;
    5.91 +
    5.92 +    env = SDL_getenv(name);
    5.93 +    for (hint = SDL_hints; hint; hint = hint->next) {
    5.94 +        if (SDL_strcmp(name, hint->name) == 0) {
    5.95 +            if (!env || hint->priority == SDL_HINT_OVERRIDE) {
    5.96 +                return hint->value;
    5.97 +            }
    5.98 +            break;
    5.99 +        }
   5.100 +    }
   5.101 +    return env;
   5.102 +}
   5.103 +
   5.104 +void SDL_ClearHints()
   5.105 +{
   5.106 +    SDL_Hint *hint;
   5.107 +
   5.108 +    while (SDL_hints) {
   5.109 +        hint = SDL_hints;
   5.110 +        SDL_hints = hint->next;
   5.111 +
   5.112 +        SDL_free(hint->name);
   5.113 +        SDL_free(hint->value);
   5.114 +        SDL_free(hint);
   5.115 +    }
   5.116 +}
   5.117 +
   5.118 +/* vi: set ts=4 sw=4 expandtab: */