xbmc/GUILargeTextureManager.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 "guilib/TextureManager.h"
  12 #include "threads/CriticalSection.h"
  13 #include "utils/Job.h"
  14
  15 #include <memory>
  16 #include <string>
  17 #include <utility>
  18 #include <vector>
  19
  20 class CTexture;
  21
  22 /*!
  23  \ingroup textures,jobs
  24  \brief Image loader job class
  25
  26  Used by the CGUILargeTextureManager to perform asynchronous loading of textures.
  27
  28  \sa CGUILargeTextureManager and CJob
  29  */
  30 class CImageLoader : public CJob
  31 {
  32 public:
  33   CImageLoader(const std::string &path, const bool useCache);
  34   ~CImageLoader() override;
  35
  36   /*!
  37    \brief Work function that loads in a particular image.
  38    */
  39   bool DoWork() override;
  40
  41   bool          m_use_cache; ///< Whether or not to use any caching with this image
  42   std::string    m_path; ///< path of image to load
  43   std::unique_ptr<CTexture> m_texture; ///< Texture object to load the image into \sa CTexture.
  44 };
  45
  46 /*!
  47  \ingroup textures
  48  \brief Background texture loading manager
  49
  50  Used to load textures for the user interface asynchronously, allowing fluid framerates
  51  while background loading textures.
  52
  53  \sa IJobCallback, CGUITexture
  54  */
  55 class CGUILargeTextureManager : public IJobCallback
  56 {
  57 public:
  58   CGUILargeTextureManager();
  59   ~CGUILargeTextureManager() override;
  60
  61   /*!
  62    \brief Callback from CImageLoader on completion of a loaded image
  63
  64    Transfers texture information from the loading job to our allocated texture list.
  65
  66    \sa CImageLoader, IJobCallback
  67    */
  68   void OnJobComplete(unsigned int jobID, bool success, CJob *job) override;
  69
  70   /*!
  71    \brief Request a texture to be loaded in the background.
  72
  73    Loaded textures are reference counted, hence this call may immediately return with the texture
  74    object filled if the texture has been previously loaded, else will return with an empty texture
  75    object if it is being loaded.
  76
  77    \param path path of the image to load.
  78    \param texture texture object to hold the resulting texture
  79    \param orientation orientation of resulting texture
  80    \param firstRequest true if this is the first time we are requesting this texture
  81    \return true if the image exists, else false.
  82    \sa CGUITextureArray and CGUITexture
  83    */
  84   bool GetImage(const std::string &path, CTextureArray &texture, bool firstRequest, bool useCache = true);
  85
  86   /*!
  87    \brief Request a texture to be unloaded.
  88
  89    When textures are finished with, this function should be called.  This decrements the texture's
  90    reference count, and schedules it to be unloaded once the reference count reaches zero.  If the
  91    texture is still queued for loading, or is in the process of loading, the image load is cancelled.
  92
  93    \param path path of the image to release.
  94    \param immediately if set true the image is immediately unloaded once its reference count reaches zero
  95                       rather than being unloaded after a delay.
  96    */
  97   void ReleaseImage(const std::string &path, bool immediately = false);
  98
  99   /*!
 100    \brief Cleanup images that are no longer in use.
 101
 102    Loaded textures are reference counted, and upon reaching reference count 0 through ReleaseImage()
 103    they are flagged as unused with the current time.  After a delay they may be unloaded, hence
 104    CleanupUnusedImages() should be called periodically to ensure this occurs.
 105
 106    \param immediately set to true to cleanup images regardless of whether the delay has passed
 107    */
 108   void CleanupUnusedImages(bool immediately = false);
 109
 110 private:
 111   class CLargeTexture
 112   {
 113   public:
 114     explicit CLargeTexture(const std::string &path);
 115     virtual ~CLargeTexture();
 116
 117     void AddRef();
 118     bool DecrRef(bool deleteImmediately);
 119     bool DeleteIfRequired(bool deleteImmediately = false);
 120     void SetTexture(std::unique_ptr<CTexture> texture);
 121
 122     const std::string& GetPath() const { return m_path; }
 123     const CTextureArray& GetTexture() const { return m_texture; }
 124
 125   private:
 126     static const unsigned int TIME_TO_DELETE = 2000;
 127
 128     unsigned int m_refCount;
 129     std::string m_path;
 130     CTextureArray m_texture;
 131     unsigned int m_timeToDelete;
 132   };
 133
 134   void QueueImage(const std::string &path, bool useCache = true);
 135
 136   std::vector< std::pair<unsigned int, CLargeTexture *> > m_queued;
 137   std::vector<CLargeTexture *> m_allocated;
 138   typedef std::vector<CLargeTexture *>::iterator listIterator;
 139   typedef std::vector< std::pair<unsigned int, CLargeTexture *> >::iterator queueIterator;
 140
 141   CCriticalSection m_listSection;
 142 };
 143