GIF

GIF image and animation reading and writing support. More...

Collaboration diagram for GIF:

Data Structures
struct	gdGifInfo
	Basic information read from a GIF stream. More...
struct	gdGifFrameInfo
	Per-frame information read from a GIF animation. More...

GIF animation disposal constants
enum	{ gdDisposalUnknown , gdDisposalNone , gdDisposalRestoreBackground , gdDisposalRestorePrevious }
	GIF frame disposal methods. More...
#define	GD_GIF_DISPOSAL_UNKNOWN   gdDisposalUnknown
#define	GD_GIF_DISPOSAL_NONE   gdDisposalNone
#define	GD_GIF_DISPOSAL_RESTORE_BACKGROUND   gdDisposalRestoreBackground
#define	GD_GIF_DISPOSAL_RESTORE_PREVIOUS   gdDisposalRestorePrevious

Animated GIF reading
typedef struct gdGifReadStruct *	gdGifReadPtr
	Opaque animated GIF reader handle.
int	gdGifIsAnimated (FILE *fd)
	Test whether a seekable GIF stdio file contains more than one frame.
int	gdGifIsAnimatedCtx (gdIOCtxPtr in)
	Test whether a seekable GIF gdIOCtx contains more than one frame.
int	gdGifIsAnimatedPtr (int size, void *data)
	Test whether a GIF memory buffer contains more than one frame.
gdGifReadPtr	gdGifReadOpen (FILE *fd)
	Open an animated GIF reader from a stdio file.
gdGifReadPtr	gdGifReadOpenCtx (gdIOCtxPtr in)
	Open an animated GIF reader from a gdIOCtx.
gdGifReadPtr	gdGifReadOpenPtr (int size, void *data)
	Open an animated GIF reader from a memory buffer.
void	gdGifReadClose (gdGifReadPtr gif)
	Close an animated GIF reader.
int	gdGifReadGetInfo (gdGifReadPtr gif, gdGifInfo *info)
	Read logical screen and loop information from a GIF reader.
int	gdGifGetInfo (FILE *file, gdGifInfo *info)
	Read logical screen and loop information from a GIF stdio file.
int	gdGifGetInfoCtx (gdIOCtxPtr input, gdGifInfo *info)
	Read logical screen and loop information from a seekable gdIOCtx.
int	gdGifGetInfoPtr (int size, const void *data, gdGifInfo *info)
	Read logical screen and loop information from a GIF memory buffer.
int	gdGifReadNextFrame (gdGifReadPtr gif, gdGifFrameInfo *info, gdImagePtr *frame)
	Read the next raw GIF frame.
int	gdGifReadNextImage (gdGifReadPtr gif, gdGifFrameInfo *info, gdImagePtr *image)
	Read the next GIF frame composited onto the logical screen.

Single-frame GIF reading and writing
gdImagePtr	gdImageCreateFromGif (FILE *fd)
	Create an image from the first frame of a GIF stdio file.
gdImagePtr	gdImageCreateFromGifCtx (gdIOCtxPtr in)
	Create an image from the first frame of GIF data read through a gdIOCtx.
gdImagePtr	gdImageCreateFromGifPtr (int size, void *data)
	Create an image from the first frame of a GIF memory buffer.
void	gdImageGifCtx (gdImagePtr im, gdIOCtxPtr out)
	Write an image as GIF data to a gdIOCtx.
void	gdImageGif (gdImagePtr im, FILE *out)
	Write an image as GIF data to a stdio file.
void *	gdImageGifPtr (gdImagePtr im, int *size)
	Write an image as GIF data to a newly allocated memory buffer.

Animated GIF writing
void	gdImageGifAnimBegin (gdImagePtr im, FILE *outFile, int GlobalCM, int Loops)
	Begin writing a GIF animation to a stdio file.
void	gdImageGifAnimAdd (gdImagePtr im, FILE *outFile, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm)
	Add a frame to a GIF animation written to a stdio file.
void	gdImageGifAnimEnd (FILE *outFile)
	Finish writing a GIF animation to a stdio file.
void	gdImageGifAnimBeginCtx (gdImagePtr im, gdIOCtxPtr out, int GlobalCM, int Loops)
	Begin writing a GIF animation to a gdIOCtx.
void	gdImageGifAnimAddCtx (gdImagePtr im, gdIOCtxPtr out, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm)
	Add a frame to a GIF animation written to a gdIOCtx.
void	gdImageGifAnimEndCtx (gdIOCtxPtr out)
	Finish writing a GIF animation to a gdIOCtx.
void *	gdImageGifAnimBeginPtr (gdImagePtr im, int *size, int GlobalCM, int Loops)
	Begin writing a GIF animation to a newly allocated memory buffer.
