Debian Codegraph @

Documentation/Overview/resources-1.xml

raw
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 &lt;resources&gt; tag. It can then be followed either by the special
56 &lt;section&gt; 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 &lt;section&gt; element will be considered a
65 resource. You can create as many custom resource element types as you want,
66 in this example the &lt;customtype&gt; 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>&lt;surface&gt; - represents a <codelink>CL_Surface</codelink></li>
113 <li>&lt;sprite&gt; - <codelink>CL_Sprite</codelink></li>
114 <li>&lt;sprite_description&gt; - <codelink>CL_SpriteDescription</codelink></li>
115 <li>&lt;texture&gt; - <codelink>CL_Texture</codelink></li>
116 <li>&lt;font&gt; - <codelink>CL_Font</codelink></li>
117 <li>&lt;string&gt; - <codelink>CL_String</codelink></li>
118 <li>&lt;integer&gt; - <codelink>CL_Integer</codelink></li>
119 <li>&lt;boolean&gt; - <codelink>CL_Boolean</codelink></li>
120 <li>&lt;raw&gt; - <codelink>CL_Raw</codelink></li>
121 <li>&lt;sample&gt; - <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 &lt;surface&gt;), 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 &lt;surface&gt; 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>