The Beginner Guide to Resource Groups

One common cause of confusion in the earlier releases of CEGUI 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.

The 0.5.0 release introduced some 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), this article is a brief introduction and tutorial on specifying resource groups and their directories with the DefaultResourceProvider, and on how to set the default resource groups to be used by the various components in CEGUI.

Specifying Resource Groups and Directories

The DefaultResourceProvider allows you to define any number of named resource groups and to specify a directory to be used for each group. What this 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, without the use of resource groups, you might have done this: <cpp/> Imageset* wlis = ImagesetManager::getSingleton().createImageset( "./mygame/datafiles/gui/imagesets/WindowsLook.imageset");

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

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

Then later on in the code, when you need to load the imageset, you can reference the resource group to be used, like this: <cpp/> Imageset* wlis = ImagesetManager::getSingleton().createImageset( "WindowsLook.imageset", "imagesets");

Note how you do not need to 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 approach, the data files should not contain relative path information – they should, in general, just have the actual file name.

Default Resource Groups

Each of the system classes that represents a loadable resource 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");

Here you have had a brief introduction to the DefaultResourceProvider class, and also how to specify default resource groups for each resource type CEGUI uses.

CrazyEddie 10:08, 6 August 2006 (PDT)