PageRenderTime 21ms CodeModel.GetById 13ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 0ms

/xbmc/TextureCache.h

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