From 215d1bec589de6085acf55e79bfc1295b26abf16 Mon Sep 17 00:00:00 2001
From: Chris Young <chris@unsatisfactorysoftware.co.uk>
Date: Tue, 22 Mar 2016 19:39:33 +0000
Subject: [PATCH] Document new bitmap functions

---
 amiga/bitmap.c |  5 ++++
 amiga/bitmap.h | 78 ++++++++++++++++++++++++++++++++++++++++++++++----
 amiga/icon.c   |  3 +-
 3 files changed, 78 insertions(+), 8 deletions(-)

diff --git a/amiga/bitmap.c b/amiga/bitmap.c
index ba72b11cf..cb30354a2 100644
--- a/amiga/bitmap.c
+++ b/amiga/bitmap.c
@@ -657,6 +657,11 @@ ULONG *ami_bitmap_get_icondata(struct bitmap *bm)
 	return bm->icondata;
 }
 
+void ami_bitmap_set_icondata(struct bitmap *bm, ULONG *icondata)
+{
+	bm->icondata = icondata;
+}
+
 bool ami_bitmap_has_dto(struct bitmap *bm)
 {
 	if(bm->dto) return true;
diff --git a/amiga/bitmap.h b/amiga/bitmap.h
index cb7f968a1..a1893b317 100755
--- a/amiga/bitmap.h
+++ b/amiga/bitmap.h
@@ -40,14 +40,64 @@ PLANEPTR ami_bitmap_get_mask(struct bitmap *bitmap, int width,
 Object *ami_datatype_object_from_bitmap(struct bitmap *bitmap);
 struct bitmap *ami_bitmap_from_datatype(char *filename);
 
+/**
+ * Set bitmap URL
+ *
+ * \param  bm  a bitmap, as returned by bitmap_create()
+ * \param  title  a pointer to a title string
+ *
+ * It is assumed that this is freed elsewhere after the bitmap is destroyed.
+ */
 void ami_bitmap_set_url(struct bitmap *bm, struct nsurl *url);
-void ami_bitmap_set_title(struct bitmap *bm, const char *title);
-ULONG *ami_bitmap_get_icondata(struct bitmap *bm);
-bool ami_bitmap_has_dto(struct bitmap *bm);
-bool ami_bitmap_is_nativebm(struct bitmap *bm, struct BitMap *nbm);
 
-int bitmap_get_width(void *bitmap);
-int bitmap_get_height(void *bitmap);
+/**
+ * Set bitmap title
+ *
+ * \param  bm  a bitmap, as returned by bitmap_create()
+ * \param  title  a pointer to a title string
+ *
+ * It is assumed that this is freed elsewhere after the bitmap is destroyed.
+ */
+void ami_bitmap_set_title(struct bitmap *bm, const char *title);
+
+/**
+ * Get an icondata pointer
+ *
+ * \param  bm  a bitmap, as returned by bitmap_create()
+ * \return pointer to the icondata area
+ *
+ * This function probably shouldn't be here!
+ */
+ULONG *ami_bitmap_get_icondata(struct bitmap *bm);
+
+/**
+ * Set an icondata pointer
+ *
+ * \param  bm  a bitmap, as returned by bitmap_create()
+ * \param  icondata  a pointer to memory
+ *
+ * This function probably shouldn't be here!
+ */
+void ami_bitmap_set_icondata(struct bitmap *bm, ULONG *icondata);
+
+/**
+ * Test if a bitmap has an associated DataTypes object.
+ *
+ * \param  bm  a bitmap, as returned by bitmap_create()
+ * \return true if the BitMap has a DataTypes object
+ *
+ * This function probably shouldn't be used!
+ */
+bool ami_bitmap_has_dto(struct bitmap *bm);
+
+/**
+ * Test if a BitMap is owned by a bitmap.
+ *
+ * \param  bm  a bitmap, as returned by bitmap_create()
+ * \param  nbm a BitMap, as created by AllocBitMap()
+ * \return true if the BitMap is owned by the bitmap
+ */
+bool ami_bitmap_is_nativebm(struct bitmap *bm, struct BitMap *nbm);
 
 /**
  * Cleanup bitmap allocations
@@ -83,6 +133,22 @@ unsigned char *amiga_bitmap_get_buffer(void *bitmap);
  */
 size_t amiga_bitmap_get_rowstride(void *bitmap);
 
+/**
+ * Return the width of a bitmap.
+ *
+ * \param  bitmap  a bitmap, as returned by bitmap_create()
+ * \return width in pixels
+ */
+int bitmap_get_width(void *bitmap);
+
+/**
+ * Return the height of a bitmap.
+ *
+ * \param  bitmap  a bitmap, as returned by bitmap_create()
+ * \return height in pixels
+ */
+int bitmap_get_height(void *bitmap);
+
 /**
  * Free a bitmap.
  *
diff --git a/amiga/icon.c b/amiga/icon.c
index 0ef3dbb12..1370c3c04 100644
--- a/amiga/icon.c
+++ b/amiga/icon.c
@@ -498,11 +498,10 @@ struct DiskObject *amiga_icon_from_bitmap(struct bitmap *bm)
 #ifdef __amigaos4__
 	if(bm)
 	{
-		icondata = ami_bitmap_get_icondata(bm);
-
 		bitmap = ami_bitmap_get_native(bm, THUMBNAIL_WIDTH,
 									THUMBNAIL_HEIGHT, NULL);
 		icondata = AllocVecTagList(THUMBNAIL_WIDTH * 4 * THUMBNAIL_HEIGHT, NULL);
+		ami_bitmap_set_icondata(bm, icondata);
 
 		BltBitMapTags(BLITA_Width, THUMBNAIL_WIDTH,
 					BLITA_Height, THUMBNAIL_HEIGHT,