Parameter Handling API

With this API you can handle parameter sets in TORCS, this includes manipulation of data in memory, and writing into/reading from XML files. More...

Collaboration diagram for Parameter Handling API:

Topics
	Parameter Handling API Setup
	Initialize and shutdown the Parameter Handling API.
	Parameter File Handling API
	Create, read and write parameter files.
	Parameter Data Handling API
	Handling of data in parameter sets.
	Parameter List Handling API
	Handling of multiple sections or subsections and the elements in parameter sets.
	Parameter Helper Functions
	Internal (not exported) helper functions, not part of the API.

Detailed Description

With this API you can handle parameter sets in TORCS, this includes manipulation of data in memory, and writing into/reading from XML files.

The parameters are structured in:
section - containing a family of parameters on the same topic.
list (subsections) - containing elements of numerical attributes and string attributes.

The API is not thread safe, because parameter sets and handles carry internal state regarding iteration and XML parsing. The parameter sets are reference counted, so usually multiple handles can refer to the same parameter set.

Handles and ownership

Include tgf.h. TORCS initializes the library before robot callbacks. Read a file with GfParmReadFile and check for NULL before using the result. Each successful read returns an owned handle to release with GfParmReleaseHandle; do not release handles borrowed from the race manager. Most functions require a valid non-NULL handle, even getters with a fallback value. Non-private reads with the same filename share data: modifying, cleaning or rereading through one handle affects the others. GFPARM_RMODE_PRIVATE requests independent data. GFPARM_RMODE_CREAT creates only an in-memory set; persistence requires GfParmWriteFile. Releasing a handle does not save it.

Paths, strings and units

Paths are slash-separated section names such as "Gearbox/gears/1", without a leading or trailing slash. Keys identify attributes within that section; use the constants in car.h and other interface headers where available. String getters return borrowed storage (or the exact fallback pointer), not a copy. Copy strings before retaining them across mutations, rereads or release. Numeric values are stored in SI units. Getter unit arguments select output units; setter unit arguments describe input units. NULL means SI. Defaults are returned unchanged, so express them in the requested output unit. GfParmGetNumBoundaries always returns SI bounds. GfParmSetNum also sets both bounds to the value; use GfParmSetNumEx to preserve an adjustable range.

Reading a robot setting

void *settings = GfParmReadFile("drivers/myrobot/default.xml",
                              GFPARM_RMODE_STD | GFPARM_RMODE_PRIVATE);
if (settings != NULL) {
    tdble fuel = GfParmGetNum(settings, SECT_CAR, PRM_FUEL, NULL, 50.0f);
    // Use fuel here; copy any strings needed after releasing settings.
    GfParmReleaseHandle(settings);
}

Lists and validation

A list is a section whose immediate child sections are its elements, not an array of attributes. Its cursor is shared by all handles to that parameter set. GfParmListSeekFirst can succeed on an empty list; check the current name before processing it (see Parameter List Handling API). Setters do not enforce setup constraints. See GfParmCheckHandle for the limitations of its checks and return status, and GfParmMergeHandles for merge modes, range adjustment and optional input-handle release.

Parameter directions

[in] means read-only input, [out] means a caller-provided output destination, and [in,out] includes mutation of data, iteration state or handle lifetime.