add a bunch of comments for images and image caches. and make the number of resized pictures saved in an image tunable per-icon cache.

1 files changed, 17 insertions, 3 deletions

diff --git a/render/imagecache.h b/render/imagecache.h
index 8c96caf0..4ad2deae 100644
--- a/render/imagecache.h
+++ b/render/imagecache.h
@@ -21,15 +21,29 @@
 
 #include <glib.h>
 
-/* the number of resized pictures to cache for an image */
-#define MAX_CACHE_RESIZED 3
-
 struct _RrImagePic;
 
 guint RrImagePicHash(const struct _RrImagePic *p);
 
+/*! Create a new image cache.  An image cache is basically a hash table to look
+  up RrImages.  Each RrImage in the cache may contain one or more Pictures,
+  that is one or more actual copies of image data at various sizes.  For eg,
+  for a window, all of its various icons are loaded into the same RrImage.
+  When an RrImage is drawn and a picture inside it needs to be resized, that
+  is also saved within the RrImage.
+
+  For each picture that an RrImage has, the picture is hashed and that is used
+  as a key to find the RrImage.  So, given any picture in any RrImage in the
+  cache, if you hash it, you will find the RrImage.
+*/
 struct _RrImageCache {
     gint ref;
+    /*! When an original picture is resized for an RrImage, the resized picture
+      is saved in the RrImage.  This specifies how many pictures should be
+      saved at a time.  When this is exceeded, the least recently used
+      "resized" picture is deleted.
+    */
+    gint max_resized_saved;
 
     GHashTable *table;
 };