4 * Copyright (C) 2005-2013 Team XBMC
7 * This Program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2, or (at your option)
12 * This Program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License
18 * along with XBMC; see the file COPYING. If not, see
19 * <http://www.gnu.org/licenses/>.
23 #include "threads/CriticalSection.h"
24 #include "utils/Job.h"
25 #include "guilib/TextureManager.h"
28 \ingroup textures,jobs
29 \brief Image loader job class
31 Used by the CGUILargeTextureManager to perform asynchronous loading of textures.
33 \sa CGUILargeTextureManager and CJob
35 class CImageLoader : public CJob
38 CImageLoader(const CStdString &path, const bool useCache);
39 virtual ~CImageLoader();
42 \brief Work function that loads in a particular image.
44 virtual bool DoWork();
46 bool m_use_cache; ///< Whether or not to use any caching with this image
47 CStdString m_path; ///< path of image to load
48 CBaseTexture *m_texture; ///< Texture object to load the image into \sa CBaseTexture.
53 \brief Background texture loading manager
55 Used to load textures for the user interface asynchronously, allowing fluid framerates
56 while background loading textures.
58 \sa IJobCallback, CGUITexture
60 class CGUILargeTextureManager : public IJobCallback
63 CGUILargeTextureManager();
64 virtual ~CGUILargeTextureManager();
67 \brief Callback from CImageLoader on completion of a loaded image
69 Transfers texture information from the loading job to our allocated texture list.
71 \sa CImageLoader, IJobCallback
73 virtual void OnJobComplete(unsigned int jobID, bool success, CJob *job);
76 \brief Request a texture to be loaded in the background.
78 Loaded textures are reference counted, hence this call may immediately return with the texture
79 object filled if the texture has been previously loaded, else will return with an empty texture
80 object if it is being loaded.
82 \param path path of the image to load.
83 \param texture texture object to hold the resulting texture
84 \param orientation orientation of resulting texture
85 \param firstRequest true if this is the first time we are requesting this texture
86 \return true if the image exists, else false.
87 \sa CGUITextureArray and CGUITexture
89 bool GetImage(const CStdString &path, CTextureArray &texture, bool firstRequest, bool useCache = true);
92 \brief Request a texture to be unloaded.
94 When textures are finished with, this function should be called. This decrements the texture's
95 reference count, and schedules it to be unloaded once the reference count reaches zero. If the
96 texture is still queued for loading, or is in the process of loading, the image load is cancelled.
98 \param path path of the image to release.
99 \param immediately if set true the image is immediately unloaded once its reference count reaches zero
100 rather than being unloaded after a delay.
102 void ReleaseImage(const CStdString &path, bool immediately = false);
105 \brief Cleanup images that are no longer in use.
107 Loaded textures are reference counted, and upon reaching reference count 0 through ReleaseImage()
108 they are flagged as unused with the current time. After a delay they may be unloaded, hence
109 CleanupUnusedImages() should be called periodically to ensure this occurs.
111 \param immediately set to true to cleanup images regardless of whether the delay has passed
113 void CleanupUnusedImages(bool immediately = false);
119 CLargeTexture(const CStdString &path);
120 virtual ~CLargeTexture();
123 bool DecrRef(bool deleteImmediately);
124 bool DeleteIfRequired(bool deleteImmediately = false);
125 void SetTexture(CBaseTexture* texture);
127 const CStdString &GetPath() const { return m_path; };
128 const CTextureArray &GetTexture() const { return m_texture; };
131 static const unsigned int TIME_TO_DELETE = 2000;
133 unsigned int m_refCount;
135 CTextureArray m_texture;
136 unsigned int m_timeToDelete;
139 void QueueImage(const CStdString &path, bool useCache = true);
141 std::vector< std::pair<unsigned int, CLargeTexture *> > m_queued;
142 std::vector<CLargeTexture *> m_allocated;
143 typedef std::vector<CLargeTexture *>::iterator listIterator;
144 typedef std::vector< std::pair<unsigned int, CLargeTexture *> >::iterator queueIterator;
146 CCriticalSection m_listSection;
149 extern CGUILargeTextureManager g_largeTextureManager;