src/graphics/GraphicsCache.h

   1 // -*- C++ -*-
   2 /**
   3  *  \file GraphicsCache.h
   4  *  Read the file COPYING
   5  *
   6  * \author Baruch Even
   7  * \author Angus Leeming
   8  *
   9  * Full author contact details available in file CREDITS
  10  *
  11  *  grfx::Cache is the manager of the image cache.
  12  *  It is responsible for creating the grfx::CacheItem's and maintaining them.
  13  *
  14  *  grfx::Cache is a singleton class. It is possible to have only one
  15  *  instance of it at any moment.
  16  */
  17
  18 #ifndef GRAPHICSCACHE_H
  19 #define GRAPHICSCACHE_H
  20
  21 #ifdef __GNUG__
  22 #pragma interface
  23 #endif
  24
  25 #include "LString.h"
  26 #include <vector>
  27 #include <boost/utility.hpp>
  28 #include <boost/scoped_ptr.hpp>
  29 #include <boost/shared_ptr.hpp>
  30
  31
  32 namespace grfx {
  33
  34 class CacheItem;
  35
  36 class Cache : boost::noncopyable {
  37 public:
  38
  39         /// This is a singleton class. Get the instance.
  40         static Cache & get();
  41
  42         /** Which graphics formats can be loaded directly by the image loader.
  43          *  Other formats can be loaded if a converter to a loadable format
  44          *  can be defined.
  45          */
  46         std::vector<string> loadableFormats() const;
  47
  48         /// Add a graphics file to the cache.
  49         void add(string const & file) const;
  50
  51         /// Remove a file from the cache.
  52         void remove(string const & file) const;
  53
  54         /// Returns \c true if the file is in the cache.
  55         bool inCache(string const & file) const;
  56
  57         /** Get the cache item associated with file.
  58          *  Returns an empty container if there is no such item.
  59          *
  60          *  IMPORTANT: whatever uses an image must make a local copy of this
  61          *  ItemPtr. The boost::shared_ptr<>::use_count() function is
  62          *  used to ascertain whether or not to remove the item from the cache
  63          *  when remove(file) is called.
  64          *
  65          *  You have been warned!
  66          */
  67         typedef boost::shared_ptr<CacheItem> ItemPtr;
  68         ///
  69         ItemPtr const item(string const & file) const;
  70
  71 private:
  72         /** Make the c-tor, d-tor private so we can control how many objects
  73          *  are instantiated.
  74          */
  75         Cache();
  76         ///
  77         ~Cache();
  78
  79         /// Use the Pimpl idiom to hide the internals.
  80         class Impl;
  81         /// The pointer never changes although *pimpl_'s contents may.
  82         boost::scoped_ptr<Impl> const pimpl_;
  83 };
  84
  85 } // namespace grfx
  86
  87 #endif // GRAPHICSCACHE_H