kevin/rtengine
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

Update CVar system

Kevin Trogant 2024-08-01 08:51:58 +02:00
parent e92ad7cccd
commit cc20ee9fb5
1 changed files with 45 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
CVar-system.md

@ -1,6 +1,49 @@
The engine provides a CVar (configuration variable) system in <runtime/config.h>, that is used heavily in the engine to configure its various features.
The engine provides a CVar (configuration variable) system in `<runtime/config.h>`, that is used heavily in the engine to configure its various features.
**TODO: In depth description**
## Creating CVars
CVars are created with one of the `RT_CVAR_` macros in `<runtime/config.h>`. These take a name, the description string and the default value respectively.
The convention used in the engine is to define CVars at the top of the file that uses them.
CVars use a tagged union to store values of different types. The macro used to define the cvar also sets the type.
At the time of writing this, the following types are available:
| Type | Creation macro | Union member |
|---------|------|----------|
| int | `RT_CVAR_I` | `.i` |
| float | `RT_CVAR_F` | `.f` |
| string | `RT_CVAR_S` | `.s` |
| size_t | `RT_CVAR_SZ` | `.sz` |
CVars must be registered to be able to retrieve them from other parts of the code (including changing them from configuration files).
This is done via `rtRegisterCVAR`.
The game provides a callback to launcher called RegisterCVARs that is called *before initialization*.
After registering the game cvars, the launcher loads and parses the game-config file, which then can modify these variables.
In the engine, each subsystem (runtime, renderer, asset_compiler, ...) handles its own CVars.
Aside from the runtime, the launcher program makes sure to register these in the correct order and loads the associated configuration files.
## Config-Files
Config files, by convention, are placed in the 'cfg' directory and use the file extension '.cfg'.
They use [INI file syntax](https://en.wikipedia.org/wiki/INI_file).
Currently, the system ignores sections.
Config files are loaded using the function `rtProcessConfigFiles` which takes a number of files, loads them and parses their contents.
Currently, the following configuration files are used by the engine:
| File | Purpose |
|----|------|
| cfg/engine_early.cfg | Configures the basic runtime systems (AIO, resource system, asserts, ...) |
| cfg/launcher.cfg | Configures the launcher executable (Window mode, renderer to use, game-lib, ...)
| cfg/renderer.cfg | Configures render parameters |
| cfg/game.cfg | Game-specific configuration |
## Listening to changes
The cvar system allows the user to register "change event handlers" for particular CVars.
This is done via `rtRegisterCVARChangeEventHandler`, which takes a callback of the form: `void ChangeEventHandler(rt_cvar *cvar, void *userdata)`.
Whenever the system is notified of a cvar change (`rtNotifyCVARChange`) all registered callbacks for the changed cvar are called.
## CVar naming convention