Resource Management - ClanLib SDK

Resource Management

The resource management system in ClanLib is based on the principle that for each resource type there is a resource cache object responsible for fetching resources of that type.

Since resources can be virtually anything (images, textures, 3D meshes, shared GPU objects, etc), the system relies on casting the generic clan::ResourceObject class to a specific clan::Resource<Type> object. The clan::Resource<Type> template can return a reference the actual shared resource object, as well as track if the resource has been modified.

Just like resources can be virtually anything, the method for fetching a clan::ResourceObject also varies from type to type. To get a resource, the resource cache object managing it must first be retrieved. clan::ResourceManager has a clan::get_cache<Type>(name) function with returns a specific cache. For clanDisplay based resources, the cache interface is the clan::DisplayCache class, and it is stored in the clan::ResourceManager with the name "clan.display".

clan::ResourceManager is in other words just a map of cache objects for different resource types. It is possible to create custom resource handling by constructing clan::ResourceManager manually, then attach your own implementation of clan::DisplayCache and so on.

Most applications rely on the default implementation which is provided by constructing clan::XMLResourceManager instead. It loads resources described in an XML file. For the standard objects offered by ClanLib, such as the clan::Sprite class, the above manual fetching of resource is also not needed. The convenience function clan::Sprite::resource(gc, id, resources) takes care of the common case.

    THIS PAGE REQUIRES UPDATING FOR CLANLIB 3.0

## Resource Manager

The resource manager in ClanLib allows you to use a central source for all your resources in your application. The system defines a simple XML format describing resources used by ClanLib, and since it is XML it also allows you to use it for your own custom resources.

A resource XML file may look like this:

<resources>
<section name="section1">
<texture name="texture1" file="image.png" />
</section>
<section name="section2">
<section name="section3">
<my-type name="my-resource1">
<text>Hello World!</text>
</my-type>
</section>
</section>
<sample name="my-sample" file="test.wav" />
</resources>

The class clan::ResourceManager is used to load, manage and save resource files. The syntax for loading resources is fairly straightforward:

clan::ResourceManager resources("resources.xml");
clan::Texture texture(gc, "section1/texture1", &resources);
clan::SoundBuffer sample("my-sample", &resources);
clan::ResourceManager
Resource manager.
Definition resource_manager.h:44
clan::SoundBuffer
Sample interface in ClanLib.
Definition soundbuffer.h:56
clan::Texture
Texture object class.
Definition texture.h:103

## Resource Objects

Although the above syntax is the common way to load resources, in reality all objects defined in a resource XML are all represented as clan::Resource objects. To illustrate how this object is used, the above clan::Texture constructor used to load a texture may have been implemented like this:

clan::ResourceManager resources("resources.xml");
clan::Resource resource = resources.get_resource("section1/texture1");
clan::String filename = resource.get_element().get_attribute("file");
clan::PixelBuffer image = clan::ImageProviderFactory::load(filename, resources.get_directory());
clan::Texture texture(gc, image);
clan::ImageProviderFactory::load
static PixelBuffer load(const std::string &filename, const FileSystem &fs, const std::string &type=std::string(), bool srgb=false)
Loads an image file from 'filename', using the provider.
clan::PixelBuffer
Pixel data container.
Definition pixel_buffer.h:68
clan::Resource
Resource proxy of a specific type.
Definition resource.h:58

In the same way we might create our own custom resource loader:

clan::String load_my_type(const clan::String &res_id, clan::ResourceManager &resources)
{
clan::Resource resource = resources.get_resource(res_id);
if (resource.get_type() != "my-type")
throw clan::Exception("Resource not of expected type!");
clan::DomElement text_element = resource.get_element().named_item("text").to_element();
return text_element.get_text();
}
clan::ResourceManager resources("resources.xml");
clan::Console::write_line(load_my_type("section2/section3/my-resource1", resources);
clan::Console::write_line
static void write_line(const std::string &text)
Writes text to the console window and then advances to a new line.
Definition console.h:185
clan::DomElement
DOM Element class.
Definition dom_element.h:60
clan::DomElement::get_text
std::string get_text() const
Returns the text of all child Text nodes appended together.
clan::Exception
Top-level exception class.
Definition exception.h:42