Chapter 11. X-Forge Utils

Table of Contents

Introduction
XFuConfiguration
XFuConfigurationData
XFuFastRandom
XFuRandom
XFuParticleSystem
XFuPrinter
XFuRLESpritePrinter
XFuTokenizer
XFuXMPlayer
XFuFPSCount
XFuWavLoad
XFuVideoRecorder

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.