## Chapter 11. X-Forge Utils

## Introduction

The xfutil library is a collection of routines that are not part of the core, but are not part of the engine proper either. They are still used by the engine or any games built directly on top of the X-Forge Core.

The classes in the util library are small, helpful routines that can be used in small projects without using the engine at all.

## XFuConfiguration

The `XFuConfiguration` class is a configuration container. It wraps an `.ini` file parser and a hash table.

Each row of the .ini file contains a name and a value, like thus:

    fileName=HelloWorld.xff

Rows with a leading # are treated as comments.

To create an `XFuConfiguration` object, you call either `create()` to create an empty configuration set, or `create(const CHAR *aFilename)` to load an `.ini` file to populate the object.

You can also populate an existing `XFuConfiguration` object by loading more `.ini` files with the `load()` method, or by adding single configuration keys with the `put()` method.

You can clear the object of all keys with the `clear()` method. Finally, you can get a value for a key with the `get()` method.

## XFuConfigurationData

The `XFuConfigurationData` class is a configured data container, extending `XFuConfiguration`. It reads and parses a set of configuration data keys from a file. The format of the configuration file is such that there is one property on each row in a text file. Each property is a pair of a key and a value, delimited by a '=' char, for example:

    fileName = HelloWorld.xff

Optionally the key can also have a type prefix which is delimited from the rest of the key with a ':' (colon) char, for example:

    image : cursor = arrow.tga

Recognized builtin types are parsed when the configuration file is processed. For some types the data is also loaded at the same time. Note that for recognized types the key is reformatted to use the short form before adding to the data container, which affects only fetching of data with regular get-method instead of a type specific getType-style method. If multiple keys refer to exact same value which results in loading of a resource, the resource is loaded only once so that the same loaded resource is shared between the keys. Builtin types have getType-style methods which can be used to read the data easily by the key omitting the type prefix. Builtin types also have both long and short forms of the type, so the previous example could be also written:

    i:cursor = arrow.tga

Recognized built-in types are `image` (short form: i), `printer` (p), `sound` (s) and `music` (m). Leading and trailing spaces are trimmed. Lines starting with character '#' are treated as comment lines and are ignored. Optional parts of value strings can be omitted.

Please refer to the API-documentation for detailed description of usage.

## XFuFastRandom

The `XFuFastRandom` class contains an implementation of a fast pseudorandom number generator.

The random number generator has not been scientifically tested, and is most probably rather poor at generating truly random numbers. Thus it is good for whenever you need somewhat random numbers, fast.

After creating the `XFuFastRandom` object, you can get random numbers with the `next()` method. You can set the random number seed with the `seed()` method.

## XFuRandom

The `XFuRandom` class is an implementation of the "Mersenne Twister" pseudorandom number generator, considered widely to be one of the best pseudorandom number generators. More information about the algorithm can be found at `http://www.math.keio.ac.jp/~matumoto/emt.html`.

After creating the `XFuRandom` object, you can get random numbers with the `next()` method. You can set the random number seed with the `seed()` method.

## XFuParticleSystem

The `XFuParticleSystem` implements a particle system. The particle systems can be edited with the ThinGamaJig editor found in the X-Forge distribution.

The particle system has been designed so that it is used as it is inside the particle system editor, with embedded X-Forge providing realtime preview of the particle system.

The `load()` method is used to load a particle system configuration. These files are created with the ThinGamaJig editor.

The `save()` method can be used to save the particle system settings.

The `loadTextures()` method is used to load the textures. The `load()` method does not load textures.

The `tick()` method is used to make the particle system calculate the particle movements. The method takes current time as parameter, instead of taking the current tick from the system; this can be used to alter the flow of time.

The `render()` method is used to render the particle system. The `XFuParticleSystem` class does not change any of the `XFcGL` matrices.

The `restart()` method can be used to restart the whole animation from beginning. This can be useful for explosion-style particle systems.

## XFuPrinter

The `XFuPrinter` is a primitive bitmap font printer.

The font itself must be in an 8-bit paletted pcx or tga file or a 32-bit tga file. The printer is internally 8-bit, so using a 32-bit image won't bring any advantage. In the image all characters must be listed in ASCII order starting from character 33 (the exclamation mark, "!"), so that the image has one character per row.

The image file must be as wide as a single character is high, ie. for a 8x8 font with 20 characters and one character, the image dimensions would be 8x160.

## XFuRLESpritePrinter

The `XFuRLESpritePrinter` extends the `XFuPrinter` class, using RLE compressed sprites instead of normal `XFcGLSurface` objects. It was designed to be a drop-in replacement for `XFuPrinter`, and the only thing you may wish to change is the creation.

## XFuTokenizer

The `XFuTokenizer` class implements a simple string tokenizer.

Sample usage:

    const CHAR blah="some; string with ; different tokens";

    XFuTokenizer myTokens;
    myTokens.tokenize(blah,XFUSTR(";"));
    for (int i=0;i<myTokens.getTokenCount();i++)
       if (tokenEqualsNocase(XFUSTR("String wIth"))
           printf("token number d is our token",i);

You can create a simple parser by using two `XFuTokenizer` objects. Run one through the whole line, using newline and carrier return characters as delimiters, and use second to tokenize a single line at a time.

## XFuXMPlayer

The `XFuXMPlayer` is an XM music player, implemented as an X-Forge audio stream.

The XM format is an advanced descendant of the Amiga .MOD format. An .XM file contains sample and note data, enabling the composer to create high-quality audio in rather small file sizes.

Decoding XM files is also much lighter operation than, for example, decoding MP3 files.

## XFuFPSCount

The FPS counter utility class can be used to track average framerate within the last N frames. You can also create several, and track the average framerate for the last 5 and 50 frames, for instance.

## XFuWavLoad

The WAV loader utility loads noncompressed PCM wave files directly into audio buffers.

## XFuVideoRecorder

The video recorder utility can be used to store sequential frames from desktop builds of X-Forge applications at a constant framerate, useful for promotional videos.

|  | X-Forge Documentation Confidential Copyright © 2003 Fathammer