Debian Codegraph @

Documentation/Overview/resources-2.xml

raw
1 <xml>
2 <head>
3 <title>Resource API Overview - Part 2</title>
4 </head>
5 <body>
6
7 <h3>Custom resources</h3>
8
9 <p>It is possible to add your own resource types to clanlib, or even extend the functionality of already
10 existing resource types.</p>
11
12 <p>The resource system uses an interface called CL_ResourceType to identify resource types in the resource
13 files, and instantiate the appropiate data objects for a resource. When a resource is being loaded, the
14 following happens:</p>
15
16 <ul>
17 <li>The resource manager parses a resource description in the resource file, and creates a CL_Resource
18 object containing the description.</li>
19 <li>The manager walks through a linked list of registered resource types, finding all resource types that
20 aknowledges the resource description.</li>
21 <li>Each resource type is asked to create and attach a resource data object (CL_ResourceData) that can
22 handle the resource' data.</li
23 <li>The CL_Resource object has some signals that are invoked when a resource is to be loaded, unloaded, or
24 saved to a datafile. If a resource data object is interesting in reacting on this (a surface resource data
25 object would load the surface into memory on a load signal), they must connect a slot to the appropiate
26 signal.</li>
27 <li>Each resource data object uses a identifying string that can be used to locate the object's pointer.
28 A surface data object might register itself as "surface", and a call to CL_Resource.get_data("surface")
29 will then return a pointer this object.</li>
30 </ul>
31
32 <p>This may sound a little advanced, but a small example will show how simple it can look. First
33 we create our data object:</p>
34
35 <code>
36 // resources.scr:
37 our_map = some_location.map
38 (
39 type=map,
40 size=100x200
41 };
42
43 class ResourceData_Map : public CL_ResourceData
44 {
45 public:
46 ResourceData_Map(CL_Resource &resource)
47 : CL_ResourceData(resource), width(0), height(0), map(NULL)
48 {
49 // Connect to the file load signal:
50 slot_load_file = resource.sig_load_file().connect(this, &ResourceData_Map::on_load_file);
51
52 // Attach resource data object to the resource.
53 resource.attach_data("map", this);
54 }
55
56 ~ResourceData_Map()
57 {
58 delete[] map;
59 }
60
61 void on_load_file()
62 {
63 // get the size option (100x200)
64 CL_ResourceOption &size_opt = get_resource().get_options().get_option("size");
65
66 // get the first value of the size (100)
67 width = CL_String(size_opt.get_value(0)).get_as_int();
68
69 // get the second value of the size (200)
70 height = CL_String(size_opt.get_value(1)).get_as_int();
71
72 // allocate memory for the map
73 map = new char[width*height];
74
75 // open the file "some_location.map"
76 FILE *file = fopen(get_resource().get_location().c_str(), "rb");
77 fread(map, width*height, file);
78 fclose(file);
79 }
80
81 char *map;
82 int width, height;
83 CL_Slot slot_load_file;
84 };
85 </code>
86
87 <p>The data object attaches itself to the resource using the name 'map'. We can obtain a pointer to
88 the object by using the CL_Resource::get_data() function: </p>
89
90 <code>
91 // open the resource file
92 CL_ResourceManager resources("resources.scr", false);
93
94 // get the map resource
95 CL_Resource &map_resource = resources.get_resource("our_map");
96
97 // get the attached Map data from the resource
98 ResourceData_Map *map = (ResourceData_Map*) map_resource.get_data("map");
99 </code>
100
101 <p>Note that the above code will not produce a call to ResourceData_Map::on_load_file(). This will
102 first happen when a call is done to CL_Resource::load(). The same thing applies with unloading; if
103 you loaded an object by calling load(), you must also call unload(). The resource class reference
104 counts the loading, so several objects can call load(), but only the first call will actually perform
105 the load.</p>
106
107 <p>When the resource manager parses the resource file, it will need to know what resource types exist,
108 and how to attach data objects. In order to do this, the resource manager use a linked list of
109 CL_ResourceType objects. It walks through all the resource type objects, and then asks wether it can
110 attach data to the resource. If no resource type recognizes the resource, the resource manager will throw
111 and exception, telling the program that it has encountered an unknown resource type.</p>
112
113 <p>ClanLib contain a template class called CL_RegisterResourceType<ResourceDataClass> that allows you
114 to construct simple resource type objects, that just attach a single data object to the resource. Registration
115 of resource types require that you create an instance of CL_ResourceType. The template class is inheriated
116 from CL_ResourceType and is nothing more than a convience class. An example of its usage:</p>
117
118 <code>
119 void MyApp::main(int argc, char **argv)
120 {
121 CL_SetupCore setup_core;
122
123 CL_RegisterResourceType<ResourceData_Map> resource_type_map("map"); // register resource type 'map'
124 CL_ResourceManager manager("resources.scr", false);
125 CL_Resource &map_resource = manager.get_resource("our_map");
126
127 map_resource.load(); // calls on_load_file() on our data object
128 ResourceData_Map *map = (ResourceData_Map *) map_resource.get_data("map");
129
130 std::cout << "width of map: " << map->width << std::endl;
131
132 map_resource.unload(); // calls on_unload() on our data object
133 }
134 </code>
135
136 <p>That's it! We have constructed our own custom resource.</p>
137
138 <h3>Extending existing resource types</h3>
139
140 <p>It is possible to have several resource type objects for the same resource. This is practical if you
141 want to extend an already existing resource type with more functionality. Each resource type object can
142 attach its own data to the resource object, allowing you to eg. add "animation_data" to a surface type.</p>
143
144 <p>The following is a small example of how to extend the surface type with some additional data:</p>
145
146 <code>
147 class AnimationData;
148
149 class AnimationSurface : public CL_Surface
150 {
151 public:
152 AnimationSurface(const std::string &res_id, CL_ResourceManager *resources)
153 : CL_Surface(res_id, resources)
154 {
155 CL_Resource &resource = resources->get_resource(res_id);
156 anim_data = (AnimationData *) resource.get_data("animation_data");
157 }
158
159 AnimationData *get_anim_data() { return anim_data; }
160
161 private:
162 AnimationData *anim_data;
163 };
164
165 class AnimationData : public CL_ResourceData
166 {
167 public:
168 AnimationData(CL_Resource &resource)
169 {
170 some_data = resource.get_option("anim_data").get_value();
171 resource.attach_data(this);
172 }
173
174 std::string some_data;
175 };
176
177 class MyApplication : public CL_ClanApplication
178 {
179 public:
180 virtual int main(int argc, char **argv)
181 {
182 CL_SetupCore setup_core;
183 CL_SetupGL setup_gl;
184 CL_SetupDisplay setup_display;
185
186 CL_RegisterResourceType<AnimationData> restype_anim("surface");
187
188 CL_DisplayWindow window("Window", 640, 480);
189
190 CL_ResourceManager resources("resources.scr", false);
191 AnimationSurface surf("my_surf", &resources);
192
193 surf.draw(0, 0);
194
195 CL_Display::flip();
196
197 std::cout << "some data: " << surf.get_anim_data()->some_data.c_str() << std::endl;
198
199 return 0;
200 }
201 } app;
202 </code>
203
204 </body>
205 </xml>