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