-/*! Finds an image in the cache, if it is already in there */
-RrImage* RrImageCacheFind(RrImageCache *self,
- RrPixel32 *data, gint w, gint h);
-/*! Finds an image in the cache, by searching for the name of the image */
-RrImage* RrImageCacheFindName(RrImageCache *self,
- const gchar *name);
-
-RrImage* RrImageNew(RrImageCache *cache);
-void RrImageRef(RrImage *im);
-void RrImageUnref(RrImage *im);
-
-void RrImageAddPicture(RrImage *im, const RrPixel32 *data, gint w, gint h);
-/*! Adds a picture by name, from a file on disk.
- @name Can be a full path to an image, or it can be a name as per the
- freedesktop.org icon spec. */
-gboolean RrImageAddPictureName(RrImage *im, const gchar *name);
-void RrImageRemovePicture(RrImage *im, gint w, gint h);
+/*! 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);
+
+void RrImageRef(RrImage *im);
+void RrImageUnref(RrImage *im);