Configuration Variables
-----------------------

  $Id: cvar.txt,v 1.6 2003/04/06 12:20:51 knghtbrd Exp $

  The Configuration Variable system used in Project Twilight is a more
  dynamic version of the Console Variable system used by NQ/QW.  It's fair
  to say that it more resembles the Cvar code used by Q3A, though it is a
  bit more flexible than that.  Here's the structure declaration:


    typedef struct cvar_s
    {
        char            *name;
        char            *initval;
        char            *svalue;
        float           fvalue;
        int             ivalue;
        int             flags;

	void            (*callback) (struct cvar_s *var);
    } cvar_t;

  This Cvar declaration seems to have almost nothing in common with the
  Cvar system found in QW or in WinQuake.  The individual qbooleans are
  gone now, replaced by a single flags field.  The first value given to
  the Cvar is stored in initval.  There's also an optional function called
  whenever the Cvar changes. The big changes to your code are that the
  string and value fields have been replaced with svalue, fvalue, and
  ivalue, and that the new Cvar API means you'll be declaring pointers
  rather than structures.

  To create a Cvar, just do this:

    cvar_t *_windowed mouse;

  and find a good place to initialize it.  Initializing a Cvar is done
  with the Cvar_Get function.

    _windowed_mouse = Cvar_Get ("_windowed_mouse", "1", CVAR_ARCHIVE,
    	                NULL);

  Here is the declaration of Cvar_Get:

    cvar_t *
    Cvar_Get (
        const char *name,               // name as it appears to users
        const char *svalue,             // default value of the Cvar
        const int flags,                // bitfield for special flags
        const cvar_callback callback    // function called on change
    );

  Both Cvar_Get and Cvar_Set (used for changing a Cvar you already have a
  pointer for) take a string value, which often contains a number.  It is
  a Quake practice, especially with NetQuake, to follow numeric Cvar
  settings with a ; and a short description.  This is still supported, but
  not used anywhere within the engine at this time.

  The flags field recognizes several options which may be combined with a
  logical or (|) if needed.  Here's the list:

    CVAR_NONE           Cvar has no flags
    CVAR_ARCHIVE        Cvar should be written to user's config.cfg
    CVAR_USER           Cvar was created by the user
    CVAR_TEMP           Cvar was created by progs (gamecode)
    CVAR_USERINFO       Cvar is sent to server
    CVAR_SERVERINFO     Cvar is sent to client
    CVAR_ROM            Cvar cannot be changed by user

  CVAR_USER variables may be created, but currently there is no practical
  use for them yet besides initializing a CVAR_ROM variable before it is
  declared as such and rendered unchangable.  A good example of this is
  the filesystem variables.  Once the game starts, you really can't change
  these, though you should be able to set them on the command line without
  much trouble.  This is done with +set, just as it is in Q2/Q3A.

  CVAR_TEMP variables may be created by the compiled QuakeC.  This allows
  mod developers to make new Cvars.  No more should a mod need to make you
  add 1 + 4 + 64 to set a combination of options.  If the mod needs more
  Cvars, it can just make them.

  QuakeWorld provides an info key system which is expected to tie into the
  Cvar system.  Since the system behaves a bit differently depending on
  whether Cvar exists on a server (serverinfo) or a client (userinfo), we
  have a flag for each.  This is done to eventually allow for a QuakeWorld
  client to start its own server.  In NetQuake, the closest thing to an
  info variable is the few Cvars which can be queried by qstat/GameSpy.
  These are given the CVAR_SERVERINFO flag.

  As suggested above, Cvar_Get does not necessarily create the Cvar.  The
  Cvar may already exist.  In that case, Cvar_Get only changes the flags
  to match your specification.  Note that flags are replaced, not
  appended or toggled.

  You may provide a callback function, called when the Cvar is changed
  using the Cvar API.  For this and other reasons, you should never change
  the value of a Cvar manually.  Always use Cvar_Set.

    void
    Cvar_Set (
        cvar_t *var,                    // The variable to set
        const char *svalue              // What to set it to
    );

  Traditionally, you were able to set a Cvar knowing only its console
  name.  You cannot do this anymore, but you can use Cvar_Find

    cvar_t *
    Cvar_Find (
        const char *name                // Cvar name, eg "_windowed_mouse"
    );

  Using a Cvar once you have created it is fairly straightforward.  If the
  Cvar contains a string, where you would have referred to var.string
  before, use var->svalue now.  If you would have referred to var.value,
  you'd use var->fvalue or var->ivalue instead, depending on whether the
  Cvar contains an int or float value.  If the Cvar does not contain any
  numeric data the int and float values will be 0.


  It is sometimes necessary to iterate through every Cvar, even though
  this is generally considered to be something you should not do if you
  can avoid it.  In case you ever need to do it, three functions have been
  created to help.  Here are their declarations:

    struct cvar_foreach_s *
    Cvar_ForeachStart (void);

    cvar_t *
    Cvar_ForeachNext (
        struct cvar_foreach_s *id       // Search ID
    );

    void
    Cvar_ForeachEnd (
        struct cvar_foreach_s *id       // Search ID
    );

  Create a pointer to a struct cvar_foreach_s and assign the result of
  Cvar_ForeachStart to it.  Then call Cvar_ForeachNext with that pointer
  as its argument until you've either found what you're looking for or you
  get a NULL back for a Cvar, at which point you've reached the end of the
  list.  Cvar_ForeachEnd frees up any memory used by this process.  If you
  really need to go through the entire list, that's all there is to doing
  it.  The contents of cvar_foreach_s should be considered opaque and are
  subject to change.


  There are a few other functions in cvar.h which perform not covered by
  this overview.  Most of these are support functions used by the console
  or the init/shutdown functions.  There are a couple of functions which
  exist primarily for developer convenience, and bight be useful to some
  places.

