code.vuplus.com Git - vuplus_xbmc/blob - xbmc/TextureCache.h

   1 /*
   2  *      Copyright (C) 2005-2013 Team XBMC
   3  *      http://www.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 retrieve a cache file (relative to the cache path) to associate with the given image, excluding extension
 119    Use GetCachedPath(GetCacheFile(url)+extension) for the full path to the file.
 120    \param url location of the image
 121    \return a "unique" filename for the associated cache file, excluding extension
 122    */
 123   static CStdString GetCacheFile(const CStdString &url);
 124
 125   /*! \brief retrieve the full path of the given cached file
 126    \param file name of the file
 127    \return full path of the cached file
 128    */
 129   static CStdString GetCachedPath(const CStdString &file);
 130
 131   /*! \brief retrieve a wrapped URL for a image file
 132    \param image name of the file
 133    \param type signifies a special type of image (eg embedded video thumb, picture folder thumb)
 134    \param options which options we need (eg size=thumb)
 135    \return full wrapped URL of the image file
 136    */
 137   static CStdString GetWrappedImageURL(const CStdString &image, const CStdString &type = "", const CStdString &options = "");
 138   static CStdString GetWrappedThumbURL(const CStdString &image);
 139
 140   /*! \brief Unwrap an image://<url_encoded_path> style URL
 141    Such urls are used for art over the webserver or other users of the VFS
 142    \param image url of the image
 143    \return the unwrapped URL, or the original URL if unwrapping is inappropriate.
 144    */
 145   static CStdString UnwrapImageURL(const CStdString &image);
 146
 147   /*! \brief check whether an image:// URL may be cached
 148    \param url the URL to the image
 149    \return true if the given URL may be cached, false otherwise
 150    */
 151   static bool CanCacheImageURL(const CURL &url);
 152
 153   /*! \brief Add this image to the database
 154    Thread-safe wrapper of CTextureDatabase::AddCachedTexture
 155    \param image url of the original image
 156    \param details the texture details to add
 157    \return true if we successfully added to the database, false otherwise.
 158    */
 159   bool AddCachedTexture(const CStdString &image, const CTextureDetails &details);
 160
 161   /*! \brief Export a (possibly) cached image to a file
 162    \param image url of the original image
 163    \param destination url of the destination image, excluding extension.
 164    \param overwrite whether to overwrite the destination if it exists (TODO: Defaults to false)
 165    \return true if we successfully exported the file, false otherwise.
 166    */
 167   bool Export(const CStdString &image, const CStdString &destination, bool overwrite);
 168   bool Export(const CStdString &image, const CStdString &destination); // TODO: BACKWARD COMPATIBILITY FOR MUSIC THUMBS
 169 private:
 170   // private construction, and no assignements; use the provided singleton methods
 171   CTextureCache();
 172   CTextureCache(const CTextureCache&);
 173   CTextureCache const& operator=(CTextureCache const&);
 174   virtual ~CTextureCache();
 175
 176   /*! \brief Check if the given image is a cached image
 177    \param image url of the image
 178    \return true if this is a cached image, false otherwise.
 179    */
 180   bool IsCachedImage(const CStdString &image) const;
 181
 182   /*! \brief retrieve the cached version of the given image (if it exists)
 183    \param image url of the image
 184    \param details [out] the details of the texture.
 185    \param trackUsage whether this call should track usage of the image (defaults to false)
 186    \return cached url of this image, empty if none exists
 187    \sa ClearCachedImage, CTextureDetails
 188    */
 189   CStdString GetCachedImage(const CStdString &image, CTextureDetails &details, bool trackUsage = false);
 190
 191   /*! \brief Get an image from the database
 192    Thread-safe wrapper of CTextureDatabase::GetCachedTexture
 193    \param image url of the original image
 194    \param details [out] texture details from the database (if available)
 195    \return true if we have a cached version of this image, false otherwise.
 196    */
 197   bool GetCachedTexture(const CStdString &url, CTextureDetails &details);
 198
 199   /*! \brief Clear an image from the database
 200    Thread-safe wrapper of CTextureDatabase::ClearCachedTexture
 201    \param image url of the original image
 202    \param cacheFile [out] url of the cached original (if available)
 203    \return true if we had a cached version of this image, false otherwise.
 204    */
 205   bool ClearCachedTexture(const CStdString &url, CStdString &cacheFile);
 206
 207   /*! \brief Increment the use count of a texture
 208    Stores locally before calling CTextureDatabase::IncrementUseCount via a CUseCountJob
 209    \sa CUseCountJob, CTextureDatabase::IncrementUseCount
 210    */
 211   void IncrementUseCount(const CTextureDetails &details);
 212
 213   /*! \brief Set a previously cached texture as valid in the database
 214    Thread-safe wrapper of CTextureDatabase::SetCachedTextureValid
 215    \param image url of the original image
 216    \param updateable whether this image should be checked for updates
 217    \return true if successful, false otherwise.
 218    */
 219   bool SetCachedTextureValid(const CStdString &url, bool updateable);
 220
 221   virtual void OnJobComplete(unsigned int jobID, bool success, CJob *job);
 222   virtual void OnJobProgress(unsigned int jobID, unsigned int progress, unsigned int total, const CJob *job);
 223
 224   /*! \brief Called when a caching job has completed.
 225    Removes the job from our processing list, updates the database
 226    and fires a DDS job if appropriate.
 227    \param success whether the job was successful.
 228    \param job the caching job.
 229    */
 230   void OnCachingComplete(bool success, CTextureCacheJob *job);
 231
 232   CCriticalSection m_databaseSection;
 233   CTextureDatabase m_database;
 234   std::set<CStdString> m_processing; ///< currently processing list to avoid 2 jobs being processed at once
 235   CCriticalSection     m_processingSection;
 236   CEvent               m_completeEvent; ///< Set whenever a job has finished
 237   std::vector<CTextureDetails> m_useCounts; ///< Use count tracking
 238   CCriticalSection             m_useCountSection;
 239 };
 240