From 1e827485ef51baa619d469775ca09f0cec0cd9a0 Mon Sep 17 00:00:00 2001 From: Bill Currie Date: Wed, 7 Sep 2011 21:08:37 +0900 Subject: [PATCH] Do some work on the user documentation. Also document part of the cvar api. --- doc/Makefile.am | 2 +- doc/config.dox | 122 +++++++++++++++++++++++++++++++++++++++++++++ doc/faq.dox | 7 +++ doc/quakeforge.dox | 9 +--- include/QF/cvar.h | 73 ++++++++++++++++----------- 5 files changed, 174 insertions(+), 39 deletions(-) create mode 100644 doc/config.dox diff --git a/doc/Makefile.am b/doc/Makefile.am index a031ecbe6..ec55eb35f 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -3,7 +3,7 @@ AUTOMAKE_OPTIONS= foreign SUBDIRS= man DOX=\ - bind.dox connect.dox cshifts.dox dirconf.dox faq.dox \ + bind.dox config.dox connect.dox cshifts.dox dirconf.dox faq.dox \ filesystem.dox mapformat.dox property-list.dox qtv.dox quakeforge.dox \ qw-cap-spec.dox qw-download-spec.dox surround-sound.dox timestamps.dox diff --git a/doc/config.dox b/doc/config.dox new file mode 100644 index 000000000..98d0c32dd --- /dev/null +++ b/doc/config.dox @@ -0,0 +1,122 @@ +//unfortunately, have to wrap the docs in a C comment for doxygen +/** +\page run_config Runtime Configuration. + +\li \subpage cvars +\li \subpage filesystem +\li \subpage dirconf +\li \subpage tracklist +\li \subpage key_binding +\li \subpage cshift_cvars +\li \subpage server_timestamps + +*/ + +/** +\page cvars Configuration variables + +The core of \QF's configurabitly is the cvar. + +\section cvar_value Cvar values. +Depending how the engine's use of the cvar, the value will be treated as a +string, a floating point value, an integer value or even a vector value. + +If a space is needed in the value, the value must be "quoted". + +\section cvar_type Cvar types. +From the user's perspective, there are three types of cvar: +\li plain cvar: the value can be displayed or set, but will not be +automatically saved. +\li archive cvar: like a plain cvar, the value can be displayed or set, but +the cvar will be automatically saved to \c config.cfg by the engine on +shutdown or gamedir change (quakeworld). +\li read-only cvar: the value can be displayed but not changed in any way +(value or flags). If the cvar also happens to be an archive cvar (the +archive flag was set before the read-only flag), then the cvar will be +saved to \c config.cfg. + +\section cvar_cmds Cvar related commands. +\ [value]
+Display the current value of the specified cvar. If \c value is given, set +the cvar to \c value. Does not create a new cvar. + +set \ \
+Set the specified cvar to the specified value. If the cvar does not already +exist, a new cvar will be created. + +seta \ \
+Set the specified cvar to the specified value. If the cvar does not already +exist, a new cvar will be created. Sets the cvar's archive flag so it will +be automatically saved to \c config.cfg by the clients. + +setrom \ \
+Set the specified cvar to the specified value. If the cvar does not already +exist, a new cvar will be created. Sets the cvar's read-only flag so it can +no longer be modified in any way (not even by \c reset or \c resetall). + +toggle \
+Treat the cvar as a boolean value, changing it from off to on, or on to +off. Any non-zero integer value is considered to be on, while zero and +any string that parses as zero (does not start with a non-zero number) will +be treated as off. The new value will always be either one (1) or zero (0). +\note values smaller than 1 will be treated as off. + +cvarlist [foo]
+Print a list of all cvars known to the engine (engine created or user +created). If the foo parameter is given (any value), then extra +information (cvar description, flags) will also be printed. + +cycle \ \
+Cause the cvar to cycle through the list of values. Each time this command +is executed, the cvar will change to the value immediately after the cvar's +current value in the list, cycling back to the beginning when the current +value is the last value in the list. If the current value is not in the +list, the cvar will be set to the first value in the list. + +inc \ [amount]
+Add one (1) to the cvar's current numeric value. If the optional amount is +given, add that value to the cvar's current numeric value. Using -1 +(inc \ -1), this can be used as a \c dec command. + +reset \
+Reset the specified cvar to its default (engine specified) value. + +resetall
+Reset all cvars to their default (engine specified values). + +\section cvar_rom Read-only cvars. +Many cvars in \QF are read-only because changing them at runtime would +either have little meaning or be difficult to implement. However, there +is a way to change even a read-only cvarsing the \c set command, +the cvar can be created with the desired value before the engine creates +the cvar (and sets its read-only flag). There are exactly three places +where the cvar can be created before the engine does: +\li the command line (eg nq-glx +set snd_rate 48000) +\li the global configuration file specified by the \c fs_globalcfg cvar. +\li the user configuration file specified by the \c fs_usercfg cvar. + +The global and user configuration files are normal quake scripts, but only +\c set, \c seta, and \c setrom commands are executed. + +It might seem strange to have the global and user configuration files +specified by cvars, but \QF's startup sequence is quite intense: +\li execute any \c set commands given on the command line. This way, \c +fs_globalcfg can be set. +\li execute any \c set commands in the global configuration file. This way, +\c fs_usercfg can be set. +\li re-execute any \c set commands given on the command line. Thus it is +possible to override \c fs_usercfg if it is set by the global configuration +file (unless \c setrom is used: BOFH). +\li execute any \c set commands in the user configuration file. Any cvars +set in the user configuration file override those set in the global +configuration file. +\li once again, re-execute any \c set commands given on the command line. +Thus cvars set on the command line override those set in either the user +configuration file or the global configuration file (or both). + +During the above process, the only cvars created by the engine are \c +fs_globalcfg (just before reading the global configuration file) and \c +fs_usercfg (just before reading the user configuration file). Thus, it is +possible to set any cvar in \QF. + +*/ diff --git a/doc/faq.dox b/doc/faq.dox index 4a16182f1..4958eefe9 100644 --- a/doc/faq.dox +++ b/doc/faq.dox @@ -7,6 +7,7 @@ \li \ref git_compile_error \li \ref no_music \li \ref no_mp3 +\li \ref faq_cvar_rom \section gfx_wad What does "W_LoadWadFile: unable to load gfx.wad" mean? The most common cause of this error is QuakeForge is unable to find @@ -17,6 +18,8 @@ Linux (and other UNIX like operating systems), fs_userpath defaults to ~/.quakeforge and fs_sharepath defaults to $prefix/share/games/quakeforge (distribution packages might alter the exact path). +See \ref filesystem for more details. + \section pak0_pak Where can I get pak0.pak? See \ref game_data @@ -60,4 +63,8 @@ the value appropriate for your system: Because they are not free. MP3 support is a patent minefield, and we really don't want to wind up with lawyers at ten paces, especially since we'd be unarmed with no armor, and they have rocket launchers and quad-damage. + +\section faq_cvar_rom How do I set a read-only cvar (eg, snd_rate)? +Read-only cvars can be set by creating them before the engine does. See +\ref cvar_rom for details. */ diff --git a/doc/quakeforge.dox b/doc/quakeforge.dox index f5d354f62..c8a624a50 100644 --- a/doc/quakeforge.dox +++ b/doc/quakeforge.dox @@ -10,12 +10,5 @@ of players we can. \li \subpage build-install \li \subpage faq -\li \subpage key_binding -\li \subpage cshift_cvars -\li \subpage filesystem -\li \subpage dirconf -\li \subpage qw_cap_spec -\li \subpage qw_download_spec -\li \subpage server_timestamps -\li \subpage qtv_overview +\li \subpage run_config */ diff --git a/include/QF/cvar.h b/include/QF/cvar.h index 63070feef..7d664764f 100644 --- a/include/QF/cvar.h +++ b/include/QF/cvar.h @@ -38,42 +38,55 @@ #include "QF/quakeio.h" typedef struct cvar_s { - const char *name; - const char *string; - const char *default_string; - int flags; + const char *name; ///< The name of the cvar. + const char *string; ///< The current cvar value as a string. + const char *default_string; ///< The default value of the cvar. + int flags; ///< Cvar flags + /** Callback for when the cvar value changes. + + This allows for more flexibility in what happens when a cvar is + nodifed than can be achieved with flags alone. While a similar could + be done using commands, a cvar with a callback and CVAR_ARCHIVE set + allows the setting to be saved automatically. + + \param var This cvar. + */ void (*callback)(struct cvar_s *var); - const char *description; // for "help" command - float value; - int int_val; - vec3_t vec; - struct cvar_s *next; + const char *description; ///< for "help" command + float value; ///< The current cvar value as a float + int int_val; ///< The current cvar value as an integer + vec3_t vec; ///< The current cvar value as a vector + struct cvar_s *next; ///< \internal Linked list of cvars. } cvar_t; typedef struct cvar_alias_s { - char *name; - cvar_t *cvar; - struct cvar_alias_s *next; + char *name; ///< The name of the alias. + cvar_t *cvar; ///< The cvar to which this alias refers + struct cvar_alias_s *next; ///< \internal LInked list of aliases. } cvar_alias_t; -#define CVAR_NONE 0 -#define CVAR_ARCHIVE 1 // set to cause it to be saved to vars.rc - // used for system variables, not for player - // specific configurations -#define CVAR_USERINFO 2 // sent to server on connect or change -#define CVAR_SERVERINFO 4 // sent in response to front end requests -#define CVAR_NOTIFY 32 // Will notify players when changed. -#define CVAR_ROM 64 // display only, cannot be set by user at all -#define CVAR_USER_CREATED 128 // created by a set command -#define CVAR_LATCH 2048 // will change only when C code next does - // a Cvar_Get(), so it can't be changed - -// Zoid| A good CVAR_ROM example is userpath. The code should read "cvar_t -// *fs_userpath = CvarGet("fs_userpath", ".", CVAR_ROM); The user can -// override that with +set fs_userpath since the command line +set gets -// created _before_ the C code for fs_basepath setup is called. The code goes -// "look, the user made fs_basepath already", uses the users value, but sets -// CVAR_ROM as per the call. +/** \name cvar_flags + Zoid| A good CVAR_ROM example is userpath. The code should read "cvar_t + *fs_userpath = CvarGet("fs_userpath", ".", CVAR_ROM); The user can + override that with +set fs_userpath \ since the command line +set + gets created _before_ the C code for fs_basepath setup is called. The + code goes "look, the user made fs_basepath already", uses the users value, + but sets CVAR_ROM as per the call. +*/ +//@{ +#define CVAR_NONE 0 ///< normal cvar +#define CVAR_ARCHIVE 1 ///< set to cause it to be saved to + ///< config.cfg +#define CVAR_USERINFO 2 ///< sent to server on connect or change +#define CVAR_SERVERINFO 4 ///< sent in response to front end requests +#define CVAR_NOTIFY 32 ///< Will notify players when changed. + ///< (not implemented) +#define CVAR_ROM 64 ///< display only, cannot be set +#define CVAR_USER_CREATED 128 ///< created by a set command +#define CVAR_LATCH 2048 ///< will change only when C code next does + ///< a Cvar_Get(), so it can't be changed + ///< (not implemented) +//@} // Returns the Cvar if found, creates it with value if not. Description and