-/*! Finds an image in the cache, if it is already in there */
-RrImage* RrImageCacheFind(RrImageCache *self,
- RrPixel32 *data, gint w, gint h);
-
-RrImage* RrImageNew(RrImageCache *cache);
-void RrImageRef(RrImage *im);
-void RrImageUnref(RrImage *im);
+/*! Create a new image, or return one from the cache that matches.
+ @param cache The image cache.
+ @param old The current RrImage, which the new image should be added to.
+ Use this if loading a different sized version of the same image.
+ The returned RrImage should replace the one passed in as old.
+ Pass NULL here if adding an image which is (or may be) entirely new.
+ @param name The name of the icon to be loaded off disk, or used in the cache
+ @return Returns NULL if unable to load an image by the name and it is not in
+ the cache already
+*/
+RrImage* RrImageNewFromName(RrImageCache *cache, const gchar *name);
+
+/*! Create a new image, or return one from the cache that matches.
+ @param cache The image cache.
+ @param data The image data in RGBA32 format. There should be @w * @h many
+ values in the data array.
+ @param w The width of the image data.
+ @param h The height of the image data.
+ @return Returns NULL if unable to load an image by the name and it is not in
+ the cache already
+*/
+RrImage* RrImageNewFromData(RrImageCache *cache, RrPixel32 *data,
+ gint w, gint h);
+
+/*! Add a new size of a picture to an image.
+ If a picture has multiple versions of different sizes (example 16x16, 32x32
+ and so on), they should all be under the same RrImage. This adds a new
+ size to an existing RrImage, associating the newly sized picture with the
+ others in the RrImage - classifying them as being the same logical image at a
+ different dimention.
+*/
+void RrImageAddFromData(RrImage *image, RrPixel32 *data, gint w, gint h);