diff options
Diffstat (limited to 'include/libnsgif.h')
| -rw-r--r-- | include/libnsgif.h | 207 |
1 files changed, 141 insertions, 66 deletions
diff --git a/include/libnsgif.h b/include/libnsgif.h index 462c354..33b4b19 100644 --- a/include/libnsgif.h +++ b/include/libnsgif.h @@ -7,8 +7,9 @@ * http://www.opensource.org/licenses/mit-license.php */ -/** \file - * Progressive animated GIF file decoding (interface). +/** + * \file + * Interface to progressive animated GIF file decoding. */ #ifndef _LIBNSGIF_H_ @@ -17,42 +18,53 @@ #include <stdbool.h> #include <inttypes.h> -/* Error return values -*/ +/* Error return values */ typedef enum { - GIF_WORKING = 1, - GIF_OK = 0, - GIF_INSUFFICIENT_FRAME_DATA = -1, - GIF_FRAME_DATA_ERROR = -2, - GIF_INSUFFICIENT_DATA = -3, - GIF_DATA_ERROR = -4, - GIF_INSUFFICIENT_MEMORY = -5, - GIF_FRAME_NO_DISPLAY = -6, - GIF_END_OF_FRAME = -7 + GIF_WORKING = 1, + GIF_OK = 0, + GIF_INSUFFICIENT_FRAME_DATA = -1, + GIF_FRAME_DATA_ERROR = -2, + GIF_INSUFFICIENT_DATA = -3, + GIF_DATA_ERROR = -4, + GIF_INSUFFICIENT_MEMORY = -5, + GIF_FRAME_NO_DISPLAY = -6, + GIF_END_OF_FRAME = -7 } gif_result; -/* The GIF frame data -*/ +/** GIF frame data */ typedef struct gif_frame { - bool display; /**< whether the frame should be displayed/animated */ - unsigned int frame_delay; /**< delay (in cs) before animating the frame */ - /** Internal members are listed below - */ - unsigned int frame_pointer; /**< offset (in bytes) to the GIF frame data */ - bool virgin; /**< whether the frame has previously been used */ - bool opaque; /**< whether the frame is totally opaque */ - bool redraw_required; /**< whether a forcable screen redraw is required */ - unsigned char disposal_method; /**< how the previous frame should be disposed; affects plotting */ - bool transparency; /**< whether we acknoledge transparency */ - unsigned char transparency_index; /**< the index designating a transparent pixel */ - unsigned int redraw_x; /**< x co-ordinate of redraw rectangle */ - unsigned int redraw_y; /**< y co-ordinate of redraw rectangle */ - unsigned int redraw_width; /**< width of redraw rectangle */ - unsigned int redraw_height; /**< height of redraw rectangle */ + /** whether the frame should be displayed/animated */ + bool display; + /** delay (in cs) before animating the frame */ + unsigned int frame_delay; + + /* Internal members are listed below */ + + /** offset (in bytes) to the GIF frame data */ + unsigned int frame_pointer; + /** whether the frame has previously been used */ + bool virgin; + /** whether the frame is totally opaque */ + bool opaque; + /** whether a forcable screen redraw is required */ + bool redraw_required; + /** how the previous frame should be disposed; affects plotting */ + unsigned char disposal_method; + /** whether we acknoledge transparency */ + bool transparency; + /** the index designating a transparent pixel */ + unsigned char transparency_index; + /** x co-ordinate of redraw rectangle */ + unsigned int redraw_x; + /** y co-ordinate of redraw rectangle */ + unsigned int redraw_y; + /** width of redraw rectangle */ + unsigned int redraw_width; + /** height of redraw rectangle */ + unsigned int redraw_height; } gif_frame; -/* API for Bitmap callbacks -*/ +/* API for Bitmap callbacks */ typedef void* (*gif_bitmap_cb_create)(int width, int height); typedef void (*gif_bitmap_cb_destroy)(void *bitmap); typedef unsigned char* (*gif_bitmap_cb_get_buffer)(void *bitmap); @@ -60,49 +72,112 @@ typedef void (*gif_bitmap_cb_set_opaque)(void *bitmap, bool opaque); typedef bool (*gif_bitmap_cb_test_opaque)(void *bitmap); typedef void (*gif_bitmap_cb_modified)(void *bitmap); -/* The Bitmap callbacks function table -*/ +/** Bitmap callbacks function table */ typedef struct gif_bitmap_callback_vt { - gif_bitmap_cb_create bitmap_create; /**< Create a bitmap. */ - gif_bitmap_cb_destroy bitmap_destroy; /**< Free a bitmap. */ - gif_bitmap_cb_get_buffer bitmap_get_buffer; /**< Return a pointer to the pixel data in a bitmap. */ - /** Members below are optional - */ - gif_bitmap_cb_set_opaque bitmap_set_opaque; /**< Sets whether a bitmap should be plotted opaque. */ - gif_bitmap_cb_test_opaque bitmap_test_opaque; /**< Tests whether a bitmap has an opaque alpha channel. */ - gif_bitmap_cb_modified bitmap_modified; /**< The bitmap image has changed, so flush any persistant cache. */ + /** Create a bitmap. */ + gif_bitmap_cb_create bitmap_create; + /** Free a bitmap. */ + gif_bitmap_cb_destroy bitmap_destroy; + /** Return a pointer to the pixel data in a bitmap. */ + gif_bitmap_cb_get_buffer bitmap_get_buffer; + + /* Members below are optional */ + + /** Sets whether a bitmap should be plotted opaque. */ + gif_bitmap_cb_set_opaque bitmap_set_opaque; + /** Tests whether a bitmap has an opaque alpha channel. */ + gif_bitmap_cb_test_opaque bitmap_test_opaque; + /** The bitmap image has changed, so flush any persistant cache. */ + gif_bitmap_cb_modified bitmap_modified; } gif_bitmap_callback_vt; -/* The GIF animation data -*/ +/** GIF animation data */ typedef struct gif_animation { - gif_bitmap_callback_vt bitmap_callbacks; /**< callbacks for bitmap functions */ - unsigned char *gif_data; /**< pointer to GIF data */ - unsigned int width; /**< width of GIF (may increase during decoding) */ - unsigned int height; /**< heigth of GIF (may increase during decoding) */ - unsigned int frame_count; /**< number of frames decoded */ - unsigned int frame_count_partial; /**< number of frames partially decoded */ - gif_frame *frames; /**< decoded frames */ - int decoded_frame; /**< current frame decoded to bitmap */ - void *frame_image; /**< currently decoded image; stored as bitmap from bitmap_create callback */ - int loop_count; /**< number of times to loop animation */ - gif_result current_error; /**< current error type, or 0 for none*/ - /** Internal members are listed below - */ - unsigned int buffer_position; /**< current index into GIF data */ - unsigned int buffer_size; /**< total number of bytes of GIF data available */ - unsigned int frame_holders; /**< current number of frame holders */ - unsigned int background_index; /**< index in the colour table for the background colour */ - unsigned int aspect_ratio; /**< image aspect ratio (ignored) */ - unsigned int colour_table_size; /**< size of colour table (in entries) */ - bool global_colours; /**< whether the GIF has a global colour table */ - unsigned int *global_colour_table; /**< global colour table */ - unsigned int *local_colour_table; /**< local colour table */ + /** callbacks for bitmap functions */ + gif_bitmap_callback_vt bitmap_callbacks; + /** pointer to GIF data */ + unsigned char *gif_data; + /** width of GIF (may increase during decoding) */ + unsigned int width; + /** heigth of GIF (may increase during decoding) */ + unsigned int height; + /** number of frames decoded */ + unsigned int frame_count; + /** number of frames partially decoded */ + unsigned int frame_count_partial; + /** decoded frames */ + gif_frame *frames; + /** current frame decoded to bitmap */ + int decoded_frame; + /** currently decoded image; stored as bitmap from bitmap_create callback */ + void *frame_image; + /** number of times to loop animation */ + int loop_count; + /** current error type, or 0 for none */ + gif_result current_error; + + /* Internal members are listed below */ + + /** current index into GIF data */ + unsigned int buffer_position; + /** total number of bytes of GIF data available */ + unsigned int buffer_size; + /** current number of frame holders */ + unsigned int frame_holders; + /** index in the colour table for the background colour */ + unsigned int background_index; + /** image aspect ratio (ignored) */ + unsigned int aspect_ratio; + /** size of colour table (in entries) */ + unsigned int colour_table_size; + /** whether the GIF has a global colour table */ + bool global_colours; + /** global colour table */ + unsigned int *global_colour_table; + /** local colour table */ + unsigned int *local_colour_table; } gif_animation; +/** + * Initialises necessary gif_animation members. + */ void gif_create(gif_animation *gif, gif_bitmap_callback_vt *bitmap_callbacks); + +/** + * Initialises any workspace held by the animation and attempts to decode + * any information that hasn't already been decoded. + * If an error occurs, all previously decoded frames are retained. + * + * @return Error return value. + * - GIF_FRAME_DATA_ERROR for GIF frame data error + * - GIF_INSUFFICIENT_FRAME_DATA for insufficient data to process + * any more frames + * - GIF_INSUFFICIENT_MEMORY for memory error + * - GIF_DATA_ERROR for GIF error + * - GIF_INSUFFICIENT_DATA for insufficient data to do anything + * - GIF_OK for successful decoding + * - GIF_WORKING for successful decoding if more frames are expected + */ gif_result gif_initialise(gif_animation *gif, size_t size, unsigned char *data); + +/** + * Decodes a GIF frame. + * + * @return Error return value. If a frame does not contain any image data, + * GIF_OK is returned and gif->current_error is set to + * GIF_FRAME_NO_DISPLAY + * - GIF_FRAME_DATA_ERROR for GIF frame data error + * - GIF_INSUFFICIENT_FRAME_DATA for insufficient data to complete the frame + * - GIF_DATA_ERROR for GIF error (invalid frame header) + * - GIF_INSUFFICIENT_DATA for insufficient data to do anything + * - GIF_INSUFFICIENT_MEMORY for insufficient memory to process + * - GIF_OK for successful decoding + */ gif_result gif_decode_frame(gif_animation *gif, unsigned int frame); + +/** + * Releases any workspace held by a gif + */ void gif_finalise(gif_animation *gif); #endif |