void *	gdImageGifAnimAddPtr (gdImagePtr im, int *size, int LocalCM, int LeftOfs, int TopOfs, int Delay, int Disposal, gdImagePtr previm)
	Add a GIF animation frame to a newly allocated memory buffer.
void *	gdImageGifAnimEndPtr (int *size)
	Finish a GIF animation into a newly allocated memory buffer.

Detailed Description

GIF image and animation reading and writing support.

GIF support reads single images as palette-based gd images and writes palette-based GIF data, quantizing truecolor input when needed. Animated GIF support includes a reader for raw frames or composited images and a legacy begin/add/end writer API.

gdImagePtr im;
gdImagePtr prev = NULL;
FILE *out;
int i;
 
im = gdImageCreate(100, 100);
if (im == NULL) {
  fprintf(stderr, "Unable to create image\n");
  exit(1);
}
 
gdImageColorAllocate(im, 255, 255, 255);
 
out = fopen("anim.gif", "wb");
if (out == NULL) {
   fprintf(stderr, "Unable to open output file\n");
   gdImageDestroy(im);
   exit(1);
}
 
gdImageGifAnimBegin(im, out, 1, -1);
for (i = 0; i < 20; i++) {
  gdImagePtr frame;
  int color;
 
  frame = gdImageCreate(100, 100);
  if (frame == NULL) {
    break;
  }
  gdImageColorAllocate(frame, 255, 255, 255);
  color = gdImageColorAllocate(frame, i * 10, 0, 255 - i * 10);
  gdImageFilledRectangle(frame, 10 + i, 10 + i, 40 + i, 40 + i, color);
  gdImageGifAnimAdd(frame, out, 1, 0, 0, 10, GD_GIF_DISPOSAL_NONE, prev);
  if (prev != NULL) {
    gdImageDestroy(prev);
  }
  prev = frame;
}
if (prev != NULL) {
  gdImageDestroy(prev);
}
gdImageGifAnimEnd(out);
fclose(out);
gdImageDestroy(im);

Macro Definition Documentation

GD_GIF_DISPOSAL_NONE

#define GD_GIF_DISPOSAL_NONE   gdDisposalNone

Alias for gdDisposalNone.

GD_GIF_DISPOSAL_RESTORE_BACKGROUND

#define GD_GIF_DISPOSAL_RESTORE_BACKGROUND   gdDisposalRestoreBackground

Alias for gdDisposalRestoreBackground.

GD_GIF_DISPOSAL_RESTORE_PREVIOUS

#define GD_GIF_DISPOSAL_RESTORE_PREVIOUS   gdDisposalRestorePrevious

Alias for gdDisposalRestorePrevious.

GD_GIF_DISPOSAL_UNKNOWN

#define GD_GIF_DISPOSAL_UNKNOWN   gdDisposalUnknown

Alias for gdDisposalUnknown.

Enumeration Type Documentation

anonymous enum

anonymous enum

GIF frame disposal methods.

Enumerator
gdDisposalUnknown	Unknown disposal method; not recommended for writing.
gdDisposalNone	Preserve previous frame contents.
gdDisposalRestoreBackground	Restore the frame area to the background color.
gdDisposalRestorePrevious	Restore the frame area to its previous contents.

Function Documentation

gdGifGetInfo()

int gdGifGetInfo	(	FILE *	file,
		gdGifInfo *	info
	)

Read logical screen and loop information from a GIF stdio file.

The input stream position is restored before returning.

gdGifGetInfoCtx()

int gdGifGetInfoCtx	(	gdIOCtxPtr	input,
		gdGifInfo *	info
	)

Read logical screen and loop information from a seekable gdIOCtx.

The input context position is restored before returning.

gdGifIsAnimated()

int gdGifIsAnimated

(

FILE *

fd

)

Test whether a seekable GIF stdio file contains more than one frame.

Parameters

fd	Pointer to the input FILE stream.

Returns

Returns 1 if animated, 0 if readable but not animated, or -1 on error.

gdGifIsAnimatedCtx()

int gdGifIsAnimatedCtx

(

gdIOCtxPtr

in

)

Test whether a seekable GIF gdIOCtx contains more than one frame.

Parameters

in	Pointer to the gdIOCtx input context.

Returns

Returns 1 if animated, 0 if readable but not animated, or -1 on error.

gdGifIsAnimatedPtr()

int gdGifIsAnimatedPtr	(	int	size,
		void *	data
	)

Test whether a GIF memory buffer contains more than one frame.

Parameters

size	Size of the GIF memory buffer in bytes.
data	Pointer to the GIF memory buffer.

Returns

Returns 1 if animated, 0 if readable but not animated, or -1 on error.

gdGifReadClose()

void gdGifReadClose

(

gdGifReadPtr

gif

)

Close an animated GIF reader.

Parameters

