API: Clean up client bitmap interface.

3 files changed, 67 insertions, 30 deletions

diff --git a/include/nsgif.h b/include/nsgif.h
index 11378d1..1472842 100644
--- a/include/nsgif.h
+++ b/include/nsgif.h
@@ -73,31 +73,66 @@ typedef struct nsgif_rect {
 	uint32_t y1;
 } nsgif_rect;
 
-/* API for Bitmap callbacks */
-typedef void* (*nsgif_bitmap_cb_create)(int width, int height);
-typedef void (*nsgif_bitmap_cb_destroy)(void *bitmap);
-typedef uint8_t* (*nsgif_bitmap_cb_get_buffer)(void *bitmap);
-typedef void (*nsgif_bitmap_cb_set_opaque)(void *bitmap, bool opaque);
-typedef bool (*nsgif_bitmap_cb_test_opaque)(void *bitmap);
-typedef void (*nsgif_bitmap_cb_modified)(void *bitmap);
+/**
+ * Client bitmap type.
+ *
+ * These are client-created and destroyed, via the \ref bitmap callbacks,
+ * but they are owned by a \ref nsgif.
+ */
+typedef void nsgif_bitmap_t;
 
 /** Bitmap callbacks function table */
 typedef struct nsgif_bitmap_cb_vt {
-	/** Create a bitmap. */
-	nsgif_bitmap_cb_create create;
-	/** Free a bitmap. */
-	nsgif_bitmap_cb_destroy destroy;
-	/** Return a pointer to the pixel data in a bitmap. */
-	nsgif_bitmap_cb_get_buffer get_buffer;
-
-	/* Members below are optional */
-
-	/** Sets whether a bitmap should be plotted opaque. */
-	nsgif_bitmap_cb_set_opaque set_opaque;
-	/** Tests whether a bitmap has an opaque alpha channel. */
-	nsgif_bitmap_cb_test_opaque test_opaque;
-	/** The bitmap image has changed, so flush any persistent cache. */
-	nsgif_bitmap_cb_modified modified;
+	/**
+	 * Callback to create a bitmap with the given dimensions.
+	 *
+	 * \param[in]  width   Required bitmap width in pixels.
+	 * \param[in]  height  Required bitmap height in pixels.
+	 * \return pointer to client's bitmap structure or NULL on error.
+	 */
+	nsgif_bitmap_t* (*create)(int width, int height);
+
+	/**
+	 * Callback to free a bitmap.
+	 *
+	 * \param[in]  bitmap  The bitmap to destroy.
+	 */
+	void (*destroy)(nsgif_bitmap_t *bitmap);
+
+	/**
+	 * Get pointer to pixel buffer in a bitmap.
+	 *
+	 * The pixel buffer must be `width * height * sizeof(uint32_t)`.
+	 *
+	 * \param[in]  bitmap  The bitmap.
+	 * \return pointer to bitmap's pixel buffer.
+	 */
+	uint8_t* (*get_buffer)(nsgif_bitmap_t *bitmap);
+
+	/* The following functions are optional. */
+
+	/**
+	 * Set whether a bitmap can be plotted opaque.
+	 *
+	 * \param[in]  bitmap  The bitmap.
+	 * \param[in]  opaque  Whether the current frame is opaque.
+	 */
+	void (*set_opaque)(nsgif_bitmap_t *bitmap, bool opaque);
+
+	/**
+	 * Tests whether a bitmap has an opaque alpha channel.
+	 *
+	 * \param[in]  bitmap  The bitmap.
+	 * \return true if the bitmap is opaque, false otherwise.
+	 */
+	bool (*test_opaque)(nsgif_bitmap_t *bitmap);
+
+	/**
+	 * Bitmap modified notification.
+	 *
+	 * \param[in]  bitmap  The bitmap.
+	 */
+	void (*modified)(nsgif_bitmap_t *bitmap);
 } nsgif_bitmap_cb_vt;
 
 /**
@@ -161,8 +196,10 @@ nsgif_result nsgif_frame_prepare(
 /**
  * Decodes a GIF frame.
  *
- * \param[in]  gif    The nsgif object.
- * \param[in]  frame  The frame number to decode.
+ * \param[in]  gif     The nsgif object.
+ * \param[in]  frame   The frame number to decode.
+ * \param[out] bitmap  On success, returns pointer to the client-allocated,
+ *                     nsgif-owned client bitmap structure.
  * \return Error return value.
  *         - NSGIF_FRAME_DATA_ERROR for GIF frame data error
  *         - NSGIF_DATA_ERROR for GIF error (invalid frame header)
@@ -173,7 +210,7 @@ nsgif_result nsgif_frame_prepare(
 nsgif_result nsgif_frame_decode(
 		nsgif *gif,
 		uint32_t frame,
-		const uint32_t **buffer);
+		nsgif_bitmap_t **bitmap);
 
 /**
  * Reset a GIF animation.
diff --git a/src/gif.c b/src/gif.c
index dd29f0a..5ed38d8 100644
--- a/src/gif.c
+++ b/src/gif.c
@@ -67,7 +67,7 @@ struct nsgif {
 	/** current frame decoded to bitmap */
 	uint32_t decoded_frame;
 	/** currently decoded image; stored as bitmap from bitmap_create callback */
-	void *frame_image;
+	nsgif_bitmap_t *frame_image;
 
 	uint16_t delay_default;
 	/** number of frames partially decoded */
@@ -1685,13 +1685,13 @@ nsgif_result nsgif_frame_prepare(
 nsgif_result nsgif_frame_decode(
 		nsgif *gif,
 		uint32_t frame,
-		const uint32_t **buffer)
+		nsgif_bitmap_t **bitmap)
 {
 	uint32_t start_frame;
 	nsgif_result ret = NSGIF_OK;
 
 	if (gif->decoded_frame == frame) {
-		*buffer = gif->frame_image;
+		*bitmap = gif->frame_image;
 		return NSGIF_OK;
 
 	} else if (gif->decoded_frame >= frame ||
@@ -1710,7 +1710,7 @@ nsgif_result nsgif_frame_decode(
 		}
 	}
 
-	*buffer = gif->frame_image;
+	*bitmap = gif->frame_image;
 	return ret;
 }
 
diff --git a/test/decode_gif.c b/test/decode_gif.c
index 5f5c377..acc2ef0 100644
--- a/test/decode_gif.c
+++ b/test/decode_gif.c
@@ -122,7 +122,7 @@ static void decode(FILE* fh, const char *name, nsgif *gif, bool write_ppm)
 
 	/* decode the frames */
 	while (true) {
-		const uint32_t *buffer;
+		nsgif_bitmap_t *buffer;
 		const uint8_t *image;
 		uint32_t frame_new;
 		uint32_t delay_cs;