| 1 |
<xml> |
| 2 |
<head> |
| 3 |
<title>Resources</title> |
| 4 |
</head> |
| 5 |
<body> |
| 6 |
|
| 7 |
<p>Resources are a fundamental aspect of any game. The graphics in the game |
| 8 |
may consist of sprites, and the sounds in the game typically consists of |
| 9 |
wave-samples or similar. Other data used in games could be the data defining |
| 10 |
a level in a game, or the dialogue used in some scene in the game. As a |
| 11 |
matter of fact, anything except the actual game code in the game, can be |
| 12 |
viewed as resources.</p> |
| 13 |
|
| 14 |
<p>We would like resources in a game to be separated from the game as much |
| 15 |
as possible. For instance, we don't want to change code because we change |
| 16 |
the filename of some sprite graphics file, and we certainly don't want to |
| 17 |
update source code, if we change the dimensions or any similar aspect of a |
| 18 |
resource either. We want to have flexible control of the resources |
| 19 |
initialization, separated from the game code. For instance we want to be |
| 20 |
able to specify whether a sample loops, or set it's volume separately from |
| 21 |
the source code. We want to have as great resource flexibility as possible |
| 22 |
while developing the game. And finally we would like our resources to be |
| 23 |
location transparent. If we have some netgame server that includes a level |
| 24 |
unknown to a joining client, we want that level to be transferred to the |
| 25 |
client game location transparently, as if the resource resided locally on |
| 26 |
that client.</p> |
| 27 |
|
| 28 |
<p>To design a resource system, that provides an adequate solution to these |
| 29 |
problems, we need a level of abstraction between physical resource |
| 30 |
location/loading, and resource naming in the actual game code. This is where |
| 31 |
the resource manager in ClanLib comes in. The resource manager, |
| 32 |
<codelink>CL_ResourceManager</codelink>, provides this level of abstraction |
| 33 |
by presenting an uniform resource interface to ClanLib applications. The |
| 34 |
resource managers main responsibility is to parse a resource definition |
| 35 |
file, and load the resources using the proper resource loader, when |
| 36 |
requested.</p> |
| 37 |
|
| 38 |
<p>A resource definition file in ClanLib is a xml file. It contains two |
| 39 |
different types of XML tags: sections and resource types. It has a form like |
| 40 |
this:</p> |
| 41 |
|
| 42 |
<code> |
| 43 |
<resources> |
| 44 |
<section name="Game"> |
| 45 |
<sample name="sfx_explosion" file="explosion.wav" /> |
| 46 |
<surface name="sur_explosion" file="explosion.png" /> |
| 47 |
<customtype name="data" text="hello"> |
| 48 |
<meaning_of_life value="42" /> |
| 49 |
</customtype> |
| 50 |
</section> |
| 51 |
</resources> |
| 52 |
</code> |
| 53 |
|
| 54 |
<p>The top element of a resource definition file in ClanLib starts with the |
| 55 |
<resources> tag. It can then be followed either by the special |
| 56 |
<section> tag, or by a resource type tag. Sections and resource |
| 57 |
tags only have one required attribute "name". The resource identifer for the |
| 58 |
explosion sample is "Game/sfx_explosion" in the above example.</p> |
| 59 |
|
| 60 |
<p>Sections are a way to group resources. This aids readability and logical |
| 61 |
grouping for the game coder, as well as providing an efficient way to load a |
| 62 |
group of resources at the same time.</p> |
| 63 |
|
| 64 |
<p>Any other element than the <section> element will be considered a |
| 65 |
resource. You can create as many custom resource element types as you want, |
| 66 |
in this example the <customtype> resource (note that "customtype" isnt |
| 67 |
a keyword, it could be any tag name). The only requirement is that it has |
| 68 |
the "name" attribute, which is used to access the resource from the resource |
| 69 |
manager. Via the <codelink>CL_Resource</codelink> interface, you can access |
| 70 |
the XML tree from any resource in the resource definition file.</p> |
| 71 |
|
| 72 |
<p>If the above resource definition file was named resources.xml, the |
| 73 |
following code illustrates how to load and access resources in it:</p> |
| 74 |
|
| 75 |
<code> |
| 76 |
CL_ResourceManager resources("resources.xml"); |
| 77 |
CL_Resource resource_sample = resources.get_resource("Game/sfx_explosion"); |
| 78 |
std::string file = resource_sample.get_element().get_attribute("file"); |
| 79 |
CL_Resource resource_data = resources.get_resource("Game/data"); |
| 80 |
CL_DomNode meaning_of_life = resource_data.get_element().named_item("meaning_of_life"); |
| 81 |
</code> |
| 82 |
|
| 83 |
<h3>Resource Loading And Unloading</h3> |
| 84 |
|
| 85 |
<p>Built on top of the above system, the resource system can also |
| 86 |
administrate reference counted loading and unloading of resources. |
| 87 |
<codelink>CL_Resource</codelink> contains two functions called load() and |
| 88 |
unload(), which can be called to increase or decrease the load reference |
| 89 |
count of a resource. At the first load the resource will emit its sig_load |
| 90 |
signal, and at the last unload the sig_unload signal is emitted. This can be |
| 91 |
used to load additional shared data related to a resource.</p> |
| 92 |
|
| 93 |
<p>It is possible to attach data objects to a resource. Such additional data |
| 94 |
is attached by deriving <codelink>CL_ResourceData</codelink> and then using |
| 95 |
the attach_data function on CL_Resource to attach it. Any other part of the |
| 96 |
application can then get the pointer to the data object by calling get_data |
| 97 |
via CL_Resource.</p> |
| 98 |
|
| 99 |
<p>To allow a more automatic way of attaching data objects to resources, |
| 100 |
CL_ResourceManager provides a static global signal called |
| 101 |
sig_resource_loaded. When a resource definition file is loaded, it will emit |
| 102 |
this signal with each resource found in the definition file. By connecting |
| 103 |
slots to this signal, applications and ClanLib can attach data objects |
| 104 |
transparently at construction time of CL_ResourceManager.</p> |
| 105 |
|
| 106 |
<h3>Built-In Resource Types</h3> |
| 107 |
|
| 108 |
<p>The resource loading system above is used by ClanLib to automatically |
| 109 |
administrate the following resource types:</p> |
| 110 |
|
| 111 |
<ul> |
| 112 |
<li><surface> - represents a <codelink>CL_Surface</codelink></li> |
| 113 |
<li><sprite> - <codelink>CL_Sprite</codelink></li> |
| 114 |
<li><sprite_description> - <codelink>CL_SpriteDescription</codelink></li> |
| 115 |
<li><texture> - <codelink>CL_Texture</codelink></li> |
| 116 |
<li><font> - <codelink>CL_Font</codelink></li> |
| 117 |
<li><string> - <codelink>CL_String</codelink></li> |
| 118 |
<li><integer> - <codelink>CL_Integer</codelink></li> |
| 119 |
<li><boolean> - <codelink>CL_Boolean</codelink></li> |
| 120 |
<li><raw> - <codelink>CL_Raw</codelink></li> |
| 121 |
<li><sample> - <codelink>CL_Sample</codelink></li> |
| 122 |
</ul> |
| 123 |
|
| 124 |
<p>If you create a resource tag of any of these types, you will be able use |
| 125 |
the resource constructor in their equivalent C++ class (eg. |
| 126 |
<codelink>CL_Surface</codelink> for <surface>), like illustrated in |
| 127 |
the following code block:</p> |
| 128 |
|
| 129 |
<code> |
| 130 |
CL_Surface sur_explosion("Game/sur_explosion", &resources); |
| 131 |
</code> |
| 132 |
|
| 133 |
<p>All the resource related constructors use the above syntax in |
| 134 |
ClanLib.</p> |
| 135 |
|
| 136 |
<p>Behind the curtain, ClanLib uses the sig_resource_loaded signal to attach |
| 137 |
a "surface" resource data object to any <surface> resource type. Then |
| 138 |
when the above constructor is called, it will increase the reference count |
| 139 |
on the resource, which causes sig_load to be called on the CL_Resource |
| 140 |
object. The surface resource data object will be listening on this event, |
| 141 |
loading the shared surface data, and finally the CL_Surface constructor |
| 142 |
above will access the shared data calling get_data("surface") on the |
| 143 |
resource. When the local CL_Surface instance is destroyed, the load |
| 144 |
reference count will be decreased again, possibly unloading the shared |
| 145 |
resource data.</p> |
| 146 |
|
| 147 |
<p>This means that constructing another CL_Surface using the same resource |
| 148 |
ID should only cause the load reference count increase - sharing the |
| 149 |
image data together with the other CL_Surface instance.</p> |
| 150 |
|
| 151 |
<h3>Resources In Datafiles</h3> |
| 152 |
|
| 153 |
<p>It is possible to compile resources used in a resource definition file |
| 154 |
into a datafile. This can be useful for a various of reasons, the two most |
| 155 |
obvious being having only one file containing a large set of resource data, |
| 156 |
and compression of resource data. The datafile format of choice in ClanLib |
| 157 |
is zip - ClanLib has native zip archive support via the |
| 158 |
<codelink>CL_Zip_Archive</codelink> interface. To create a datafile for your |
| 159 |
resources, simply zip the resource definition file and its related resource |
| 160 |
data files into an archive and construct your resources like this:</p> |
| 161 |
|
| 162 |
<code> |
| 163 |
CL_ResourceManager resources( |
| 164 |
"resources.xml", |
| 165 |
new CL_Zip_Archive("resources.zip"), |
| 166 |
true); |
| 167 |
</code> |
| 168 |
|
| 169 |
<p>That's it. Resources are now loaded from the zip archive instead. The |
| 170 |
above code will cause it look for a resource definition file called |
| 171 |
resources.xml inside the resources.zip</p> |
| 172 |
|
| 173 |
<p>There's one little detail worth paying attention to: compression. |
| 174 |
Depending on speed versus size, you may want to instruct your zipping tool |
| 175 |
to store (some or all) files in uncompressed form inside the archive. |
| 176 |
Loading from an uncompressed file is in most cases faster, but in particular |
| 177 |
if a resource needs to do random file access (seek around in a file), |
| 178 |
compressed files can produce a significant overhead.</p> |
| 179 |
|
| 180 |
<h3>Using Multiple Resource Definition Files</h3> |
| 181 |
|
| 182 |
<p>The resource management system in ClanLib supports setting up a search |
| 183 |
tree for additional resources provided via other resource managers. Using |
| 184 |
this feature it is possible to have one central resource file with general |
| 185 |
resources, and other resource files for each level or mod for a game. The |
| 186 |
following code chunk illustrates how to set it up:</p> |
| 187 |
|
| 188 |
<code> |
| 189 |
CL_ResourceManager resources_global("global.xml"); |
| 190 |
CL_ResourceManager resources_mod("mod.xml"); |
| 191 |
CL_ResourceManager resources_level("level.xml"); |
| 192 |
resources_level.add_resources(resources_mod); |
| 193 |
resources_level.add_resources(resources_global); |
| 194 |
</code> |
| 195 |
|
| 196 |
<p>When requesting a resource from resources_level, it will first search its |
| 197 |
local resources, then from resources_mod and finally from |
| 198 |
resources_global.</p> |
| 199 |
|
| 200 |
<!-- Old resource docs: |
| 201 |
|
| 202 |
<p>The purpose of these resource types should be self explanatory. Each |
| 203 |
resource type has several configuration options associated with it. All |
| 204 |
options in the resource definition file must be enterered within the |
| 205 |
parantheses following the physical resource location, and must be separated |
| 206 |
by commas. A later part of this overview will describe the options |
| 207 |
associated with each resource type.</p> |
| 208 |
|
| 209 |
<h3>A resource usage example</h3> |
| 210 |
|
| 211 |
<p>Let us look at an example resource definition file, and see how that can |
| 212 |
be translated to resources usable by the ClanLib classes during runtime:</p> |
| 213 |
|
| 214 |
<code> |
| 215 |
res_surface = test.tga (type=surface); |
| 216 |
res_sample = test.wav (type=sample); |
| 217 |
</code> |
| 218 |
|
| 219 |
<p>As mentioned previously, this definition file is interfaced to via the |
| 220 |
<codelink>CL_ResourceManager</codelink> class. The |
| 221 |
<codelink>CL_ResourceManager</codelink> is created using the following |
| 222 |
constructor:</p> |
| 223 |
|
| 224 |
<code> |
| 225 |
CL_ResourceManager::CL_ResourceManager( |
| 226 |
const char *file_name, |
| 227 |
const bool is_datafile); |
| 228 |
</code> |
| 229 |
|
| 230 |
<p>It receives as input the name of a file. If 'is_datafile' is true, the |
| 231 |
filename is assumed to be the filename of a datafile, containing both the |
| 232 |
resource definition file, and the resources. If not, the filename is assumed |
| 233 |
to be the name of the resource definition file. If the resource definition |
| 234 |
file cannot be found, or if a syntax error is found during parsing of the |
| 235 |
resource definition file, an exception of type <codelink>CL_Error</codelink> |
| 236 |
is thrown.</p> |
| 237 |
|
| 238 |
<p>The instantiated <codelink>CL_ResourceManager</codelink> class, is in |
| 239 |
most cases only used indirectly. Classes like |
| 240 |
<codelink>CL_Surface</codelink> and <codelink>CL_SoundBuffer</codelink> have |
| 241 |
resource load constructors, receiving as argument a pointer to the |
| 242 |
instantiated resource manager, as well as a resource id specifying the |
| 243 |
specific resource to be loaded as data for that given object.</p> |
| 244 |
|
| 245 |
<p>When using resources, make sure you include <ClanLib/core.h></p> |
| 246 |
|
| 247 |
<p>Some example code could look like this:</p> |
| 248 |
<code> |
| 249 |
// my_resources.scr: |
| 250 |
section Surfaces |
| 251 |
{ |
| 252 |
my_surface = test.tga (type=surface); |
| 253 |
} |
| 254 |
|
| 255 |
CL_ResourceManager manager( |
| 256 |
"my_resources.scr", // Name of resource definition file |
| 257 |
false); // This is not read from a datafile - load resource data through normal files |
| 258 |
|
| 259 |
CL_Surface my_surface("Surfaces/my_surface", &manager); |
| 260 |
</code> |
| 261 |
|
| 262 |
<h3>Compiling resourcefiles</h3> |
| 263 |
|
| 264 |
<p>As mentioned briefly already, resource definition files can be compiled |
| 265 |
into a datafile, which will contain both the resource definition file, and |
| 266 |
the all resources in one big file.</p> |
| 267 |
|
| 268 |
<p>To compile your datafile, add this code:</p> |
| 269 |
|
| 270 |
<code> |
| 271 |
CL_DatafileCompiler::write("my_resources.scr", "my_resources.dat"); |
| 272 |
</code> |
| 273 |
|
| 274 |
<p>This compiles the resource-file my_resources.scr into a datafile called |
| 275 |
my_resources.dat. Normally, the datafile compiler can be made available |
| 276 |
through a command-line interface or similar.</p> |
| 277 |
|
| 278 |
<p>Now, to create a resourcemanager from a compiled datafile, use the |
| 279 |
following code:</p> |
| 280 |
|
| 281 |
<code> |
| 282 |
CL_ResourceManager manager( |
| 283 |
"my_resources.dat", // Name of resource file |
| 284 |
true); // This is read from a datafile - load resource data through a packed resourcefile |
| 285 |
</code> |
| 286 |
|
| 287 |
<h3>Resource sections</h3> |
| 288 |
|
| 289 |
<p>As you may have noted in the previous section, my_resources.scr, contains |
| 290 |
a 'section Surfaces' construct. 'section' is a keyword in ClanLib resource |
| 291 |
definition files, and sections can be build up, to provide better grouping |
| 292 |
of resources. Sections can be nested inside each other, but a resource can |
| 293 |
be a part of only one section (as the resource name is qualified with the |
| 294 |
section hierachy of which it is a part (as in "Surfaces/my_surface")). The |
| 295 |
syntax of a resource section is as follows:</p> |
| 296 |
|
| 297 |
<code> |
| 298 |
section MySection |
| 299 |
{ |
| 300 |
section MyNestedSection |
| 301 |
{ |
| 302 |
my_resource = resource.tga (type=surface); |
| 303 |
} |
| 304 |
} |
| 305 |
</code> |
| 306 |
|
| 307 |
<p>'my_resource' has the following fully qualified resource_id: |
| 308 |
"MySection/MyNestedSection/my_resource".</p> |
| 309 |
|
| 310 |
<p>One of the advantages of grouping is that you can load all resources in a |
| 311 |
group into memory at once. This allows your game to do all in-game loading |
| 312 |
at game start, instead of loading the resources as they are used in the |
| 313 |
game. The following code will do that:</p> |
| 314 |
|
| 315 |
<code> |
| 316 |
manager.load_section("MySection"); |
| 317 |
</code> |
| 318 |
|
| 319 |
<p>When you load an entire section of resources, you will have to inform the |
| 320 |
resource manager when it can unload them from memory again. All the |
| 321 |
resources in ClanLib are reference counted, and if you do not call the |
| 322 |
CL_ResourceManager::unload_section() function, your application will memory |
| 323 |
leak!</p> |
| 324 |
|
| 325 |
<p><a href="resources-2.html">Move on to part two</a>.</p> |
| 326 |
--> |
| 327 |
</body> |
| 328 |
</xml> |