added: doxygen docs to the large texture manager.

git-svn-id: https://xbmc.svn.sourceforge.net/svnroot/xbmc/trunk@23231 568bbfeb-2a22-0410-94d2-cc84cf5bfa90

1 files changed, 41 insertions, 2 deletions

diff --git a/xbmc/GUILargeTextureManager.h b/xbmc/GUILargeTextureManager.h
index e689ea1f9c..c8ea0c2d4b 100644
--- a/xbmc/GUILargeTextureManager.h
+++ b/xbmc/GUILargeTextureManager.h
@@ -66,14 +66,54 @@ public:
   CGUILargeTextureManager();
   virtual ~CGUILargeTextureManager();
 
+  /*!
+   \brief Callback from CImageLoader on completion of a loaded image
+   
+   Transfers texture information from the loading job to our allocated texture list.
+   
+   \sa CImageLoader, IJobCallback
+   */
   virtual void OnJobComplete(unsigned int jobID, CJob *job);
 
+  /*!
+   \brief Request a texture to be loaded in the background.
+   
+   Loaded textures are reference counted, hence this call may immediately return with the texture
+   object filled if the texture has been previously loaded, else will return with an empty texture
+   object if it is being loaded.
+   
+   \param path path of the image to load.
+   \param texture texture object to hold the resulting texture
+   \param orientation orientation of resulting texture
+   \param firstRequest true if this is the first time we are requesting this texture
+   \return true if the image exists, else false.
+   \sa CGUITextureArray and CGUITexture
+   */
   bool GetImage(const CStdString &path, CTextureArray &texture, int &orientation, bool firstRequest);
+  
+  /*!
+   \brief Request a texture to be unloaded.
+   
+   When textures are finished with, this function should be called.  This decrements the texture's
+   reference count, and schedules it to be unloaded once the reference count reaches zero.  If the
+   texture is still queued for loading, or is in the process of loading, the image load is cancelled.
+   
+   \param path path of the image to release.
+   \param immediately if set true the image is immediately unloaded once its reference count reaches zero
+                      rather than being unloaded after a delay.
+   */  
   void ReleaseImage(const CStdString &path, bool immediately = false);
 
+  /*!
+   \brief Cleanup images that are no longer in use.
+   
+   Loaded textures are reference counted, and upon reaching reference count 0 through ReleaseImage()
+   they are flagged as unused with the current time.  After a delay they may be unloaded, hence
+   CleanupUnusedImages() should be called periodically to ensure this occurs.
+   */
   void CleanupUnusedImages();
 
-protected:
+private:
   class CLargeTexture
   {
   public:
@@ -101,7 +141,6 @@ protected:
 
   void QueueImage(const CStdString &path);
 
-private:
   std::vector< std::pair<unsigned int, CLargeTexture *> > m_queued;
   std::vector<CLargeTexture *> m_allocated;
   typedef std::vector<CLargeTexture *>::iterator listIterator;