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.

What is a 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 lower level Direct3D and OpenGL libraries do not have their own resource systems as such, so for these you can use the CEGUI default resource provider.

DefaultResourceProvider Explained

CEGUI's default resource provider, CEGUI::DefaultResourceProvider, supplies some basic functionality for those who do not yet have, or do not need, a more sophisticated alternative. As well as supplying the functions required by CEGUI for actually loading files and data, DefaultResourceProvider also has some rudimentary support for 'resource groups'. Here, a resource group is basically a label given to a directory or path on the system. This allows us to have logical grouping of files within directories and then to be able to refer to those location via a simple label rather than hard coded paths. In the simplest case this means that you just need to update the resource group location instead of updating path information throughout your code and in the XML files when you change the location of the data files.

For a fuller introduction to DefaultResourceProvider, including an example of how you need to set up the resource groups to take advantage of the CEGUI datafiles directory and its contents, please now refer to the Overview of resource system enhancements in 0.5.0.

XML, XSD? It's all XML!

With the notable exceptions of graphical image files and loadable modules (DLL and so files, etc), the majority of the data files used by CEGUI are actually XML. This leads us to the first obstacle that people run into; the .xsd schema files.

Although the Expat XML parsing library is now becoming CEGUI's default library, the previous long time default, and my own preferred, XML parsing library is the Xerces-C++ library from the Apache Software Foundation. The advantage of using this particular library to handle parsing XML is that it provides 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 CEGUI's schema files are currently found in the cegui_mk2/XMLRefSchema/ directory. Anyway, the only thing you need to know about these .xsd files for now is that, when using Xerces-C++ as a parser, they must be available to the ResourceProvider system; this is best achieved by setting up a resource group to a directory containing the schema files and setting that group as the default to be used by CEGUI::XercesParser when loading schema files (again, Overview of resource system enhancements in 0.5.0 shows how to do this).

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

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 largely 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 (either a full Imageset via XML, or a single image via an image file)
• Font
• Window Set
• Window Renderer Set
• Window Alias
• Falagard Mapping

Imageset and Font

These have already been mentioned above. The specifications here just get them to load as part of the scheme.

Window Set

Basically specifies the name of a loadable module (.dll / .so, etc), and a set of widget names contained within that module that you wish to register with the system. If no names are listed, all available types in the module are registered.

Window Renderer Set

Specifies the name of a loadable module (.dll / .so, etc), and a set of window renderer names contained within that module that you wish to register with the system. If no names are listed, all available types in the module are registered. A 'Window Renderer' is an object that can control rendering for some base window type(s), all the window renderer objects supplied with CEGUI perform rendering by making use of the 'Falagard' skinning system (though this is not a strict requirement).

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).

Falagard Mapping

Used to create a usable Window Type type from a Target Type which names the base type containing the functionality, a Renderer which names a Window Renderer that can control rendering for the specified target type, and a LookNFeel which names a skin to be applied (these are normally specified via XML looknfeel files).

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. For the purposes of this tutorial, we will load a scheme file and a font file - it is assumed the scheme automatically loads an Imageset for us. This is done as follows:

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

// load in a font. The first font loaded automatically becomes the default font. if(! CEGUI::FontManager::getSingleton().isFontPresent( "Commonwealth-10" ) )

 CEGUI::FontManager::getSingleton().createFont( "Commonwealth-10.font" );

In the above code snippet (and in the sample files) it is assumed that the resource group locations and the default groups have all been set up as described in Overview of resource system enhancements in 0.5.0.

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" );

If you intend to use tool tips, usually you specify the name of the ToolTip based widget type that you want used. It is actually possible to set this on a per-window basis, though that is not normally required, and is beyond the scope of this little introduction. Anyway, to specify the tool tip window type:

System::getSingleton().setDefaultToolTip( "TaharezLook/Tooltip" );

Conclusion

Here we have discovered 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 03:40, 9 February 2008 (PST)