gif	The GIF reader to close.

gdGifReadGetInfo()

int gdGifReadGetInfo	(	gdGifReadPtr	gif,
		gdGifInfo *	info
	)

Read logical screen and loop information from a GIF reader.

Parameters

gif	The GIF reader.
info	Pointer to the gdGifInfo structure to populate.

Returns

Returns 1 on success, or 0 on failure.

gdGifReadNextFrame()

int gdGifReadNextFrame	(	gdGifReadPtr	gif,
		gdGifFrameInfo *	info,
		gdImagePtr *	frame
	)

Read the next raw GIF frame.

Parameters

gif	The GIF reader.
info	Pointer to a gdGifFrameInfo structure to populate, or NULL.
frame	Pointer to receive a caller-owned raw frame image, or NULL to skip receiving the image.

Returns

Returns 1 when a frame is read, 0 at end of stream, or -1 on error.

gdGifReadNextImage()

int gdGifReadNextImage	(	gdGifReadPtr	gif,
		gdGifFrameInfo *	info,
		gdImagePtr *	image
	)

Read the next GIF frame composited onto the logical screen.

Parameters

gif	The GIF reader.
info	Pointer to a gdGifFrameInfo structure to populate, or NULL.
image	Pointer to receive a caller-owned composited image, or NULL to skip receiving the image.

Returns

Returns 1 when an image is read, 0 at end of stream, or -1 on error.

gdGifReadOpen()

gdGifReadPtr gdGifReadOpen

(

FILE *

fd

)

Open an animated GIF reader from a stdio file.

Parameters

fd	Pointer to the input FILE stream.

Returns

Returns a gdGifReadPtr on success, or NULL on failure. Close it with gdGifReadClose().

gdGifReadOpenCtx()

gdGifReadPtr gdGifReadOpenCtx

(

gdIOCtxPtr

in

)

Open an animated GIF reader from a gdIOCtx.

Parameters

in	Pointer to the gdIOCtx input context. The reader does not take ownership of this context.

Returns

Returns a gdGifReadPtr on success, or NULL on failure. Close it with gdGifReadClose().

gdGifReadOpenPtr()

gdGifReadPtr gdGifReadOpenPtr	(	int	size,
		void *	data
	)

Open an animated GIF reader from a memory buffer.

Parameters

size	Size of the GIF memory buffer in bytes.
data	Pointer to the GIF memory buffer.

Returns

Returns a gdGifReadPtr on success, or NULL on failure. Close it with gdGifReadClose().

gdImageCreateFromGif()

gdImagePtr gdImageCreateFromGif

(

FILE *

fd

)

Create an image from the first frame of a GIF stdio file.

Parameters

fd	Pointer to the input FILE stream.

Returns

Returns a caller-owned gdImagePtr on success, or NULL on failure.

gdImageCreateFromGifCtx()

gdImagePtr gdImageCreateFromGifCtx

(

gdIOCtxPtr

in

)

Create an image from the first frame of GIF data read through a gdIOCtx.

Parameters

in	Pointer to the gdIOCtx input context.

Returns

Returns a caller-owned gdImagePtr on success, or NULL on failure.

gdImageCreateFromGifPtr()

gdImagePtr gdImageCreateFromGifPtr	(	int	size,
		void *	data
	)

Create an image from the first frame of a GIF memory buffer.

Parameters

size	Size of the GIF memory buffer in bytes.
data	Pointer to the GIF memory buffer.

Returns

Returns a caller-owned gdImagePtr on success, or NULL on failure.

gdImageGif()

void gdImageGif	(	gdImagePtr	im,
		FILE *	out
	)

Write an image as GIF data to a stdio file.

Parameters

im	The image to write.
out	The stdio file to write the GIF data to.

gdImageGifAnimAdd()

void gdImageGifAnimAdd	(	gdImagePtr	im,
		FILE *	outFile,
		int	LocalCM,
		int	LeftOfs,
		int	TopOfs,
		int	Delay,
		int	Disposal,
		gdImagePtr	previm
	)

Add a frame to a GIF animation written to a stdio file.

Parameters

im	The frame image to add.
outFile	The stdio file to write to.
LocalCM	Local color table flag: 1 to write one, 0 to use the global color table, or -1 for the default.
LeftOfs	Frame left offset on the logical screen.
TopOfs	Frame top offset on the logical screen.
Delay	Frame delay in hundredths of a second.
Disposal	One of the GD_GIF_DISPOSAL_* constants.
previm	Previous frame image for built-in optimization, or NULL.

gdImageGifAnimAddCtx()

void gdImageGifAnimAddCtx	(	gdImagePtr	im,
		gdIOCtxPtr	out,
		int	LocalCM,
		int	LeftOfs,
		int	TopOfs,
		int	Delay,
		int	Disposal,
		gdImagePtr	previm
	)

