xbmc/TextureCache.h

   1 /*
   2  *      Copyright (C) 2005-2013 Team XBMC
   3  *      http://xbmc.org
   4  *
   5  *  This Program is free software; you can redistribute it and/or modify
   6  *  it under the terms of the GNU General Public License as published by
   7  *  the Free Software Foundation; either version 2, or (at your option)
   8  *  any later version.
   9  *
  10  *  This Program is distributed in the hope that it will be useful,
  11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  *  GNU General Public License for more details.
  14  *
  15  *  You should have received a copy of the GNU General Public License
  16  *  along with XBMC; see the file COPYING.  If not, see
  17  *  <http://www.gnu.org/licenses/>.
  18  *
  19  */
  20
  21 #pragma once
  22
  23 #include <set>
  24 #include "utils/StdString.h"
  25 #include "utils/JobManager.h"
  26 #include "TextureDatabase.h"
  27 #include "threads/Event.h"
  28
  29 class CURL;
  30 class CBaseTexture;
  31
  32 /*!
  33  \ingroup textures
  34  \brief Texture cache class for handling the caching of images.
  35
  36  Manages the caching of images for use as control textures. Images are cached
  37  both as originals (direct copies) and as .dds textures for fast loading. Images
  38  may be periodically checked for updates and may be purged from the cache if
  39  unused for a set period of time.
  40
  41  */
  42 class CTextureCache : public CJobQueue
  43 {
  44 public:
  45   /*!
  46    \brief The only way through which the global instance of the CTextureCache should be accessed.
  47    \return the global instance.
  48    */
  49   static CTextureCache &Get();
  50
  51   /*! \brief Initalize the texture cache
  52    */
  53   void Initialize();
  54
  55   /*! \brief Deinitialize the texture cache
  56    */
  57   void Deinitialize();
  58
  59   /*! \brief Check whether we already have this image cached
  60
  61    Check and return URL to cached image if it exists; If not, return empty string.
  62    If the image is cached, return URL (for original image or .dds version if requested)
  63    Creates a .dds of image if requested via returnDDS and the image doesn't need recaching.
  64
  65    \param image url of the image to check
  66    \param returnDDS if we're allowed to return a DDS version, defaults to true
  67    \param needsRecaching [out] whether the image needs recaching.
  68    \return cached url of this image
  69    \sa GetCachedImage
  70    */
  71   CStdString CheckCachedImage(const CStdString &image, bool returnDDS, bool &needsRecaching);
  72
  73   /*! \brief Cache image (if required) using a background job
  74
  75    Checks firstly whether an image is already cached, and return URL if so [see CheckCacheImage]
  76    If the image is not yet in the database, a background job is started to
  77    cache the image and add to the database [see CTextureCacheJob]
  78
  79    \param image url of the image to cache
  80    \sa CacheImage
  81    */
  82   void BackgroundCacheImage(const CStdString &image);
  83
  84   /*! \brief Cache an image to image cache, optionally return the texture
  85
  86    Caches the given image, returning the texture if the caller wants it.
  87
  88    \param image url of the image to cache
  89    \param texture [out] the loaded image
  90    \param details [out] details of the cached image
  91    \return cached url of this image
  92    \sa CTextureCacheJob::CacheTexture
  93    */
  94   CStdString CacheImage(const CStdString &url, CBaseTexture **texture = NULL, CTextureDetails *details = NULL);
  95
  96   /*! \brief Cache an image to image cache if not already cached, returning the image details.
  97    \param image url of the image to cache.
  98    \param details [out] the image details.
  99    \return true if the image is in the cache, false otherwise.
 100    \sa CTextureCacheJob::CacheTexture
 101    */
 102   bool CacheImage(const CStdString &image, CTextureDetails &details);
 103
 104   /*! \brief Check whether an image is in the cache
 105    Note: If the image url won't normally be cached (eg a skin image) this function will return false.
 106    \param image url of the image
 107    \return true if the image is cached, false otherwise
 108    \sa ClearCachedImage
 109    */
 110   bool HasCachedImage(const CStdString &image);
 111
 112   /*! \brief clear the cached version of the given image
 113    \param image url of the image
 114    \sa GetCachedImage
 115    */
 116   void ClearCachedImage(const CStdString &image, bool deleteSource = false);
 117
 118   /*! \brief clear the cached version of the image with given id
 119    \param database id of the image
 120    \sa GetCachedImage
 121    */
 122   bool ClearCachedImage(int textureID);
 123
 124   /*! \brief retrieve a cache file (relative to the cache path) to associate with the given image, excluding extension
 125    Use GetCachedPath(GetCacheFile(url)+extension) for the full path to the file.
 126    \param url location of the image
 127    \return a "unique" filename for the associated cache file, excluding extension
 128    */
 129   static CStdString GetCacheFile(const CStdString &url);
 130
 131   /*! \brief retrieve the full path of the given cached file
 132    \param file name of the file
 133    \return full path of the cached file
 134    */
 135   static CStdString GetCachedPath(const CStdString &file);
 136
 137   /*! \brief check whether an image:// URL may be cached
 138    \param url the URL to the image
 139    \return true if the given URL may be cached, false otherwise
 140    */
 141   static bool CanCacheImageURL(const CURL &url);
 142
 143   /*! \brief Add this image to the database
 144    Thread-safe wrapper of CTextureDatabase::AddCachedTexture
 145    \param image url of the original image
 146    \param details the texture details to add
 147    \return true if we successfully added to the database, false otherwise.
 148    */
 149   bool AddCachedTexture(const CStdString &image, const CTextureDetails &details);
 150
 151   /*! \brief Export a (possibly) cached image to a file
 152    \param image url of the original image
 153    \param destination url of the destination image, excluding extension.
 154    \param overwrite whether to overwrite the destination if it exists (TODO: Defaults to false)
 155    \return true if we successfully exported the file, false otherwise.
 156    */
 157   bool Export(const CStdString &image, const CStdString &destination, bool overwrite);
 158   bool Export(const CStdString &image, const CStdString &destination); // TODO: BACKWARD COMPATIBILITY FOR MUSIC THUMBS
 159 private:
 160   // private construction, and no assignements; use the provided singleton methods
 161   CTextureCache();
 162   CTextureCache(const CTextureCache&);
 163   CTextureCache const& operator=(CTextureCache const&);
 164   virtual ~CTextureCache();
 165
 166   /*! \brief Check if the given image is a cached image
 167    \param image url of the image
 168    \return true if this is a cached image, false otherwise.
 169    */
 170   bool IsCachedImage(const CStdString &image) const;
 171
 172   /*! \brief retrieve the cached version of the given image (if it exists)
 173    \param image url of the image
 174    \param details [out] the details of the texture.
 175    \param trackUsage whether this call should track usage of the image (defaults to false)
 176    \return cached url of this image, empty if none exists
 177    \sa ClearCachedImage, CTextureDetails
 178    */
 179   CStdString GetCachedImage(const CStdString &image, CTextureDetails &details, bool trackUsage = false);
 180
 181   /*! \brief Get an image from the database
 182    Thread-safe wrapper of CTextureDatabase::GetCachedTexture
 183    \param image url of the original image
 184    \param details [out] texture details from the database (if available)
 185    \return true if we have a cached version of this image, false otherwise.
 186    */
 187   bool GetCachedTexture(const CStdString &url, CTextureDetails &details);
 188
 189   /*! \brief Clear an image from the database
 190    Thread-safe wrapper of CTextureDatabase::ClearCachedTexture
 191    \param image url of the original image
 192    \param cacheFile [out] url of the cached original (if available)
 193    \return true if we had a cached version of this image, false otherwise.
 194    */
 195   bool ClearCachedTexture(const CStdString &url, CStdString &cacheFile);
 196   bool ClearCachedTexture(int textureID, CStdString &cacheFile);
 197
 198   /*! \brief Increment the use count of a texture
 199    Stores locally before calling CTextureDatabase::IncrementUseCount via a CUseCountJob
 200    \sa CUseCountJob, CTextureDatabase::IncrementUseCount
 201    */
 202   void IncrementUseCount(const CTextureDetails &details);
 203
 204   /*! \brief Set a previously cached texture as valid in the database
 205    Thread-safe wrapper of CTextureDatabase::SetCachedTextureValid
 206    \param image url of the original image
 207    \param updateable whether this image should be checked for updates
 208    \return true if successful, false otherwise.
 209    */
 210   bool SetCachedTextureValid(const CStdString &url, bool updateable);
 211
 212   virtual void OnJobComplete(unsigned int jobID, bool success, CJob *job);
 213   virtual void OnJobProgress(unsigned int jobID, unsigned int progress, unsigned int total, const CJob *job);
 214
 215   /*! \brief Called when a caching job has completed.
 216    Removes the job from our processing list, updates the database
 217    and fires a DDS job if appropriate.
 218    \param success whether the job was successful.
 219    \param job the caching job.
 220    */
 221   void OnCachingComplete(bool success, CTextureCacheJob *job);
 222
 223   CCriticalSection m_databaseSection;
 224   CTextureDatabase m_database;
 225   std::set<CStdString> m_processinglist; ///< currently processing list to avoid 2 jobs being processed at once
 226   CCriticalSection     m_processingSection;
 227   CEvent               m_completeEvent; ///< Set whenever a job has finished
 228   std::vector<CTextureDetails> m_useCounts; ///< Use count tracking
 229   CCriticalSection             m_useCountSection;
 230 };
 231