Difference between revisions of "The Beginner Guide to Resource Groups"

From CEGUI Wiki - Crazy Eddie's GUI System (Open Source)
Jump to: navigation, search
m (spelling, dammit!)
m (Bot: Automated text replacement (-\[\[(.*?)\|.*?\]\] +\1))
 
(14 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
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.
+
{{VersionBadge|0.6}}
 +
{{Series|The Beginner Guide|2}}
  
−
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).
+
{{notice|message=This tutorial is for CEGUI versions up to 0.6.2.  For later releases, see the tutorials in the main documentation.}}
  
 +
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!
  
−
== Specifying Resource Groups and Directories ==
+
The next stage in this quest for the 'holy grail' (that is, to actually get CEGUI to work) is to setup resource provider groups that will later enable us to load some files so that CEGUI has some source materials to use when rendering.
−
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:
 
−
<code><cpp/>
 
−
Imageset* wlis = ImagesetManager::getSingleton().createImageset("./mygame/datafiles/gui/imagesets/WindowsLook.imageset");
 
−
</code>
 
  
−
Now at initialisation time, create the resource groups in the default resource provider, like this:
+
== What is a ResourceProvider? ==
−
<code><cpp/>
+
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.
−
DefaultResourceProvider* rp = static_cast<DefaultResourceProvider*>(CEGUI::System::getSingleton().getResourceProvider());
+
  
−
rp->setResourceGroupDirectory("imagesets", "./mygame/datafiles/gui/imagesets/");
+
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.
−
</code>
+
  
−
Then later on in the code, when you need to load the imageset, just do this:
+
=== DefaultResourceProvider Explained ===
−
<code><cpp/>
+
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.
−
Imageset* wlis = ImagesetManager::getSingleton().createImageset("WindowsLook.imageset", "imagesets");
+
 
 +
Before you can use the CEGUI::DefaultResourceProvider, you need to ensure you have included the correct header (usually at the start of your source file), for example:
 +
<code>
 +
# include <CEGUIDefaultResourceProvider.h>
 
</code>
 
</code>
 +
==== 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.
  
−
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).
+
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:
 +
<source lang="cpp">
 +
Imageset* wlis = ImagesetManager::getSingleton().createImageset(
 +
"./mygame/datafiles/gui/imagesets/WindowsLook.imageset");
 +
</source>
  
−
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.
+
Using resource groups, at initialisation time, you create the resource groups in the default resource provider, like this:
 +
<source lang="cpp">
 +
DefaultResourceProvider* rp = static_cast<DefaultResourceProvider*>(
 +
CEGUI::System::getSingleton().getResourceProvider());
  
−
In addition to this, each of the classes representing loadable resources now have statically accessible members to set and retrieve a default resource group.
+
rp->setResourceGroupDirectory("imagesets", "./mygame/datafiles/gui/imagesets/");
 +
</source>
 +
 
 +
Then later on in the code, when you need to load the imageset, you can reference the resource group to be used, like this:
 +
<source lang="cpp">
 +
Imageset* wlis = ImagesetManager::getSingleton().createImageset(
 +
"WindowsLook.imageset", "imagesets");
 +
</source>
 +
 
 +
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 ==
 
== 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.
−
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):
 
For each of the resource consuming classes, the static members are named the same (special exception is xerces – see below):
−
<code><cpp/>
+
<source lang="cpp">
 
const String& getDefaultResourceGroup();
 
const String& getDefaultResourceGroup();
 
void setDefaultResourceGroup(const String& groupname);
 
void setDefaultResourceGroup(const String& groupname);
−
</code>
+
</source>
  
 
The following is a list of the core resource loading classes and the resources that they load:
 
The following is a list of the core resource loading classes and the resources that they load:
Line 51: Line 67:
 
  CEGUI::ScriptModule - Script files in whichever scripted langauge.
 
  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:
+
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:
−
<code><cpp/>
+
<source lang="cpp">
 
  const String& XercesParser::getSchemaDefaultResourceGroup();
 
  const String& XercesParser::getSchemaDefaultResourceGroup();
 
  void XercesParser::setSchemaDefaultResourceGroup(const String& groupname);
 
  void XercesParser::setSchemaDefaultResourceGroup(const String& groupname);