Add a frame to a GIF animation written to a gdIOCtx.

Parameters

im	The frame image to add.
out	The gdIOCtx to write to.
LocalCM	Local color table flag: 1 to write one, 0 to use the global color table, or -1 for the default.
LeftOfs	Frame left offset on the logical screen.
TopOfs	Frame top offset on the logical screen.
Delay	Frame delay in hundredths of a second.
Disposal	One of the GD_GIF_DISPOSAL_* constants.
previm	Previous frame image for built-in optimization, or NULL.

gdImageGifAnimAddPtr()

void * gdImageGifAnimAddPtr	(	gdImagePtr	im,
		int *	size,
		int	LocalCM,
		int	LeftOfs,
		int	TopOfs,
		int	Delay,
		int	Disposal,
		gdImagePtr	previm
	)

Add a GIF animation frame to a newly allocated memory buffer.

Parameters

im	The frame image to add.
size	Pointer to an integer that receives the returned buffer size.
LocalCM	Local color table flag: 1 to write one, 0 to use the global color table, or -1 for the default.
LeftOfs	Frame left offset on the logical screen.
TopOfs	Frame top offset on the logical screen.
Delay	Frame delay in hundredths of a second.
Disposal	One of the GD_GIF_DISPOSAL_* constants.
previm	Previous frame image for built-in optimization, or NULL.

Returns

A pointer to the newly allocated GIF animation frame data, or NULL on failure. Free the returned buffer with gdFree().

gdImageGifAnimBegin()

void gdImageGifAnimBegin	(	gdImagePtr	im,
		FILE *	outFile,
		int	GlobalCM,
		int	Loops
	)

Begin writing a GIF animation to a stdio file.

Parameters

im	Reference image used for logical screen size, interlace flag, and optional global color table.
outFile	The stdio file to write to.
GlobalCM	Global color table flag: 1 to write one, 0 to omit it, or -1 for the default.
Loops	Loop count: 0 for infinite looping, -1 to omit the loop extension, or a positive finite loop count.

gdImageGifAnimBeginCtx()

void gdImageGifAnimBeginCtx	(	gdImagePtr	im,
		gdIOCtxPtr	out,
		int	GlobalCM,
		int	Loops
	)

Begin writing a GIF animation to a gdIOCtx.

Parameters

im	Reference image used for logical screen size, interlace flag, and optional global color table.
out	The gdIOCtx to write to.
GlobalCM	Global color table flag: 1 to write one, 0 to omit it, or -1 for the default.
Loops	Loop count: 0 for infinite looping, -1 to omit the loop extension, or a positive finite loop count.

gdImageGifAnimBeginPtr()

void * gdImageGifAnimBeginPtr	(	gdImagePtr	im,
		int *	size,
		int	GlobalCM,
		int	Loops
	)

Begin writing a GIF animation to a newly allocated memory buffer.

Parameters

im	Reference image used for logical screen size, interlace flag, and optional global color table.
size	Pointer to an integer that receives the returned buffer size.
GlobalCM	Global color table flag: 1 to write one, 0 to omit it, or -1 for the default.
Loops	Loop count: 0 for infinite looping, -1 to omit the loop extension, or a positive finite loop count.

Returns

A pointer to the newly allocated GIF animation header data, or NULL on failure. Free the returned buffer with gdFree().

gdImageGifAnimEnd()

void gdImageGifAnimEnd

(

FILE *

outFile

)

Finish writing a GIF animation to a stdio file.

Parameters

outFile

The stdio file to write to.

gdImageGifAnimEndCtx()

void gdImageGifAnimEndCtx

(

gdIOCtxPtr

out

)

Finish writing a GIF animation to a gdIOCtx.

Parameters

out	The gdIOCtx to write to.

gdImageGifAnimEndPtr()

void * gdImageGifAnimEndPtr

(

int *

size

)

Finish a GIF animation into a newly allocated memory buffer.

Parameters

size	Pointer to an integer that receives the returned buffer size.

Returns

A pointer to the newly allocated GIF animation terminator data, or NULL on failure. Free the returned buffer with gdFree().

gdImageGifCtx()

void gdImageGifCtx	(	gdImagePtr	im,
		gdIOCtxPtr	out
	)

Write an image as GIF data to a gdIOCtx.

Parameters

im	The image to write.
out	The gdIOCtx to write the GIF data to.

gdImageGifPtr()

void * gdImageGifPtr	(	gdImagePtr	im,
		int *	size
	)

Write an image as GIF data to a newly allocated memory buffer.

Parameters

im	The image to write.
size	Pointer to an integer that receives the returned buffer size.

Returns

A pointer to the newly allocated GIF data, or NULL on failure. Free the returned buffer with gdFree().