neo/framework/CVarSystem.h

   1 /*
   2 ===========================================================================
   3
   4 Doom 3 GPL Source Code
   5 Copyright (C) 1999-2011 id Software LLC, a ZeniMax Media company.
   6
   7 This file is part of the Doom 3 GPL Source Code (?Doom 3 Source Code?).
   8
   9 Doom 3 Source Code is free software: you can redistribute it and/or modify
  10 it under the terms of the GNU General Public License as published by
  11 the Free Software Foundation, either version 3 of the License, or
  12 (at your option) any later version.
  13
  14 Doom 3 Source Code is distributed in the hope that it will be useful,
  15 but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 GNU General Public License for more details.
  18
  19 You should have received a copy of the GNU General Public License
  20 along with Doom 3 Source Code.  If not, see <http://www.gnu.org/licenses/>.
  21
  22 In addition, the Doom 3 Source Code is also subject to certain additional terms. You should have received a copy of these additional terms immediately following the terms and conditions of the GNU General Public License which accompanied the Doom 3 Source Code.  If not, please request a copy in writing from id Software at the address below.
  23
  24 If you have questions concerning this license or the applicable additional terms, you may contact in writing id Software LLC, c/o ZeniMax Media Inc., Suite 120, Rockville, Maryland 20850 USA.
  25
  26 ===========================================================================
  27 */
  28
  29 #ifndef __CVARSYSTEM_H__
  30 #define __CVARSYSTEM_H__
  31
  32 /*
  33 ===============================================================================
  34
  35         Console Variables (CVars) are used to hold scalar or string variables
  36         that can be changed or displayed at the console as well as accessed
  37         directly in code.
  38
  39         CVars are mostly used to hold settings that can be changed from the
  40         console or saved to and loaded from configuration files. CVars are also
  41         occasionally used to communicate information between different modules
  42         of the program.
  43
  44         CVars are restricted from having the same names as console commands to
  45         keep the console interface from being ambiguous.
  46
  47         CVars can be accessed from the console in three ways:
  48         cvarName                        prints the current value
  49         cvarName X                      sets the value to X if the variable exists
  50         set cvarName X          as above, but creates the CVar if not present
  51
  52         CVars may be declared in the global namespace, in classes and in functions.
  53         However declarations in classes and functions should always be static to
  54         save space and time. Making CVars static does not change their
  55         functionality due to their global nature.
  56
  57         CVars should be contructed only through one of the constructors with name,
  58         value, flags and description. The name, value and description parameters
  59         to the constructor have to be static strings, do not use va() or the like
  60         functions returning a string.
  61
  62         CVars may be declared multiple times using the same name string. However,
  63         they will all reference the same value and changing the value of one CVar
  64         changes the value of all CVars with the same name.
  65
  66         CVars should always be declared with the correct type flag: CVAR_BOOL,
  67         CVAR_INTEGER or CVAR_FLOAT. If no such flag is specified the CVar
  68         defaults to type string. If the CVAR_BOOL flag is used there is no need
  69         to specify an argument auto-completion function because the CVar gets
  70         one assigned automatically.
  71
  72         CVars are automatically range checked based on their type and any min/max
  73         or valid string set specified in the constructor.
  74
  75         CVars are always considered cheats except when CVAR_NOCHEAT, CVAR_INIT,
  76         CVAR_ROM, CVAR_ARCHIVE, CVAR_USERINFO, CVAR_SERVERINFO, CVAR_NETWORKSYNC
  77         is set.
  78
  79 ===============================================================================
  80 */
  81
  82 typedef enum {
  83         CVAR_ALL                                = -1,           // all flags
  84         CVAR_BOOL                               = BIT(0),       // variable is a boolean
  85         CVAR_INTEGER                    = BIT(1),       // variable is an integer
  86         CVAR_FLOAT                              = BIT(2),       // variable is a float
  87         CVAR_SYSTEM                             = BIT(3),       // system variable
  88         CVAR_RENDERER                   = BIT(4),       // renderer variable
  89         CVAR_SOUND                              = BIT(5),       // sound variable
  90         CVAR_GUI                                = BIT(6),       // gui variable
  91         CVAR_GAME                               = BIT(7),       // game variable
  92         CVAR_TOOL                               = BIT(8),       // tool variable
  93         CVAR_USERINFO                   = BIT(9),       // sent to servers, available to menu
  94         CVAR_SERVERINFO                 = BIT(10),      // sent from servers, available to menu
  95         CVAR_NETWORKSYNC                = BIT(11),      // cvar is synced from the server to clients
  96         CVAR_STATIC                             = BIT(12),      // statically declared, not user created
  97         CVAR_CHEAT                              = BIT(13),      // variable is considered a cheat
  98         CVAR_NOCHEAT                    = BIT(14),      // variable is not considered a cheat
  99         CVAR_INIT                               = BIT(15),      // can only be set from the command-line
 100         CVAR_ROM                                = BIT(16),      // display only, cannot be set by user at all
 101         CVAR_ARCHIVE                    = BIT(17),      // set to cause it to be saved to a config file
 102         CVAR_MODIFIED                   = BIT(18)       // set when the variable is modified
 103 } cvarFlags_t;
 104
 105
 106 /*
 107 ===============================================================================
 108
 109         idCVar
 110
 111 ===============================================================================
 112 */
 113
 114 class idCVar {
 115 public:
 116                                                         // Never use the default constructor.
 117                                                         idCVar( void ) { assert( typeid( this ) != typeid( idCVar ) ); }
 118
 119                                                         // Always use one of the following constructors.
 120                                                         idCVar( const char *name, const char *value, int flags, const char *description,
 121                                                                         argCompletion_t valueCompletion = NULL );
 122                                                         idCVar( const char *name, const char *value, int flags, const char *description,
 123                                                                         float valueMin, float valueMax, argCompletion_t valueCompletion = NULL );
 124                                                         idCVar( const char *name, const char *value, int flags, const char *description,
 125                                                                         const char **valueStrings, argCompletion_t valueCompletion = NULL );
 126
 127         virtual                                 ~idCVar( void ) {}
 128
 129         const char *                    GetName( void ) const { return internalVar->name; }
 130         int                                             GetFlags( void ) const { return internalVar->flags; }
 131         const char *                    GetDescription( void ) const { return internalVar->description; }
 132         float                                   GetMinValue( void ) const { return internalVar->valueMin; }
 133         float                                   GetMaxValue( void ) const { return internalVar->valueMax; }
 134         const char **                   GetValueStrings( void ) const { return valueStrings; }
 135         argCompletion_t                 GetValueCompletion( void ) const { return valueCompletion; }
 136
 137         bool                                    IsModified( void ) const { return ( internalVar->flags & CVAR_MODIFIED ) != 0; }
 138         void                                    SetModified( void ) { internalVar->flags |= CVAR_MODIFIED; }
 139         void                                    ClearModified( void ) { internalVar->flags &= ~CVAR_MODIFIED; }
 140
 141         const char *                    GetString( void ) const { return internalVar->value; }
 142         bool                                    GetBool( void ) const { return ( internalVar->integerValue != 0 ); }
 143         int                                             GetInteger( void ) const { return internalVar->integerValue; }
 144         float                                   GetFloat( void ) const { return internalVar->floatValue; }
 145
 146         void                                    SetString( const char *value ) { internalVar->InternalSetString( value ); }
 147         void                                    SetBool( const bool value ) { internalVar->InternalSetBool( value ); }
 148         void                                    SetInteger( const int value ) { internalVar->InternalSetInteger( value ); }
 149         void                                    SetFloat( const float value ) { internalVar->InternalSetFloat( value ); }
 150
 151         void                                    SetInternalVar( idCVar *cvar ) { internalVar = cvar; }
 152
 153         static void                             RegisterStaticVars( void );
 154
 155 protected:
 156         const char *                    name;                                   // name
 157         const char *                    value;                                  // value
 158         const char *                    description;                    // description
 159         int                                             flags;                                  // CVAR_? flags
 160         float                                   valueMin;                               // minimum value
 161         float                                   valueMax;                               // maximum value
 162         const char **                   valueStrings;                   // valid value strings
 163         argCompletion_t                 valueCompletion;                // value auto-completion function
 164         int                                             integerValue;                   // atoi( string )
 165         float                                   floatValue;                             // atof( value )
 166         idCVar *                                internalVar;                    // internal cvar
 167         idCVar *                                next;                                   // next statically declared cvar
 168
 169 private:
 170         void                                    Init( const char *name, const char *value, int flags, const char *description,
 171                                                                         float valueMin, float valueMax, const char **valueStrings, argCompletion_t valueCompletion );
 172
 173         virtual void                    InternalSetString( const char *newValue ) {}
 174         virtual void                    InternalSetBool( const bool newValue ) {}
 175         virtual void                    InternalSetInteger( const int newValue ) {}
 176         virtual void                    InternalSetFloat( const float newValue ) {}
 177
 178         static idCVar *                 staticVars;
 179 };
 180
 181 ID_INLINE idCVar::idCVar( const char *name, const char *value, int flags, const char *description,
 182                                                         argCompletion_t valueCompletion ) {
 183         if ( !valueCompletion && ( flags & CVAR_BOOL ) ) {
 184                 valueCompletion = idCmdSystem::ArgCompletion_Boolean;
 185         }
 186         Init( name, value, flags, description, 1, -1, NULL, valueCompletion );
 187 }
 188
 189 ID_INLINE idCVar::idCVar( const char *name, const char *value, int flags, const char *description,
 190                                                         float valueMin, float valueMax, argCompletion_t valueCompletion ) {
 191         Init( name, value, flags, description, valueMin, valueMax, NULL, valueCompletion );
 192 }
 193
 194 ID_INLINE idCVar::idCVar( const char *name, const char *value, int flags, const char *description,
 195                                                         const char **valueStrings, argCompletion_t valueCompletion ) {
 196         Init( name, value, flags, description, 1, -1, valueStrings, valueCompletion );
 197 }
 198
 199
 200 /*
 201 ===============================================================================
 202
 203         idCVarSystem
 204
 205 ===============================================================================
 206 */
 207
 208 class idCVarSystem {
 209 public:
 210         virtual                                 ~idCVarSystem( void ) {}
 211
 212         virtual void                    Init( void ) = 0;
 213         virtual void                    Shutdown( void ) = 0;
 214         virtual bool                    IsInitialized( void ) const = 0;
 215
 216                                                         // Registers a CVar.
 217         virtual void                    Register( idCVar *cvar ) = 0;
 218
 219                                                         // Finds the CVar with the given name.
 220                                                         // Returns NULL if there is no CVar with the given name.
 221         virtual idCVar *                Find( const char *name ) = 0;
 222
 223                                                         // Sets the value of a CVar by name.
 224         virtual void                    SetCVarString( const char *name, const char *value, int flags = 0 ) = 0;
 225         virtual void                    SetCVarBool( const char *name, const bool value, int flags = 0 ) = 0;
 226         virtual void                    SetCVarInteger( const char *name, const int value, int flags = 0 ) = 0;
 227         virtual void                    SetCVarFloat( const char *name, const float value, int flags = 0 ) = 0;
 228
 229                                                         // Gets the value of a CVar by name.
 230         virtual const char *    GetCVarString( const char *name ) const = 0;
 231         virtual bool                    GetCVarBool( const char *name ) const = 0;
 232         virtual int                             GetCVarInteger( const char *name ) const = 0;
 233         virtual float                   GetCVarFloat( const char *name ) const = 0;
 234
 235                                                         // Called by the command system when argv(0) doesn't match a known command.
 236                                                         // Returns true if argv(0) is a variable reference and prints or changes the CVar.
 237         virtual bool                    Command( const idCmdArgs &args ) = 0;
 238
 239                                                         // Command and argument completion using callback for each valid string.
 240         virtual void                    CommandCompletion( void(*callback)( const char *s ) ) = 0;
 241         virtual void                    ArgCompletion( const char *cmdString, void(*callback)( const char *s ) ) = 0;
 242
 243                                                         // Sets/gets/clears modified flags that tell what kind of CVars have changed.
 244         virtual void                    SetModifiedFlags( int flags ) = 0;
 245         virtual int                             GetModifiedFlags( void ) const = 0;
 246         virtual void                    ClearModifiedFlags( int flags ) = 0;
 247
 248                                                         // Resets variables with one of the given flags set.
 249         virtual void                    ResetFlaggedVariables( int flags ) = 0;
 250
 251                                                         // Removes auto-completion from the flagged variables.
 252         virtual void                    RemoveFlaggedAutoCompletion( int flags ) = 0;
 253
 254                                                         // Writes variables with one of the given flags set to the given file.
 255         virtual void                    WriteFlaggedVariables( int flags, const char *setCmd, idFile *f ) const = 0;
 256
 257                                                         // Moves CVars to and from dictionaries.
 258         virtual const idDict *  MoveCVarsToDict( int flags ) const = 0;
 259         virtual void                    SetCVarsFromDict( const idDict &dict ) = 0;
 260 };
 261
 262 extern idCVarSystem *           cvarSystem;
 263
 264
 265 /*
 266 ===============================================================================
 267
 268         CVar Registration
 269
 270         Each DLL using CVars has to declare a private copy of the static variable
 271         idCVar::staticVars like this: idCVar * idCVar::staticVars = NULL;
 272         Furthermore idCVar::RegisterStaticVars() has to be called after the
 273         cvarSystem pointer is set when the DLL is first initialized.
 274
 275 ===============================================================================
 276 */
 277
 278 ID_INLINE void idCVar::Init( const char *name, const char *value, int flags, const char *description,
 279                                                         float valueMin, float valueMax, const char **valueStrings, argCompletion_t valueCompletion ) {
 280         this->name = name;
 281         this->value = value;
 282         this->flags = flags;
 283         this->description = description;
 284         this->flags = flags | CVAR_STATIC;
 285         this->valueMin = valueMin;
 286         this->valueMax = valueMax;
 287         this->valueStrings = valueStrings;
 288         this->valueCompletion = valueCompletion;
 289         this->integerValue = 0;
 290         this->floatValue = 0.0f;
 291         this->internalVar = this;
 292         if ( staticVars != (idCVar *)0xFFFFFFFF ) {
 293                 this->next = staticVars;
 294                 staticVars = this;
 295         } else {
 296                 cvarSystem->Register( this );
 297         }
 298 }
 299
 300 ID_INLINE void idCVar::RegisterStaticVars( void ) {
 301         if ( staticVars != (idCVar *)0xFFFFFFFF ) {
 302                 for ( idCVar *cvar = staticVars; cvar; cvar = cvar->next ) {
 303                         cvarSystem->Register( cvar );
 304                 }
 305                 staticVars = (idCVar *)0xFFFFFFFF;
 306         }
 307 }
 308
 309 #endif /* !__CVARSYSTEM_H__ */