#include <stdint.h>
#include <stdbool.h>
#include <inttypes.h>

Include dependency graph for nsgif.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	nsgif_rect

struct	nsgif_bitmap_cb_vt

struct	nsgif_info

struct	nsgif_frame_info

Macros
#define	NSGIF_INFINITE (UINT32_MAX)

#define	NSGIF_MAX_COLOURS 256

Typedefs
typedef struct nsgif	nsgif_t

typedef struct nsgif_rect	nsgif_rect_t

typedef enum nsgif_bitmap_fmt	nsgif_bitmap_fmt_t

typedef void	nsgif_bitmap_t

typedef struct nsgif_bitmap_cb_vt	nsgif_bitmap_cb_vt

typedef struct nsgif_info	nsgif_info_t

typedef struct nsgif_frame_info	nsgif_frame_info_t

Functions
const char *	nsgif_strerror (nsgif_error err)

nsgif_error	nsgif_create (const nsgif_bitmap_cb_vt bitmap_vt, nsgif_bitmap_fmt_t bitmap_fmt, nsgif_t *gif_out)

void	nsgif_destroy (nsgif_t *gif)

nsgif_error	nsgif_data_scan (nsgif_t gif, size_t size, const uint8_t data)

void	nsgif_data_complete (nsgif_t *gif)

nsgif_error	nsgif_frame_prepare (nsgif_t gif, nsgif_rect_t area, uint32_t delay_cs, uint32_t frame_new)

nsgif_error	nsgif_frame_decode (nsgif_t gif, uint32_t frame, nsgif_bitmap_t *bitmap)

nsgif_error	nsgif_reset (nsgif_t *gif)

const char *	nsgif_str_disposal (enum nsgif_disposal disposal)

const nsgif_info_t *	nsgif_get_info (const nsgif_t *gif)

const nsgif_frame_info_t *	nsgif_get_frame_info (const nsgif_t *gif, uint32_t frame)

void	nsgif_global_palette (const nsgif_t gif, uint32_t table[NSGIF_MAX_COLOURS], size_t entries)

bool	nsgif_local_palette (const nsgif_t gif, uint32_t frame, uint32_t table[NSGIF_MAX_COLOURS], size_t entries)

void	nsgif_set_frame_delay_behaviour (nsgif_t *gif, uint16_t delay_min, uint16_t delay_default)

Detailed Description

Interface to progressive animated GIF file decoding.

Macro Definition Documentation

◆ NSGIF_INFINITE

#define NSGIF_INFINITE (UINT32_MAX)

Representation of infinity.

◆ NSGIF_MAX_COLOURS

#define NSGIF_MAX_COLOURS 256

Maximum colour table size

Typedef Documentation

◆ nsgif_bitmap_cb_vt

typedef struct nsgif_bitmap_cb_vt nsgif_bitmap_cb_vt

Bitmap callbacks function table

◆ nsgif_bitmap_fmt_t

typedef enum nsgif_bitmap_fmt nsgif_bitmap_fmt_t

NSGIF nsgif_bitmap_t pixel format.

All pixel formats are 32 bits per pixel (bpp). The different formats allow control over the ordering of the colour channels. All colour channels are 8 bits wide.

Note that the GIF file format only supports an on/off mask, so the alpha (A) component (opacity) will always have a value of 0 (fully transparent) or 255 (fully opaque).

◆ nsgif_bitmap_t

typedef void nsgif_bitmap_t

Client bitmap type.

These are client-created and destroyed, via the nsgif_bitmap_cb_vt callbacks, but they are owned by a nsgif_t.

See nsgif_bitmap_fmt for pixel format information.

The bitmap may have a row_span greater than the bitmap width, but the difference between row span and width must be a whole number of pixels (a multiple of four bytes).

◆ nsgif_frame_info_t

typedef struct nsgif_frame_info nsgif_frame_info_t

Information about a GIF frame.

◆ nsgif_info_t

typedef struct nsgif_info nsgif_info_t

Information about a GIF.

◆ nsgif_rect_t

typedef struct nsgif_rect nsgif_rect_t

LibNSGIF rectangle structure.

Top left coordinate is (x0, y0).
Width is x1 - x0.
Height is y1 - y0.
Units are pixels.

◆ nsgif_t

typedef struct nsgif nsgif_t

Opaque type used by LibNSGIF to represent a GIF object in memory.

