Debian Codegraph @

engine/core/video/imagemanager.h

raw
1 /***************************************************************************
2 * Copyright (C) 2005-2019 by the FIFE team *
3 * http://www.fifengine.net *
4 * This file is part of FIFE. *
5 * *
6 * FIFE is free software; you can redistribute it and/or *
7 * modify it under the terms of the GNU Lesser General Public *
8 * License as published by the Free Software Foundation; either *
9 * version 2.1 of the License, or (at your option) any later version. *
10 * *
11 * This library is distributed in the hope that it will be useful, *
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14 * Lesser General Public License for more details. *
15 * *
16 * You should have received a copy of the GNU Lesser General Public *
17 * License along with this library; if not, write to the *
18 * Free Software Foundation, Inc., *
19 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA *
20 ***************************************************************************/
21
22 #ifndef FIFE_IMAGE_MANAGER_H
23 #define FIFE_IMAGE_MANAGER_H
24
25 // Standard C++ library includes
26 #include <map>
27 #include <string>
28 #include <vector>
29
30 // 3rd party library includes
31
32 // FIFE includes
33 // These includes are split up in two parts, separated by one empty line
34 // First block: files included from the FIFE root src directory
35 // Second block: files included from the same folder
36 #include "util/base/singleton.h"
37 #include "util/resource/resource.h"
38 #include "util/resource/resourcemanager.h"
39
40 #include "image.h"
41
42 namespace FIFE {
43
44 /** ImageManager
45 *
46 * An interface for managing images.
47 *
48 * @see IResource
49 * @see IResourceLoader
50 * @see IResourceManager
51 *
52 */
53
54 class ImageManager : public IResourceManager, public DynamicSingleton<ImageManager> {
55 public:
56
57 /** Default constructor.
58 */
59 ImageManager() : IResourceManager() { }
60
61 /** Destructor.
62 */
63 virtual ~ImageManager();
64
65 virtual size_t getMemoryUsed() const;
66 virtual size_t getTotalResourcesCreated() const;
67 virtual size_t getTotalResourcesLoaded() const;
68 virtual size_t getTotalResources() const;
69
70 /** Creates a blank Image but does not load it immediately
71 *
72 * @param loader A pointer to the custom resource loader. The
73 * default is NULL. If this parameter is present the resource
74 * will use the loader to load instead of the default built in
75 * functions.
76 * @return An ImagePtr to the newly created Image
77 *
78 * @see Image
79 * @see ImageLoader
80 * @see IResourceLoader
81 *
82 */
83 virtual ImagePtr create(IResourceLoader* loader = 0);
84
85 /** Creates a blank Image but does not load it immediately
86 *
87 * @param name The resource name. Typically a filename.
88 * @param loader A pointer to the custom resource loader. The
89 * default is NULL. If this parameter is present the resource
90 * will use the loader to load instead of the default built in
91 * functions.
92 * @return An ImagePtr to the newly created Image
93 *
94 * @see Image
95 * @see ImageLoader
96 * @see IResourceLoader
97 *
98 */
99 virtual ImagePtr create(const std::string& name, IResourceLoader* loader = 0);
100
101 /** Creates a blank resource and loads it from disk
102 *
103 * This function will create the Image if necessary and load
104 * the Image from disk. If the Image is not defined it
105 * will call ImageManager::create() before loading.
106 *
107 * @param name The resource name. Typically a filename.
108 * @param loader A pointer to the custom resource loader. The
109 * default is NULL. If this parameter is present the resource
110 * will use the loader to load instead of the default built in
111 * functions.
112 * @return A ImagePtr to the loaded Image
113 *
114 * @see Image
115 * @see ImageLoader
116 * @see IResourceLoader
117 *
118 */
119 virtual ImagePtr load(const std::string& name, IResourceLoader* loader = 0);
120
121 /** Loads a blank resource
122 *
123 * @param width
124 * @param height
125 * @return An ImagePtr to the blank image (ready to be modified)
126 */
127 virtual ImagePtr loadBlank(uint32_t width, uint32_t height);
128
129 /** Loads a blank resource
130 *
131 * @param name
132 * @param width
133 * @param height
134 * @return An ImagePtr to the blank image (ready to be modified)
135 */
136 virtual ImagePtr loadBlank(const std::string& name, uint32_t width, uint32_t height);
137
138 /** Add an Image to the manager
139 *
140 * This function will create a ImagePtr and add the Image
141 * to the manager. The manager assumes ownership of the Image
142 * so DO NOT delete it.
143 *
144 * @param res A pointer to the Image
145 * @return A ImagePtr to the added resource
146 *
147 * @see Image
148 *
149 */
150 virtual ImagePtr add(Image* res);
151
152 /** Checks to see if an Image exists
153 *
154 * This function will search the manager for Images
155 * that match the parameter
156 *
157 * @param name The name of the Image
158 * @return True if the Image exists. False otherwise.
159 *
160 */
161 virtual bool exists(const std::string& name);
162
163 /** Checks to see if an Image exists
164 *
165 * This function will search the manager for Images
166 * that match the parameter
167 *
168 * @param handle The handle of the Image
169 * @return True if the Image exists. False otherwise.
170 *
171 */
172 virtual bool exists(ResourceHandle handle);
173
174 /** Reloads an Image
175 *
176 * This function will reload an Image if it is managed
177 * by the manager. If not it creates an entry in the log
178 * specifying that the Image could not be found. It will
179 * load the Image if it is not already loaded.
180 *
181 * @param name The name of the resource
182 *
183 */
184 virtual void reload(const std::string& name);
185
186 /** Reloads a resource
187 *
188 * This function will reload an Image if it is managed
189 * by the manager. If not it creates an entry in the log
190 * specifying that the Image could not be found. It will
191 * load the Image if it is not already loaded.
192 *
193 * @param handle The handle of the resource
194 *
195 */
196 virtual void reload(ResourceHandle handle);
197
198 /** Reloads all Images
199 *
200 * This function will reload all Images managed by the
201 * manager. It will load an Image if it is not already loaded.
202 *
203 * @todo It might be beneficial to supply a parameter to
204 * only reload resources that are already loaded
205 *
206 */
207 virtual void reloadAll();
208
209 /** Loads all unreferenced Images
210 *
211 * All Images that have no external references will be
212 * loaded into memory.
213 *
214 */
215 virtual void loadUnreferenced();
216
217 /** Frees an Image from memory
218 *
219 * The Image is not deleted but it's data is freed.
220 * This calls the Image::free() function and it is
221 * up to the resource to properly free it's memory. The
222 * manager keeps a reference to the Image in case
223 * its required in the future.
224 *
225 * @param name The name of the Image
226 *
227 * @see Image
228 *
229 */
230 virtual void free(const std::string& name);
231
232 /** Frees an Image from memory
233 *
234 * The Image is not deleted but it's data is freed.
235 * This calls the Image::free() function and it is
236 * up to the resource to properly free it's memory. The
237 * manager keeps a reference to the Image in case
238 * its required in the future.
239 *
240 * @param handle The handle of the Image
241 *
242 * @see Image
243 *
244 */
245 virtual void free(ResourceHandle handle);
246
247 /** Frees all Images
248 *
249 * This calls the Image::free() function for every
250 * Image the manager is managing. It does not remove
251 * them from the manager.
252 *
253 * @see Image
254 *
255 */
256 virtual void freeAll();
257
258 /** Frees all unreferenced Image
259 *
260 * This calls the IResource::free() function for Images
261 * that have no external references to them. It does not
262 * remove them from the manager.
263 *
264 * @see IResource
265 *
266 */
267 virtual void freeUnreferenced();
268
269 /** Removes an Image from the manager
270 *
271 * This removes all references to the Image from the
272 * manager. It does not however guarantee that the resources
273 * destructor is called. If the client has any left over
274 * references to the resource it will not be freed.
275 *
276 * @param resource A ImagePtr to the image to be removed
277 * from the manager
278 *
279 * @note This is useful if you want to remove ownership of a resource
280 * from the manager
281 *
282 * @see Image
283 *
284 */
285 virtual void remove(ImagePtr& resource);
286
287 /** Removes an Image from the manager
288 *
289 * This removes all references to the Image from the
290 * manager. It does not however guarantee that the resources
291 * destructor is called. If the client has any left over
292 * references to the resource it will not be freed.
293 *
294 * @param name The name of the Image
295 *
296 * @see Image
297 *
298 */
299 virtual void remove(const std::string& name);
300
301 /** Removes an Image from the manager
302 *
303 * This removes all references to the Image from the
304 * manager. It does not however guarantee that the resources
305 * destructor is called. If the client has any left over
306 * references to the resource it will not be freed.
307 *
308 * @param handle The handle of the Image
309 *
310 * @see Image
311 *
312 */
313 virtual void remove(ResourceHandle handle);
314
315 /** Removes all Images from the manager
316 *
317 * This effectively removes all references to all Images from
318 * the manager. If there are left over shared pointers to
319 * any resources they will not be deleted.
320 *
321 * @see Image
322 *
323 */
324 virtual void removeAll();
325
326 /** Removes all unreferenced Images
327 *
328 * This effectively removes all Images that dont have an
329 * external reference. The resources will be deleted.
330 *
331 * @see Image
332 *
333 */
334 virtual void removeUnreferenced();
335
336 /** Gets a shared pointer to the Image
337 *
338 * If the Image is not defined it will attempt to create
339 * and load the Image based on the name (it assumes the name
340 * is a filename)
341 *
342 * @param name The name of the Image
343 * @return An ImagePtr to the Image
344 *
345 */
346 virtual ImagePtr get(const std::string& name);
347
348 /** Gets a shared pointer to the Image
349 *
350 * If the resource is not defined it returns an empty
351 * (or invalid) ImagePtr and makes an entry in the log.
352 *
353 * @param handle The handle of the resource
354 * @return A ImagePtr to the resource
355 *
356 * @todo This should throw an exception instead of an
357 * empty ImagePtr
358 *
359 */
360 virtual ImagePtr get(ResourceHandle handle);
361
362 virtual ImagePtr getPtr(const std::string& name);
363 virtual ImagePtr getPtr(ResourceHandle handle);
364
365 /** Gets an Image handle by name
366 *
367 * Returns the Image handle associated with the name
368 *
369 * @param name The name of the Image
370 * @return 0 if the resource name is invalid
371 *
372 */
373 virtual ResourceHandle getResourceHandle(const std::string& name);
374
375 virtual void invalidate(const std::string& name);
376 virtual void invalidate(ResourceHandle handle);
377 virtual void invalidateAll();
378
379 private:
380 typedef std::map< ResourceHandle, ImagePtr > ImageHandleMap;
381 typedef std::map< ResourceHandle, ImagePtr >::iterator ImageHandleMapIterator;
382 typedef std::map< ResourceHandle, ImagePtr >::const_iterator ImageHandleMapConstIterator;
383 typedef std::pair< ResourceHandle, ImagePtr > ImageHandleMapPair;
384
385 typedef std::map< std::string, ImagePtr > ImageNameMap;
386 typedef std::map< std::string, ImagePtr >::iterator ImageNameMapIterator;
387 typedef std::map< std::string, ImagePtr >::const_iterator ImageNameMapConstIterator;
388 typedef std::pair< std::string, ImagePtr > ImageNameMapPair;
389
390 ImageHandleMap m_imgHandleMap;
391
392 ImageNameMap m_imgNameMap;
393 };
394
395 } //FIFE
396
397 #endif //FIFE_IMAGE_MANAGER_H