xbmc/TextureCache.h

   1 /*
   2  *  Copyright (C) 2005-2018 Team Kodi
   3  *  This file is part of Kodi - https://kodi.tv
   4  *
   5  *  SPDX-License-Identifier: GPL-2.0-or-later
   6  *  See LICENSES/README.md for more information.
   7  */
   8
   9 #pragma once
  10
  11 #include "TextureCacheJob.h"
  12 #include "TextureDatabase.h"
  13 #include "threads/CriticalSection.h"
  14 #include "threads/Event.h"
  15 #include "utils/JobManager.h"
  16
  17 #include <memory>
  18 #include <set>
  19 #include <string>
  20 #include <vector>
  21
  22 class CJob;
  23 class CURL;
  24 class CTexture;
  25
  26 /*!
  27  \ingroup textures
  28  \brief Texture cache class for handling the caching of images.
  29
  30  Manages the caching of images for use as control textures. Images are cached
  31  both as originals (direct copies) and as .dds textures for fast loading. Images
  32  may be periodically checked for updates and may be purged from the cache if
  33  unused for a set period of time.
  34
  35  */
  36 class CTextureCache : public CJobQueue
  37 {
  38 public:
  39   CTextureCache();
  40   ~CTextureCache() override;
  41
  42   /*! \brief Initialize the texture cache
  43    */
  44   void Initialize();
  45
  46   /*! \brief Deinitialize the texture cache
  47    */
  48   void Deinitialize();
  49
  50   /*! \brief Check whether we already have this image cached
  51
  52    Check and return URL to cached image if it exists; If not, return empty string.
  53    If the image is cached, return URL (for original image or .dds version if requested)
  54
  55    \param image url of the image to check
  56    \param needsRecaching [out] whether the image needs recaching.
  57    \return cached url of this image
  58    \sa GetCachedImage
  59    */
  60   std::string CheckCachedImage(const std::string &image, bool &needsRecaching);
  61
  62   /*! \brief Cache image (if required) using a background job
  63
  64    Checks firstly whether an image is already cached, and return URL if so [see CheckCacheImage]
  65    If the image is not yet in the database, a background job is started to
  66    cache the image and add to the database [see CTextureCacheJob]
  67
  68    \param image url of the image to cache
  69    \sa CacheImage
  70    */
  71   void BackgroundCacheImage(const std::string &image);
  72
  73   /*! \brief Updates the in-process list.
  74
  75    Inserts the image url into the currently processing list
  76    to avoid 2 jobs being processed at once
  77
  78    \param image url of the image to start processing
  79    \return true if list updated, false otherwise
  80    \sa CacheImage
  81    */
  82   bool StartCacheImage(const std::string& 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   std::string CacheImage(const std::string& image,
  95                          std::unique_ptr<CTexture>* texture = nullptr,
  96                          CTextureDetails* details = nullptr);
  97
  98   /*! \brief Cache an image to image cache if not already cached, returning the image details.
  99    \param image url of the image to cache.
 100    \param details [out] the image details.
 101    \return true if the image is in the cache, false otherwise.
 102    \sa CTextureCacheJob::CacheTexture
 103    */
 104   bool CacheImage(const std::string &image, CTextureDetails &details);
 105
 106   /*! \brief Check whether an image is in the cache
 107    Note: If the image url won't normally be cached (eg a skin image) this function will return false.
 108    \param image url of the image
 109    \return true if the image is cached, false otherwise
 110    \sa ClearCachedImage
 111    */
 112   bool HasCachedImage(const std::string &image);
 113
 114   /*! \brief clear the cached version of the given image
 115    \param image url of the image
 116    \sa GetCachedImage
 117    */
 118   void ClearCachedImage(const std::string &image, bool deleteSource = false);
 119
 120   /*! \brief clear the cached version of the image with given id
 121    \param database id of the image
 122    \sa GetCachedImage
 123    */
 124   bool ClearCachedImage(int textureID);
 125
 126   /*! \brief retrieve a cache file (relative to the cache path) to associate with the given image, excluding extension
 127    Use GetCachedPath(GetCacheFile(url)+extension) for the full path to the file.
 128    \param url location of the image
 129    \return a "unique" filename for the associated cache file, excluding extension
 130    */
 131   static std::string GetCacheFile(const std::string &url);
 132
 133   /*! \brief retrieve the full path of the given cached file
 134    \param file name of the file
 135    \return full path of the cached file
 136    */
 137   static std::string GetCachedPath(const std::string &file);
 138
 139   /*! \brief check whether an image:// URL may be cached
 140    \param url the URL to the image
 141    \return true if the given URL may be cached, false otherwise
 142    */
 143   static bool CanCacheImageURL(const CURL &url);
 144
 145   /*! \brief Add this image to the database
 146    Thread-safe wrapper of CTextureDatabase::AddCachedTexture
 147    \param image url of the original image
 148    \param details the texture details to add
 149    \return true if we successfully added to the database, false otherwise.
 150    */
 151   bool AddCachedTexture(const std::string &image, const CTextureDetails &details);
 152
 153   /*! \brief Export a (possibly) cached image to a file
 154    \param image url of the original image
 155    \param destination url of the destination image, excluding extension.
 156    \param overwrite whether to overwrite the destination if it exists (TODO: Defaults to false)
 157    \return true if we successfully exported the file, false otherwise.
 158    */
 159   bool Export(const std::string &image, const std::string &destination, bool overwrite);
 160   bool Export(const std::string &image, const std::string &destination); //! @todo BACKWARD COMPATIBILITY FOR MUSIC THUMBS
 161 private:
 162   // private construction, and no assignments; use the provided singleton methods
 163   CTextureCache(const CTextureCache&) = delete;
 164   CTextureCache const& operator=(CTextureCache const&) = delete;
 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 std::string &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   std::string GetCachedImage(const std::string &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 std::string &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 std::string &url, std::string &cacheFile);
 196   bool ClearCachedTexture(int textureID, std::string &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 std::string &url, bool updateable);
 211
 212   void OnJobComplete(unsigned int jobID, bool success, CJob *job) override;
 213
 214   /*! \brief Called when a caching job has completed.
 215    Removes the job from our processing list, updates the database
 216    and fires a DDS job if appropriate.
 217    \param success whether the job was successful.
 218    \param job the caching job.
 219    */
 220   void OnCachingComplete(bool success, CTextureCacheJob *job);
 221
 222   CCriticalSection m_databaseSection;
 223   CTextureDatabase m_database;
 224   std::set<std::string> m_processinglist; ///< currently processing list to avoid 2 jobs being processed at once
 225   CCriticalSection     m_processingSection;
 226   CEvent               m_completeEvent; ///< Set whenever a job has finished
 227   std::vector<CTextureDetails> m_useCounts; ///< Use count tracking
 228   CCriticalSection             m_useCountSection;
 229 };
 230