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