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