juce/source/src/gui/graphics/imaging/juce_ImageCache.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_IMAGECACHE_JUCEHEADER__
  27 #define __JUCE_IMAGECACHE_JUCEHEADER__
  28
  29 #include "juce_Image.h"
  30 #include "../../../io/files/juce_File.h"
  31
  32
  33 //==============================================================================
  34 /**
  35     A global cache of images that have been loaded from files or memory.
  36
  37     If you're loading an image and may need to use the image in more than one
  38     place, this is used to allow the same image to be shared rather than loading
  39     multiple copies into memory.
  40
  41     Another advantage is that after images are released, they will be kept in
  42     memory for a few seconds before it is actually deleted, so if you're repeatedly
  43     loading/deleting the same image, it'll reduce the chances of having to reload it
  44     each time.
  45
  46     @see Image, ImageFileFormat
  47 */
  48 class JUCE_API  ImageCache
  49 {
  50 public:
  51     //==============================================================================
  52     /** Loads an image from a file, (or just returns the image if it's already cached).
  53
  54         If the cache already contains an image that was loaded from this file,
  55         that image will be returned. Otherwise, this method will try to load the
  56         file, add it to the cache, and return it.
  57
  58         Remember that the image returned is shared, so drawing into it might
  59         affect other things that are using it! If you want to draw on it, first
  60         call Image::duplicateIfShared()
  61
  62         @param file     the file to try to load
  63         @returns        the image, or null if it there was an error loading it
  64         @see getFromMemory, getFromCache, ImageFileFormat::loadFrom
  65     */
  66     static Image getFromFile (const File& file);
  67
  68     /** Loads an image from an in-memory image file, (or just returns the image if it's already cached).
  69
  70         If the cache already contains an image that was loaded from this block of memory,
  71         that image will be returned. Otherwise, this method will try to load the
  72         file, add it to the cache, and return it.
  73
  74         Remember that the image returned is shared, so drawing into it might
  75         affect other things that are using it! If you want to draw on it, first
  76         call Image::duplicateIfShared()
  77
  78         @param imageData    the block of memory containing the image data
  79         @param dataSize     the data size in bytes
  80         @returns            the image, or an invalid image if it there was an error loading it
  81         @see getFromMemory, getFromCache, ImageFileFormat::loadFrom
  82     */
  83     static Image getFromMemory (const void* imageData, int dataSize);
  84
  85     //==============================================================================
  86     /** Checks the cache for an image with a particular hashcode.
  87
  88         If there's an image in the cache with this hashcode, it will be returned,
  89         otherwise it will return an invalid image.
  90
  91         @param hashCode the hash code that was associated with the image by addImageToCache()
  92         @see addImageToCache
  93     */
  94     static Image getFromHashCode (int64 hashCode);
  95
  96     /** Adds an image to the cache with a user-defined hash-code.
  97
  98         The image passed-in will be referenced (not copied) by the cache, so it's probably
  99         a good idea not to draw into it after adding it, otherwise this will affect all
 100         instances of it that may be in use.
 101
 102         @param image    the image to add
 103         @param hashCode the hash-code to associate with it
 104         @see getFromHashCode
 105     */
 106     static void addImageToCache (const Image& image, int64 hashCode);
 107
 108     /** Changes the amount of time before an unused image will be removed from the cache.
 109         By default this is about 5 seconds.
 110     */
 111     static void setCacheTimeout (int millisecs);
 112
 113
 114 private:
 115     //==============================================================================
 116     class Pimpl;
 117     friend class Pimpl;
 118
 119     ImageCache();
 120     ~ImageCache();
 121
 122     JUCE_DECLARE_NON_COPYABLE (ImageCache);
 123 };
 124
 125 #endif   // __JUCE_IMAGECACHE_JUCEHEADER__