−
</code>
+
</source>
−
 
+
−
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.
+
  
 +
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 its own specified. This could be useful if you have all your data in a single directory.
  
−
== A final, Complete Example ==
 
  
 +
== DefaultResourceProvider Setup: A 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.
 
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:
 
After initialising the core CEGUI::System object as usual, we then specify a set of resource groups and their target directories:
−
<code><cpp/>
+
<source lang="cpp">
 
// initialise the required dirs for the DefaultResourceProvider
 
// initialise the required dirs for the DefaultResourceProvider
 
CEGUI::DefaultResourceProvider* rp = static_cast<CEGUI::DefaultResourceProvider*>
 
CEGUI::DefaultResourceProvider* rp = static_cast<CEGUI::DefaultResourceProvider*>
Line 77: Line 92:
 
rp->setResourceGroupDirectory("lua_scripts", "../datafiles/lua_scripts/");
 
rp->setResourceGroupDirectory("lua_scripts", "../datafiles/lua_scripts/");
  
−
// This is only needed if you are using Xerces and need to specify the schemas location
+
// This is only needed if you are using Xerces and need to
 +
// specify the schemas location
 
rp->setResourceGroupDirectory("schemas", "../../XMLRefSchema/");
 
rp->setResourceGroupDirectory("schemas", "../../XMLRefSchema/");
−
</code>
+
</source>
−
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:
+
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:
−
<code><cpp/>
+
<source lang="cpp">
 
// set the default resource groups to be used
 
// set the default resource groups to be used
 
CEGUI::Imageset::setDefaultResourceGroup("imagesets");
 
CEGUI::Imageset::setDefaultResourceGroup("imagesets");
Line 90: Line 106:
 
CEGUI::ScriptModule::setDefaultResourceGroup("lua_scripts");
 
CEGUI::ScriptModule::setDefaultResourceGroup("lua_scripts");
  
−
// Again, you only need to this one if you are using xerces and have defined a group for schemas.
+
// Again, you only need to this one if you are using xerces and have
 +
// defined a group for schemas.
 
CEGUI::XercesParser::setSchemaDefaultResourceGroup("schemas");
 
CEGUI::XercesParser::setSchemaDefaultResourceGroup("schemas");
−
</code>
+
</source>
 +
 
 +
== Conclusion ==
 +
Here you have had a brief introduction to the DefaultResourceProvider class, you have seen how to create resource groups and assign directory locations to them, and you have also seen how to specify default resource groups for each resource type CEGUI uses.
  
−
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.
+
[[User:CrazyEddie]]
  
−
[[User:CrazyEddie|CrazyEddie]] 10:08, 6 August 2006 (PDT)
+
[[Category:Tutorials]]

Latest revision as of 23:52, 3 March 2011

Written for CEGUI 0.6

Works with versions 0.6.x (obsolete)

The Beginner Guide series

  The Beginner Guide - Overview to CEGUI
  The Beginner Guide to Getting CEGUI Rendering
  The Beginner Guide to Resource Groups
  The Beginner Guide to Loading Data Files and Initialisation
  The Beginner Guide to Creating a CEGUI Window
  The Beginner Guide to Injecting Inputs
This page is part of a series, use links above to easily navigate through all chapters of the series.


This tutorial is for CEGUI versions up to 0.6.2. For later releases, see the tutorials in the main documentation.


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 setup resource provider groups that will later enable us to load some files so that CEGUI has some source materials to use when rendering.


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.

Before you can use the CEGUI::DefaultResourceProvider, you need to ensure you have included the correct header (usually at the start of your source file), for example:

  1. include <CEGUIDefaultResourceProvider.h>

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: 

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: 

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: 

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

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: 

 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 its own specified. This could be useful if you have all your data in a single directory.


DefaultResourceProvider Setup: A 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: 

// 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: 

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

Conclusion

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

User:CrazyEddie

Retrieved from "http://cegui.org/wiki/index.php?title=The_Beginner_Guide_to_Resource_Groups&oldid=4214"