The Beginner Guide to Loading Data Files and Initialisation

If you have read The Beginner Guide to Getting CEGUI Rendering, you probably have your application set-up to perform the basic CEGUI initialisation steps and to call the System::renderGUI method, which is all very nice; but lets face it, you still can't get anything to draw!

The next stage in this quest for the 'holy grail' (that is, to actually get CEGUI to work) is to learn how to load some data files so that CEGUI has some source materials to use when rendering.

Overview: Data Files and the ResourceProvider

CEGUI uses a variety of data files and initially there may be some confusion over what these are, how they relate to each other and how they get loaded. So before we get started with the meat of all this, I will introduce the data files, what they are, what they're used for, and how they get loaded into CEGUI.

Resources Provided – What is the ResourceProvider?

CEGUI makes use of a helper object which we call the ResourceProvider. This object provides an interface between the core CEGUI library and any external file loading system.

For example, the Ogre and Irrlicht engines have their own resource manager / file loading sub-systems, by implementing and supplying a specialised ResourceProvider object, the renderer modules for these engines allow seamless integration with these systems so that CEGUI data files are loaded via these systems.

The Direct3D and OpenGL renderers do not, by default, use a specialised ResourceProvider; these systems default to loading all resources from the current working directory for the running application (usually the directory containing the executable). This fact is of major importance when specifying paths to files within other files; they are all relative to the same directory, they are not relative to each other.

XML, XSD? It's all XML!

With the exception of graphical image files and loadable modules (DLLs / .soS, etc), all data files used by CEGUI are actually XML. This leads us to the first obstacle that people run into; the schema (.xsd) files.

By default, CEGUI uses Xerces-C++ to handle parsing XML files with schema validation. Schema validation is a means by which we can check, at parse time, whether the input file contains the expected data and that the data is correctly specified. To do this, the system requires some additional files which are known as schema files, which have the .xsd file extension (the master copies of these are in the cegui_mk2/XMLRefSchema/ directory). Anyway, the only thing you need to know about these .xsd files for now is that they must be available to the ResourceProvider system; usually this can be achieved by placing a copy of the appropriate .xsd file in the same directory as the XML data you'll be loading.

The Data Files

As mentioned above, with a couple of exceptions, all data files in CEGUI are XML. Rather than using the generic '.xml' file extension, the data files are named according to what the files actually represent; so .imageset for an Imageset and .font for a Font, etc. Below is a very brief overview of each file type; more advanced discussion of the files and their capabilities can be found elsewhere.

Imageset

Effectively, an Imageset is just a collection of defined regions upon the source image / texture file (which is also specified in the Imageset definition). Each of these defined regions has a unique name and is known within the system as an Image. An Image as defined in an Imageset is the basic level of imagery used by CEGUI. By modifying the source image / texture file and also the position and size of the defined regions within the Imageset files you can easily change the appearance of what gets drawn by CEGUI.

Font Type

A Font file, unsurprisingly, defines a font for use in CEGUI. There are two types of font which can be defined:

FreeType Font 

This is a font based upon a true-type (.ttf) font file. It is denoted with Type="FreeType" in the .font file starting with version 0.5.0 of CEGUI. In previous versions it was known as "Dynamic".

Pixmap Font 

Also known as a bitmapped font, this type of font is based upon an Imageset which defines Images for the font glyphs. It is denoted with Type="Pixmap" in the .font file starting with version 0.5.0 of CEGUI. In previous versions it was known as "Static".

Scheme

A Scheme is a means to group other data files together, it's also the most convenient way to load and register widget types. A Scheme can contain one or more of the following (which will be loaded and initialised when the scheme is loaded):

• Imageset
• Font
• Window Set
• Window Alias

Imageset and Font have already been mentioned. A 'Window Set' basically specifies the name of a loadable module (.dll / .so, etc), and a set of widgets contained within that modules that you wish to register with the system. A 'Window Alias' provides a means to refer to a window / widget type by alternative names, it can also be used to 'hide' an already registered widget type with another widget type (so that other widget type gets used instead).

Layout

A layout file contains an XML representation of a window layout. Each nested 'Window' element defines a window or widget to be created, the 'Property' elements define the desired settings and property values for each window defined.

Config

CEGUI Supports the use of a config file. This file allows you to specify some defaults, such as a Scheme to load, a layout to load, initialisation and termination script files (when using a ScriptModule), and some other things which are not discussed here.

Loading the Basic Files

In order to get things up and running you need to load in some files. The minimal set of files required are:

• Imageset
• Font
• Scheme

The good thing about the Scheme file is that it can be used to load the other two automatically. Though the sample schemes currently provided in CEGUI only specify the Imageset and not the Font. So for the purposes of this tutorial, we will load a scheme file and a font file. This is done as follows:

// load in the scheme file, which auto-loads the TaharezLook imageset
CEGUI::SchemeManager::getSingleton().loadScheme(“../datafiles/schemes/TaharezLook.scheme”);

// load in a font.  The first font loaded automatically becomes the default font.
CEGUI::FontManager::getSingleton().createFont(“../datafiles/fonts/Commonwealth-10.font”);

In the above code snippet (and in the sample files) it is assumed that a 'datafiles' directory exists above the current directory, and that it contains all the files from the cegui_mk2/Samples/datafiles/ directory.

Important note for Ogre users: To use the unmodified sample data files, you must ensure that the current working directory is specified as a resource location in the Ogre resource manager (usually via the resources.cfg file). Alternatively, you could add all the datafiles sub-directories and remove the relative path information from the sample datafiles. The reason the files are provided in this manner, is because they need to work under the default ResourceProvider used with raw D3D/OpenGL, as discussed above.

Simple Defaults Initialisation

Finally, you need to specify some defaults. This is to ensure that the system always has a font and mouse cursor available for when a window or widget specifies no preference of its own.

In reality, we no longer need to specify a default font, since the FontManager will now automatically set the first loaded font as the default. Although if this is not the default font you require, you can set a different one as you desire. The code to set a default font is as follows:

System::getSingleton().setDefaultFont(“Commonwealth-10”);

The other default object you need to set is the mouse cursor. This is to ensure that when you move the mouse over any element that does not set a cursor of its own the cursor does not disappear. The code to set the default mouse cursor is as follows (NB: This uses the TaharezLook imageset which was loaded with the scheme above).

System::getSingleton().setDefaultMouseCursor(“TaharezLook”, “MouseArrow”);

Conclusion

Here we have learned the very basics of what the various data files used by CEGUI are, how they are loaded, and the minimal initialisation needed for CEGUI applications. Other articles will discuss each of the data files types in greater detail allowing advanced uses to be discovered.

--CrazyEddie 13:23, 11 Apr 2005 (BST)