Enumeration Type Documentation

◆ nsgif_bitmap_fmt

enum nsgif_bitmap_fmt

NSGIF nsgif_bitmap_t pixel format.

All pixel formats are 32 bits per pixel (bpp). The different formats allow control over the ordering of the colour channels. All colour channels are 8 bits wide.

Note that the GIF file format only supports an on/off mask, so the alpha (A) component (opacity) will always have a value of 0 (fully transparent) or 255 (fully opaque).

Enumerator
NSGIF_BITMAP_FMT_R8G8B8A8	Bite-wise RGBA: Byte order: 0xRR, 0xGG, 0xBB, 0xAA.
NSGIF_BITMAP_FMT_B8G8R8A8	Bite-wise BGRA: Byte order: 0xBB, 0xGG, 0xRR, 0xAA.
NSGIF_BITMAP_FMT_A8R8G8B8	Bite-wise ARGB: Byte order: 0xAA, 0xRR, 0xGG, 0xBB.
NSGIF_BITMAP_FMT_A8B8G8R8	Bite-wise ABGR: Byte order: 0xAA, 0xBB, 0xGG, 0xRR.
NSGIF_BITMAP_FMT_RGBA8888	32-bit RGBA (0xRRGGBBAA). On little endian host, same as NSGIF_BITMAP_FMT_A8B8G8R8. On big endian host, same as NSGIF_BITMAP_FMT_R8G8B8A8.
NSGIF_BITMAP_FMT_BGRA8888	32-bit BGRA (0xBBGGRRAA). On little endian host, same as NSGIF_BITMAP_FMT_A8R8G8B8. On big endian host, same as NSGIF_BITMAP_FMT_B8G8R8A8.
NSGIF_BITMAP_FMT_ARGB8888	32-bit ARGB (0xAARRGGBB). On little endian host, same as NSGIF_BITMAP_FMT_B8G8R8A8. On big endian host, same as NSGIF_BITMAP_FMT_A8R8G8B8.
NSGIF_BITMAP_FMT_ABGR8888	32-bit BGRA (0xAABBGGRR). On little endian host, same as NSGIF_BITMAP_FMT_R8G8B8A8. On big endian host, same as NSGIF_BITMAP_FMT_A8B8G8R8.

◆ nsgif_disposal

enum nsgif_disposal

Frame disposal method.

Clients do not need to know about this, it is provided purely for dumping raw information about GIF frames.

Enumerator
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.

◆ nsgif_error

enum nsgif_error

LibNSGIF return codes.

Enumerator
NSGIF_OK	Success.
NSGIF_ERR_OOM	Out of memory error.
NSGIF_ERR_DATA	GIF source data is invalid, and no frames are recoverable.
NSGIF_ERR_BAD_FRAME	Frame number is not valid.
NSGIF_ERR_DATA_FRAME	GIF source data contained an error in a frame.
NSGIF_ERR_END_OF_DATA	Unexpected end of GIF source data.
NSGIF_ERR_DATA_COMPLETE	Can't supply more data after calling nsgif_data_complete.
NSGIF_ERR_FRAME_DISPLAY	The current frame cannot be displayed.
NSGIF_ERR_ANIMATION_END	Indicates an animation is complete, and nsgif_reset must be called to restart the animation from the beginning.

Function Documentation

◆ nsgif_create()

nsgif_error nsgif_create	(	const nsgif_bitmap_cb_vt *	bitmap_vt,
		nsgif_bitmap_fmt_t	bitmap_fmt,
		nsgif_t **	gif_out
	)

Create the NSGIF object.

Parameters

[in]	bitmap_vt	Bitmap operation functions v-table.
[in]	bitmap_fmt	Bitmap pixel format specification.
[out]	gif_out	Return nsgif_t object on success.

Returns: NSGIF_OK on success, or appropriate error otherwise.

◆ nsgif_data_complete()

void nsgif_data_complete ( nsgif_t * gif )

Tell libnsgif that all the gif data has been provided.

Call this after calling nsgif_data_scan with the the entire GIF source data. You can call nsgif_data_scan multiple times up until this is called, and after this is called, nsgif_data_scan will return an error.

