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 */ ImageManager()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 398