The Beginner Guide to Resource Groups

One common cause of confusion in CEGUI with previous releases had always been the various relative paths in the XML data files; specifically, how these relate to each other and the current working directory. Effectively, the default resource provider just loaded files using either absolute paths or paths relative to the working directory – this meant than in order to have data files in an organised directory hierarchy they needed to contain relative path information; this was fine until you move the files around a little, at which point everything broke.

Beginning with the 0.5.0 release, we introduced some small extensions to DefaultResourceProvider (and also the IrrlichtResourceProvider – since that is a subclass of DefaultResourceProvider. People with custom resource providers, like Ogre users, can skip to the 'specifying default resource groups' section).

Specifying Resource Groups and Directories

The core extension basically allows you to define any number of named resource groups and to specify a directory to be used for each group. What this basically means is that you can create a resource group, say “imagesets” and assign a directory to that, for example “./mygame/datafiles/gui/imagesets/”. Then when loading an Imageset through the ImagesetManager, you could specify the resource group to be used as “imagesets” and the system will look in the predefined location. At present each resource group may only have a single directory assigned to it.

A small code example is in order to clarify what has been said. Where as Previously, you would have done this: <cpp/> Imageset* wlis = ImagesetManager::getSingleton().createImageset("./mygame/datafiles/gui/imagesets/WindowsLook.imageset");

Now at initialisation time, create the resource groups in the default resource provider, like this: <cpp/> DefaultResourceProvider* rp = static_cast<DefaultResourceProvider*>(System::getSingleton().getRenderer()->getResourceProvider());

rp->createResourceGroup("imagesets", "./mygame/datafiles/gui/imagesets/");

Then later on in the code, when you need to load the imageset, just do this: <cpp/> Imageset* wlis = ImagesetManager::getSingleton().createImageset("WindowsLook.imageset", "imagesets");

Note how the new convention does not specify any path information; the path information is obtained from the resource group specified, in the example this is "imagesets". We will later show you how you set default resource groups for each of the resource types – then you do not have to specify the group when you load a resource (unless you're loading it from a group that is not the default, of course).

Another important thing to consider is that using this new approach, the data files should no longer contain relative path information – they should, in general, just have the actual file name.

In addition to this, each of the classes representing loadable resources now have statically accessible members to set and retrieve a default resource group.

Deafult Resource Groups

Each of the system classes that represents a loadable resource now has static members to set and get a default resource group. This resource group will be used when loading the specific data files needed by a given class – in the case of the Imageset class, the default resource group should reference a directory holding the imageset xml and texture image files.

For each of the resource consuming classes, the static members are named the same (special exception is xerces – see below): <cpp/> const String& getDefaultResourceGroup(); void setDefaultResourceGroup(const String& groupname);

The following is a list of the core resource loading classes and the resources that they load:

CEGUI::Imageset			- Imageset xml and texture image files. 
CEGUI::Font			- Font xml and ttf font files.
CEGUI::Scheme			- Scheme xml files.
CEGUI::WindowManager		- Window layout xml files.
CEGUI::WidgetLookManager	- LookNFeel xml files
CEGUI::ScriptModule		- Script files in whichever scripted langauge.

There is one special exception, as mentioned above – that is the Xerces-C based XML parser. For this there is a special resource group setting to specify where the schema files can be found (these are the .xsd files used for xml validation). For this special case, the static members are: <cpp/>

const String& XercesParser::getSchemaDefaultResourceGroup();
void XercesParser::setSchemaDefaultResourceGroup(const String& groupname);

One final thing to consider, is that the resource provider class also has a default group. This should be considered a 'global' default – it is used whenever a specific resource loading class has no default of it's own specified. This could be useful if you have all your data in a single directory.

A final, Complete Example

To close, we will show how the CEGUI samples framework does the initialisation of resource groups and their target directories, and how we assign the default groups to be used for all of the resource types.

After initialising the core CEGUI::System object as usual, we then specify a set of resource groups and their target directories: <cpp/> // initialise the required dirs for the DefaultResourceProvider CEGUI::DefaultResourceProvider* rp = static_cast<CEGUI::DefaultResourceProvider*>

   (CEGUI::System::getSingleton().getResourceProvider());

rp->setResourceGroupDirectory("schemes", "../datafiles/schemes/"); rp->setResourceGroupDirectory("imagesets", "../datafiles/imagesets/"); rp->setResourceGroupDirectory("fonts", "../datafiles/fonts/"); rp->setResourceGroupDirectory("layouts", "../datafiles/layouts/"); rp->setResourceGroupDirectory("looknfeels", "../datafiles/looknfeel/"); rp->setResourceGroupDirectory("lua_scripts", "../datafiles/lua_scripts/");

// This is only needed if you are using Xerces and need to specify the schemas location rp->setResourceGroupDirectory("schemas", "../../XMLRefSchema/"); Now that is done, we have a nice set of resource groups defined with their target directories set. Finally, to get the system to use these new directories, we set the default resource groups to be used: <cpp/> // set the default resource groups to be used CEGUI::Imageset::setDefaultResourceGroup("imagesets"); CEGUI::Font::setDefaultResourceGroup("fonts"); CEGUI::Scheme::setDefaultResourceGroup("schemes"); CEGUI::WidgetLookManager::setDefaultResourceGroup("looknfeels"); CEGUI::WindowManager::setDefaultResourceGroup("layouts"); CEGUI::ScriptModule::setDefaultResourceGroup("lua_scripts");

// Again, you only need to this one if you are using xerces and have defined a group for schemas. CEGUI::XercesParser::setSchemaDefaultResourceGroup("schemas");

Anyhow, that's a brief introduction to the new enhancements to the DefaultResourceProvider class, and also the extensions to allow the specification of default resource groups for each resource type we use.

CrazyEddie 10:08, 6 August 2006 (PDT)