diff options
author | Michael Drake <tlsa@netsurf-browser.org> | 2022-02-26 14:40:35 +0000 |
---|---|---|
committer | Michael Drake <tlsa@netsurf-browser.org> | 2022-02-26 14:40:35 +0000 |
commit | 370c2a783b67350143c18a07463835887d2b1847 (patch) | |
tree | 10ac9c1104edd13b986b7c59ab51c767c2f86ed7 /include | |
parent | 84a9edb126121cd145295e48a5f0a98de4aab708 (diff) | |
download | libnsgif-370c2a783b67350143c18a07463835887d2b1847.tar.gz libnsgif-370c2a783b67350143c18a07463835887d2b1847.tar.bz2 |
API: Add public access function for frame information.
Diffstat (limited to 'include')
-rw-r--r-- | include/nsgif.h | 126 |
1 files changed, 92 insertions, 34 deletions
diff --git a/include/nsgif.h b/include/nsgif.h index 550fea3..b36af8a 100644 --- a/include/nsgif.h +++ b/include/nsgif.h @@ -20,22 +20,29 @@ #include <stdbool.h> #include <inttypes.h> +/** Representation of infinity. */ #define NSGIF_INFINITE (UINT32_MAX) typedef struct nsgif nsgif; -typedef struct nsgif_info { - /** width of GIF (may increase during decoding) */ - uint32_t width; - /** height of GIF (may increase during decoding) */ - uint32_t height; - /** number of frames decoded */ - uint32_t frame_count; - /** number of times to loop animation */ - int loop_max; - /** number of animation loops so far */ - int loop_count; -} nsgif_info_t; +/** + * GIF rectangle structure. + * + * * Top left coordinate is `(x0, y0)`. + * * Width is `x1 - x0`. + * * Height is `y1 - y0`. + * * Units are pixels. + */ +typedef struct nsgif_rect { + /** x co-ordinate of redraw rectangle, left */ + uint32_t x0; + /** y co-ordinate of redraw rectangle, top */ + uint32_t y0; + /** x co-ordinate of redraw rectangle, right */ + uint32_t x1; + /** y co-ordinate of redraw rectangle, bottom */ + uint32_t y1; +} nsgif_rect; /** * NSGIF return codes. @@ -94,25 +101,6 @@ typedef enum { } nsgif_error; /** - * GIF rectangle structure. - * - * * Top left coordinate is `(x0, y0)`. - * * Width is `x1 - x0`. - * * Height is `y1 - y0`. - * * Units are pixels. - */ -typedef struct nsgif_rect { - /** x co-ordinate of redraw rectangle, left */ - uint32_t x0; - /** y co-ordinate of redraw rectangle, top */ - uint32_t y0; - /** x co-ordinate of redraw rectangle, right */ - uint32_t x1; - /** y co-ordinate of redraw rectangle, bottom */ - uint32_t y1; -} nsgif_rect; - -/** * Client bitmap type. * * These are client-created and destroyed, via the \ref bitmap callbacks, @@ -193,6 +181,13 @@ const char *nsgif_strerror(nsgif_error err); nsgif_error nsgif_create(const nsgif_bitmap_cb_vt *bitmap_vt, nsgif **gif_out); /** + * Free a NSGIF object. + * + * \param[in] gif The NSGIF to free. + */ +void nsgif_destroy(nsgif *gif); + +/** * Scan the source image data. * * This is used to feed the source data into LibNSGIF. This must be called @@ -224,6 +219,10 @@ nsgif_error nsgif_data_scan( /** * Prepare to show a frame. * + * If this is the last frame of an animation with a finite loop count, the + * returned `delay_cs` will be \ref NSGIF_INFINITE, indicating that the frame + * should be shown forever. + * * \param[in] gif The NSGIF object. * \param[out] area The area in pixels that must be redrawn. * \param[out] delay_cs Time to wait after frame_new before next frame in cs. @@ -268,6 +267,60 @@ nsgif_error nsgif_reset( nsgif *gif); /** + * Information about a GIF. + */ +typedef struct nsgif_info { + /** width of GIF (may increase during decoding) */ + uint32_t width; + /** height of GIF (may increase during decoding) */ + uint32_t height; + /** number of frames decoded */ + uint32_t frame_count; + /** number of times to loop animation */ + int loop_max; + /** number of animation loops so far */ + int loop_count; +} nsgif_info_t; + +/** + * Frame disposal method. + * + * Clients do not need to know about this, it is provided purely for dumping + * raw information about GIF frames. + */ +enum nsgif_disposal { + NSGIF_DISPOSAL_UNSPECIFIED, /**< No disposal method specified. */ + NSGIF_DISPOSAL_NONE, /**< Frame remains. */ + NSGIF_DISPOSAL_RESTORE_BG, /**< Clear frame to background colour. */ + NSGIF_DISPOSAL_RESTORE_PREV, /**< Restore previous frame. */ + NSGIF_DISPOSAL_RESTORE_QUIRK, /**< Alias for NSGIF_DISPOSAL_RESTORE_PREV. */ +}; + +/** + * Convert a disposal method to a string. + * + * \param[in] disposal The disposal method to convert. + * \return String representation of given disposal method. + */ +const char *nsgif_str_disposal(enum nsgif_disposal disposal); + +/** + * Information about a GIF frame. + */ +typedef struct nsgif_frame_info { + /** whether the frame should be displayed/animated */ + bool display; + + /** Disposal method for previous frame; affects plotting */ + uint8_t disposal; + /** delay (in cs) before animating the frame */ + uint32_t delay; + + /** Frame's redraw rectangle. */ + nsgif_rect rect; +} nsgif_frame_info_t; + +/** * Get information about a GIF from an NSGIF object. * * \param[in] gif The NSGIF object to get info for. @@ -277,10 +330,15 @@ nsgif_error nsgif_reset( const nsgif_info_t *nsgif_get_info(const nsgif *gif); /** - * Free a NSGIF object. + * Get information about a GIF from an NSGIF object. * - * \param[in] gif The NSGIF to free. + * \param[in] gif The NSGIF object to get frame info for. + * \param[in] frame The frame number to get info for. + * + * \return The gif frame info, or NULL on error. */ -void nsgif_destroy(nsgif *gif); +const nsgif_frame_info_t *nsgif_get_frame_info( + const nsgif *gif, + uint32_t frame); #endif |