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 "guilib/AspectRatio.h"
  14 #include "threads/CriticalSection.h"
  15 #include "threads/Event.h"
  16 #include "threads/Timer.h"
  17 #include "utils/JobManager.h"
  18
  19 #include <atomic>
  20 #include <chrono>
  21 #include <memory>
  22 #include <set>
  23 #include <string>
  24 #include <vector>
  25
  26 class CGUIDialogProgress;
  27 class CJob;
  28 class CURL;
  29 class CTexture;
  30
  31 /*!
  32  \ingroup textures
  33  \brief Texture cache class for handling the caching of images.
  34
  35  Manages the caching of images for use as control textures. Images are cached
  36  both as originals (direct copies) and as .dds textures for fast loading. Images
  37  may be periodically checked for updates and may be purged from the cache if
  38  unused for a set period of time.
  39
  40  */
  41 class CTextureCache : public CJobQueue
  42 {
  43 public:
  44   CTextureCache();
  45   ~CTextureCache() override;
  46
  47   /*! \brief Initialize the texture cache
  48    */
  49   void Initialize();
  50
  51   /*! \brief Deinitialize the texture cache
  52    */
  53   void Deinitialize();
  54
  55   /*! \brief Check whether we already have this image cached
  56
  57    Check and return URL to cached image if it exists; If not, return empty string.
  58    If the image is cached, return URL (for original image or .dds version if requested)
  59
  60    \param image url of the image to check
  61    \param needsRecaching [out] whether the image needs recaching.
  62    \return cached url of this image
  63    \sa GetCachedImage
  64    */
  65   std::string CheckCachedImage(const std::string &image, bool &needsRecaching);
  66
  67   /*! \brief Cache image (if required) using a background job
  68
  69    Checks firstly whether an image is already cached, and return URL if so [see CheckCacheImage]
  70    If the image is not yet in the database, a background job is started to
  71    cache the image and add to the database [see CTextureCacheJob]
  72
  73    \param image url of the image to cache
  74    \sa CacheImage
  75    */
  76   void BackgroundCacheImage(const std::string &image);
  77
  78   /*! \brief Updates the in-process list.
  79
  80    Inserts the image url into the currently processing list
  81    to avoid 2 jobs being processed at once
  82
  83    \param image url of the image to start processing
  84    \return true if list updated, false otherwise
  85    \sa CacheImage
  86    */
  87   bool StartCacheImage(const std::string& image);
  88
  89   /*! \brief Cache an image to image cache, optionally return the texture
  90
  91    Caches the given image, returning the texture if the caller wants it.
  92
  93    \param image url of the image to cache
  94    \param texture [out] the loaded image
  95    \param details [out] details of the cached image
  96    \param idealWidth the ideal width of the returned texture (defaults to 0, no ideal width). Only matters if texture is not null.
  97    \param idealHeight the ideal height of the returned texture (defaults to 0, no ideal height). Only matters if texture is not null.
  98    \param aspectRatio the aspect ratio mode of the texture (defaults to "center"). Only matters if texture is not null.
  99    \return cached url of this image
 100    \sa CTextureCacheJob::CacheTexture
 101    */
 102   std::string CacheImage(const std::string& image,
 103                          std::unique_ptr<CTexture>* texture = nullptr,
 104                          CTextureDetails* details = nullptr,
 105                          unsigned int idealWidth = 0,
 106                          unsigned int idealHeight = 0,
 107                          CAspectRatio::AspectRatio aspectRatio = CAspectRatio::CENTER);
 108
 109   /*! \brief Cache an image to image cache if not already cached, returning the image details.
 110    \param image url of the image to cache.
 111    \param details [out] the image details.
 112    \return true if the image is in the cache, false otherwise.
 113    \sa CTextureCacheJob::CacheTexture
 114    */
 115   bool CacheImage(const std::string &image, CTextureDetails &details);
 116
 117   /*! \brief Check whether an image is in the cache
 118    Note: If the image url won't normally be cached (eg a skin image) this function will return false.
 119    \param image url of the image
 120    \return true if the image is cached, false otherwise
 121    \sa ClearCachedImage
 122    */
 123   bool HasCachedImage(const std::string &image);
 124
 125   /*! \brief clear the cached version of the given image
 126    \param image url of the image
 127    \sa GetCachedImage
 128    */
 129   void ClearCachedImage(const std::string &image, bool deleteSource = false);
 130
 131   /*! \brief clear the cached version of the image with given id
 132    \param database id of the image
 133    \sa GetCachedImage
 134    */
 135   bool ClearCachedImage(int textureID);
 136
 137   /*! \brief retrieve a cache file (relative to the cache path) to associate with the given image, excluding extension
 138    Use GetCachedPath(GetCacheFile(url)+extension) for the full path to the file.
 139    \param url location of the image
 140    \return a "unique" filename for the associated cache file, excluding extension
 141    */
 142   static std::string GetCacheFile(const std::string &url);
 143
 144   /*! \brief retrieve the full path of the given cached file
 145    \param file name of the file
 146    \return full path of the cached file
 147    */
 148   static std::string GetCachedPath(const std::string &file);
 149
 150   /*! \brief Add this image to the database
 151    Thread-safe wrapper of CTextureDatabase::AddCachedTexture
 152    \param image url of the original image
 153    \param details the texture details to add
 154    \return true if we successfully added to the database, false otherwise.
 155    */
 156   bool AddCachedTexture(const std::string &image, const CTextureDetails &details);
 157
 158   /*! \brief Export a (possibly) cached image to a file
 159    \param image url of the original image
 160    \param destination url of the destination image, excluding extension.
 161    \param overwrite whether to overwrite the destination if it exists (TODO: Defaults to false)
 162    \return true if we successfully exported the file, false otherwise.
 163    */
 164   bool Export(const std::string &image, const std::string &destination, bool overwrite);
 165   bool Export(const std::string &image, const std::string &destination); //! @todo BACKWARD COMPATIBILITY FOR MUSIC THUMBS
 166
 167   bool CleanAllUnusedImages();
 168
 169 private:
 170   // private construction, and no assignments; use the provided singleton methods
 171   CTextureCache(const CTextureCache&) = delete;
 172   CTextureCache const& operator=(CTextureCache const&) = delete;
 173
 174   /*! \brief Check if the given image is a cached image
 175    \param image url of the image
 176    \return true if this is a cached image, false otherwise.
 177    */
 178   bool IsCachedImage(const std::string &image) const;
 179
 180   /*! \brief retrieve the cached version of the given image (if it exists)
 181    \param image url of the image
 182    \param details [out] the details of the texture.
 183    \param trackUsage whether this call should track usage of the image (defaults to false)
 184    \return cached url of this image, empty if none exists
 185    \sa ClearCachedImage, CTextureDetails
 186    */
 187   std::string GetCachedImage(const std::string &image, CTextureDetails &details, bool trackUsage = false);
 188
 189   /*! \brief Get an image from the database
 190    Thread-safe wrapper of CTextureDatabase::GetCachedTexture
 191    \param image url of the original image
 192    \param details [out] texture details from the database (if available)
 193    \return true if we have a cached version of this image, false otherwise.
 194    */
 195   bool GetCachedTexture(const std::string &url, CTextureDetails &details);
 196
 197   /*! \brief Clear an image from the database
 198    Thread-safe wrapper of CTextureDatabase::ClearCachedTexture
 199    \param image url of the original image
 200    \param cacheFile [out] url of the cached original (if available)
 201    \return true if we had a cached version of this image, false otherwise.
 202    */
 203   bool ClearCachedTexture(const std::string &url, std::string &cacheFile);
 204   bool ClearCachedTexture(int textureID, std::string &cacheFile);
 205
 206   /*! \brief Increment the use count of a texture
 207    Stores locally before calling CTextureDatabase::IncrementUseCount via a CUseCountJob
 208    \sa CUseCountJob, CTextureDatabase::IncrementUseCount
 209    */
 210   void IncrementUseCount(const CTextureDetails &details);
 211
 212   /*! \brief Set a previously cached texture as valid in the database
 213    Thread-safe wrapper of CTextureDatabase::SetCachedTextureValid
 214    \param image url of the original image
 215    \param updateable whether this image should be checked for updates
 216    \return true if successful, false otherwise.
 217    */
 218   bool SetCachedTextureValid(const std::string &url, bool updateable);
 219
 220   void OnJobComplete(unsigned int jobID, bool success, CJob *job) override;
 221
 222   /*! \brief Called when a caching job has completed.
 223    Removes the job from our processing list, updates the database
 224    and fires a DDS job if appropriate.
 225    \param success whether the job was successful.
 226    \param job the caching job.
 227    */
 228   void OnCachingComplete(bool success, CTextureCacheJob *job);
 229
 230   void CleanTimer();
 231   std::chrono::milliseconds ScanOldestCache();
 232   bool CleanAllUnusedImagesJob(CGUIDialogProgress* progress);
 233
 234   std::atomic_flag m_cleaningInProgress;
 235   CTimer m_cleanTimer;
 236   CCriticalSection m_databaseSection;
 237   CTextureDatabase m_database;
 238   std::set<std::string> m_processinglist; ///< currently processing list to avoid 2 jobs being processed at once
 239   CCriticalSection     m_processingSection;
 240   CEvent               m_completeEvent; ///< Set whenever a job has finished
 241   std::vector<CTextureDetails> m_useCounts; ///< Use count tracking
 242   CCriticalSection             m_useCountSection;
 243 };
 244