You can decode a GIF before this is called, however, it will fail to decode any truncated final frame data and will not perform loops when driven via nsgif_frame_prepare (because it doesn't know if there will be more frames supplied in future data).

Parameters

[in] gif The nsgif_t object.

◆ nsgif_data_scan()

nsgif_error nsgif_data_scan	(	nsgif_t *	gif,
		size_t	size,
		const uint8_t *	data
	)

Scan the source image data.

This is used to feed the source data into LibNSGIF. This must be called before calling nsgif_frame_decode.

It can be called multiple times with, with increasing sizes. If it is called several times, as more data is available (e.g. slow network fetch) the data already given to nsgif_data_scan must be provided each time.

Once all the data has been provided, call nsgif_data_complete.

For example, if you call nsgif_data_scan with 25 bytes of data, and then fetch another 10 bytes, you would need to call nsgif_data_scan with a size of 35 bytes, and the whole 35 bytes must be contiguous memory. It is safe to realloc the source buffer between calls to nsgif_data_scan. (The actual data pointer is allowed to be different.)

If an error occurs, all previously scanned frames are retained.

Note that an error returned from this function is purely informational. So long as at least one frame is available, you can display frames.

Parameters

[in]	gif	The nsgif_t object.
[in]	size	Number of bytes in data.
[in]	data	Raw source GIF data.

Returns: NSGIF_OK on success, or appropriate error otherwise.

◆ nsgif_destroy()

void nsgif_destroy ( nsgif_t * gif )

Free a NSGIF object.

Parameters

[in] gif The NSGIF to free.

◆ nsgif_frame_decode()

nsgif_error nsgif_frame_decode	(	nsgif_t *	gif,
		uint32_t	frame,
		nsgif_bitmap_t **	bitmap
	)

Decodes a GIF frame.

Parameters

[in]	gif	The nsgif_t object.
[in]	frame	The frame number to decode.
[out]	bitmap	On success, returns pointer to the client-allocated, nsgif-owned client bitmap structure.

Returns: NSGIF_OK on success, or appropriate error otherwise.

◆ nsgif_frame_prepare()

nsgif_error nsgif_frame_prepare	(	nsgif_t *	gif,
		nsgif_rect_t *	area,
		uint32_t *	delay_cs,
		uint32_t *	frame_new
	)

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 NSGIF_INFINITE, indicating that the frame should be shown forever.

Note that if nsgif_data_complete has not been called on this gif, animated GIFs will not loop back to the start. Instead it will return NSGIF_ERR_END_OF_DATA.

Parameters

[in]	gif	The nsgif_t object.
[out]	area	The area in pixels that must be redrawn.
[out]	delay_cs	Time to wait after frame_new before next frame in cs.
[out]	frame_new	The frame to decode.

Returns: NSGIF_OK on success, or appropriate error otherwise.

◆ nsgif_get_frame_info()

const nsgif_frame_info_t * nsgif_get_frame_info	(	const nsgif_t *	gif,
		uint32_t	frame
	)

Get information about a GIF from an nsgif_t object.

Parameters

[in]	gif	The nsgif_t object to get frame info for.
[in]	frame	The frame number to get info for.

Returns: The gif frame info, or NULL on error.

◆ nsgif_get_info()

const nsgif_info_t * nsgif_get_info ( const nsgif_t * gif )

Get information about a GIF from an nsgif_t object.

Parameters

[in] gif The nsgif_t object to get info for.

Returns: The gif info, or NULL on error.

◆ nsgif_global_palette()

void nsgif_global_palette	(	const nsgif_t *	gif,
		uint32_t	table[NSGIF_MAX_COLOURS],
		size_t *	entries
	)

Get the global colour palette.

If the GIF has no global colour table, this will return the default colour palette.

Colours in same pixel format as nsgif_bitmap_t.

Parameters

[in]	gif	The nsgif_t object.
[out]	table	Client buffer to hold the colour table.
[out]	entries	The number of used entries in the colour table.

◆ nsgif_local_palette()

bool nsgif_local_palette	(	const nsgif_t *	gif,
		uint32_t	frame,
		uint32_t	table[NSGIF_MAX_COLOURS],
		size_t *	entries
	)

Get the local colour palette for a frame.

Frames may have no local palette. In this case they use the global palette. This function returns false if the frame has no local palette.

Colours in same pixel format as nsgif_bitmap_t.

Parameters

[in]	gif	The nsgif_t object.
[in]	frame	The frame to get the palette for.
[out]	table	Client buffer to hold the colour table.
[out]	entries	The number of used entries in the colour table.

Returns: true if a palette is returned, false otherwise.

◆ nsgif_reset()

nsgif_error nsgif_reset ( nsgif_t * gif )

Reset a GIF animation.

Some animations are only meant to loop N times, and then show the final frame forever. This function resets the loop and frame counters, so that the animation can be replayed without the overhead of recreating the nsgif_t object and rescanning the raw data.

Parameters

[in] gif A nsgif_t object.

Returns: NSGIF_OK on success, or appropriate error otherwise.

◆ nsgif_set_frame_delay_behaviour()

void nsgif_set_frame_delay_behaviour	(	nsgif_t *	gif,
		uint16_t	delay_min,
		uint16_t	delay_default
	)

Configure handling of small frame delays.

Historically people created GIFs with a tiny frame delay, however the slow hardware of the time meant they actually played much slower. As computers sped up, to prevent animations playing faster than intended, decoders came to ignore overly small frame delays.

By default a nsgif_frame_prepare() managed animation will override frame delays of less than 2 centiseconds with a default frame delay of 10 centiseconds. This matches the behaviour of web browsers and other renderers.

Both the minimum and the default values can be overridden for a given GIF by the client. To get frame delays exactly as specified by the GIF file, set delay_min to zero.

Note that this does not affect the frame delay in the frame info (nsgif_frame_info_t) structure, which will always contain values specified by the GIF.

Parameters

[in]	gif	The nsgif_t object to configure.
[in]	delay_min	The minimum frame delay in centiseconds.
[in]	delay_default	The delay to use if a frame delay is less than `delay_min`.

◆ nsgif_str_disposal()

const char * nsgif_str_disposal ( enum nsgif_disposal disposal )

Convert a disposal method to a string.

Parameters

[in] disposal The disposal method to convert.

Returns: String representation of given disposal method.

◆ nsgif_strerror()

const char * nsgif_strerror ( nsgif_error err )

Convert an error code to a string.

Parameters

[in] err The error code to convert.

Returns: String representation of given error code.

Enumerations
enum	nsgif_error { NSGIF_OK , NSGIF_ERR_OOM , NSGIF_ERR_DATA , NSGIF_ERR_BAD_FRAME , NSGIF_ERR_DATA_FRAME , NSGIF_ERR_END_OF_DATA , NSGIF_ERR_DATA_COMPLETE , NSGIF_ERR_FRAME_DISPLAY , NSGIF_ERR_ANIMATION_END }

enum	nsgif_bitmap_fmt { NSGIF_BITMAP_FMT_R8G8B8A8 , NSGIF_BITMAP_FMT_B8G8R8A8 , NSGIF_BITMAP_FMT_A8R8G8B8 , NSGIF_BITMAP_FMT_A8B8G8R8 , NSGIF_BITMAP_FMT_RGBA8888 , NSGIF_BITMAP_FMT_BGRA8888 , NSGIF_BITMAP_FMT_ARGB8888 , NSGIF_BITMAP_FMT_ABGR8888 }

enum	nsgif_disposal { NSGIF_DISPOSAL_UNSPECIFIED , NSGIF_DISPOSAL_NONE , NSGIF_DISPOSAL_RESTORE_BG , NSGIF_DISPOSAL_RESTORE_PREV , NSGIF_DISPOSAL_RESTORE_QUIRK }

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ NSGIF_INFINITE

◆ NSGIF_MAX_COLOURS

Typedef Documentation

◆ nsgif_bitmap_cb_vt

◆ nsgif_bitmap_fmt_t

◆ nsgif_bitmap_t

◆ nsgif_frame_info_t

◆ nsgif_info_t

◆ nsgif_rect_t

◆ nsgif_t

Enumeration Type Documentation

◆ nsgif_bitmap_fmt

◆ nsgif_disposal

◆ nsgif_error

Function Documentation

◆ nsgif_create()

◆ nsgif_data_complete()

◆ nsgif_data_scan()

◆ nsgif_destroy()

◆ nsgif_frame_decode()

◆ nsgif_frame_prepare()

◆ nsgif_get_frame_info()

◆ nsgif_get_info()

◆ nsgif_global_palette()

◆ nsgif_local_palette()

◆ nsgif_reset()

◆ nsgif_set_frame_delay_behaviour()

◆ nsgif_str_disposal()

◆ nsgif_strerror()